PHP PROJ Extension — Static Build

Read in English

Extensão PHP que wrapa a biblioteca PROJ para reprojeção de coordenadas. A extensão é compilada com linkagem estática — não depende de libproj.so ou outras libs externas no SO em runtime.

Versão alvo do PHP: 8.3

Funções disponíveis

Função	Descrição
proj_get_version()	Retorna a versão da lib PROJ
proj_create_crs_to_crs(source, target)	Valida transformação entre CRS, retorna array com info ou false
proj_transform(source, target, lon, lat [, alt])	Transforma coordenadas, retorna ["x"=>..., "y"=>..., "z"=>...]
proj_transform_array(source, target, points)	Transforma array de coordenadas em lote (mais eficiente)

Docker (recomendado)

# Build, testa e exporta proj.so para ./dist/
docker compose up --build

Após o build, a pasta ./dist/ conterá:

./dist/
├── proj.so          ← extensão PHP compilada
└── proj_data/       ← dados de CRS do PROJ (proj.db etc.)

Instalação no servidor PHP

1. Copiar arquivos

# Extensão
cp dist/proj.so $(php -r "echo ini_get('extension_dir');")

# Dados do PROJ (proj.db é obrigatório para resolver EPSG codes)
sudo cp -r dist/proj_data /usr/local/share/proj

2. Configurar PHP

Adicionar ao php.ini (ou criar /etc/php/8.3/cli/conf.d/99-proj.ini):

extension=proj.so
proj.data_path=/usr/local/share/proj

A diretiva proj.data_path diz ao PROJ onde encontrar o proj.db (banco de definições de CRS como EPSG:4326, EPSG:3857 etc.). Sem isso, proj_create_crs_to_crs e proj_transform falham com "Cannot find proj.db".

Alternativas (caso não possa usar php.ini):

# Variável de ambiente do SO
export PROJ_DATA=/usr/local/share/proj

# No php-fpm pool (www.conf)
env[PROJ_DATA] = /usr/local/share/proj

# No Apache (virtualhost)
SetEnv PROJ_DATA /usr/local/share/proj

# Em runtime no PHP
putenv("PROJ_DATA=/usr/local/share/proj");

Por que é necessário?

O PROJ compila internamente o path de busca do proj.db com base no --prefix do cmake. Quando instalado direto no SO com prefix padrão /usr/local/, funciona sem configuração. Em containers ou builds com prefix customizado (ex: ./deps), o path embutido não existe no destino final — por isso precisa de proj.data_path ou PROJ_DATA.

4. Verificar

php -r 'echo "PROJ " . proj_get_version() . "\n";'
php -r 'print_r(proj_transform("EPSG:4326", "EPSG:3857", -73.9857, 40.7484));'

Build manual (sem Docker)

Requisitos

sudo apt install build-essential cmake wget php8.3-dev

1. Compilar dependências estáticas (PROJ + SQLite3)

bash build_proj.sh

Compila libproj.a e libsqlite3.a em ./deps/ sem dependências de libtiff, libcurl.

2. Compilar a extensão PHP

make clean 2>/dev/null; phpize --clean 2>/dev/null

phpize
./configure --with-proj=./deps
make

3. Verificar linkagem

ldd modules/proj.so | grep -E "proj|sqlite|tiff|curl"
# Nenhuma dessas libs deve aparecer — tudo estático

4. Testar

PROJ_DATA=./deps/share/proj php -dextension=modules/proj.so test.php

5. Instalar

sudo make install
sudo cp -r ./deps/share/proj /usr/local/share/proj
# Adicionar extension=proj.so ao php.ini
# Definir PROJ_DATA=/usr/local/share/proj (ver seção acima)

Estrutura do projeto

.
├── Dockerfile        # Multi-stage build (PHP 8.3)
├── docker-compose.yml
├── build_proj.sh     # Script para compilar PROJ+SQLite3 estáticos
├── config.m4         # Configuração de build da extensão PHP
├── php_proj.h        # Header da extensão
├── proj.c            # Implementação das funções PHP
├── test.php          # Script de teste
├── dist/             # (gerado) extensão compilada para distribuição
│   ├── proj.so       #   Extensão PHP
│   └── proj_data/    #   Dados do PROJ (proj.db etc.)
├── deps/             # (gerado) libs estáticas para build
│   ├── include/      #   Headers (proj.h, sqlite3.h)
│   ├── lib/          #   libproj.a, libsqlite3.a
│   └── share/proj/   #   proj.db
└── _build/           # (gerado) diretório temporário de build