Compilando e Instalando Módulos PHP Personalizados no ServBay (macOS)

O ServBay é um ambiente de desenvolvimento Web local poderoso, projetado especialmente para macOS, que integra um amplo conjunto de softwares para atender às demandas dos desenvolvedores modernos. Ele vem com PHP, Node.js, Python, Go, Java, bancos de dados (como MySQL, PostgreSQL, MongoDB), caches (Redis) e servidores web (Caddy, Nginx, Apache), suportando múltiplas versões de cada pacote para permitir flexibilidade conforme a necessidade do projeto.

Embora o ServBay já inclua muitos módulos PHP comuns, em certos cenários de desenvolvimento pode ser necessário compilar e instalar módulos PHP adicionais para expandir as funcionalidades do PHP ou integrar serviços de terceiros específicos.

Este artigo fornece um guia detalhado sobre como compilar e instalar módulos personalizados para sua versão do PHP no ambiente ServBay. Utilizaremos como exemplos os módulos populares de processamento de imagens imagick e de driver para Microsoft SQL Server sqlsrv, explicando detalhadamente cada etapa para ajudá-lo a adicionar os recursos necessários ao seu PHP no ServBay.

Pré-requisitos

Aviso Importante

Antes de compilar qualquer módulo PHP, o passo mais crítico é inicializar corretamente o ambiente de compilação e definir corretamente as variáveis de ambiente conforme as instruções da documentação oficial do ServBay. Isso é fundamental para o sucesso na compilação de qualquer pacote ServBay (incluindo módulos PHP). Caso esta etapa seja ignorada ou executada incorretamente, o processo de compilação poderá falhar, gerando erros de comando não encontrado, falta de bibliotecas ou arquivos de cabeçalho, entre outros.

O script de inicialização do ambiente de compilação do ServBay define variáveis de ambiente essenciais, tais como PATH (apontando para as ferramentas de build internas do ServBay), SERVBAY_PACKAGE_FULL_PATH (diretório raiz dos pacotes ServBay) e CPU_NUMBER (para compilação paralela com múltiplos núcleos). Estes parâmetros são indispensáveis para os comandos de compilação seguintes.

Para instruções detalhadas sobre como inicializar o ambiente de compilação do ServBay, consulte a documentação: Compilação secundária com ServBay. Certifique-se de compreender e seguir à risca todos os passos necessários.

Antes de prosseguir com a compilação dos módulos, confirme que você já iniciou corretamente o ambiente de compilação do ServBay e que as variáveis de ambiente relevantes estão devidamente configuradas em seu terminal.

Importância de Especificar a Versão do PHP

Um dos principais diferenciais do ServBay é o suporte a múltiplas versões do PHP instaladas e executadas simultaneamente no mesmo sistema. Essa flexibilidade permite alternar facilmente entre ambientes PHP para diferentes projetos. No entanto, ao compilar módulos PHP, é obrigatório compilar para a versão específica desejada. As ferramentas essenciais para preparar o ambiente de compilação e obter informações de configuração, phpize e php-config, estão intimamente ligadas à versão do PHP.

• phpize: Prepara o ambiente de compilação para extensões PHP. Ele lê o arquivo config.m4 e gera o script padrão configure, que é o primeiro passo comum na compilação de softwares C/C++.
• php-config: Fornece informações detalhadas da instalação PHP correspondente, como flags do compilador, diretórios de includes, diretórios de bibliotecas e o diretório de extensões. O script configure consulta o php-config para garantir que o módulo seja corretamente compilado e vinculado à versão especificada do PHP.

Por isso, ao usar phpize, php-config ou outros comandos relacionados à construção do PHP, sempre utilize o caminho completo para garantir que está trabalhando com a versão correta. Por exemplo, ao compilar para o PHP 8.3 instalado no ServBay, utilize /Applications/ServBay/package/php/8.3/current/bin/phpize e /Applications/ServBay/package/php/8.3/current/bin/php-config. A escolha correta garante compatibilidade e evita erros de compilação e execuções (como símbolos não encontrados).

Os exemplos deste documento consideram a versão PHP 8.3 instalada no ServBay. Ao executar os comandos, substitua os caminhos pelos correspondentes à versão do PHP que deseja utilizar.

Compilando o Módulo PHP imagick

O módulo imagick é uma das extensões mais populares do PHP, baseada na poderosa biblioteca ImageMagick de linha de comando. Com ela, é possível realizar diversas operações complexas em imagens: redimensionar, recortar, converter formatos, adicionar marcas d’água, compor imagens, entre outras. Veja o passo a passo para compilar e instalar o imagick para uma versão específica do PHP no ServBay:

Passo 1: Instale a biblioteca ImageMagick

O módulo imagick do PHP depende da biblioteca ImageMagick instalada no sistema. No macOS, recomenda-se o gerenciador de pacotes Homebrew. Caso ainda não tenha o Homebrew, acesse o site oficial para instruções de instalação.

Abra o terminal e execute:

brew install imagemagick

Passo 2: Baixe o código-fonte do imagick

Agora, obtenha o pacote fonte do módulo imagick no site oficial de extensões PHP (PECL). Vá até a página do PECL imagick, escolha a versão desejada (de preferência a mais recente e estável) e obtenha o link de download. Exemplo usando a versão 3.7.0:

wget https://pecl.php.net/get/imagick-3.7.0.tgz

Passo 3: Extraia o pacote fonte e acesse o diretório

Após o download, extraia o código-fonte com o comando tar e acesse a pasta criada:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Passo 4: Prepare o ambiente de compilação (usando phpize)

Dentro do diretório do módulo, utilize a ferramenta phpize correspondente à versão do PHP desejada. Lembre-se de usar o caminho completo (exemplo para PHP 8.3 com a variável SERVBAY_PACKAGE_FULL_PATH definida):

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

Se tudo ocorrer corretamente, o phpize irá gerar o script configure e os arquivos necessários, indicando que o ambiente está pronto.

Passo 5: Configure as opções de compilação

Execute o script configure, informando o caminho do php-config para a versão escolhida do PHP através do parâmetro --with-php-config. Assim, o build conhecerá os diretórios e flags corretos para a compilação.

./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

O script configure irá procurar as dependências, como a biblioteca e os cabeçalhos do ImageMagick, e criará o Makefile. Em caso de erro, verifique se todas as dependências estão instaladas e se os caminhos estão corretos.

Passo 6: Compile e instale o módulo

Com o Makefile criado, basta compilar com make e instalar com make install. Use a variável ${CPU_NUMBER} para compilar em paralelo, acelerando o processo.

make -j ${CPU_NUMBER}
make install

O make install irá copiar o arquivo imagick.so para o diretório de extensões correto do PHP indicado pelo caminho de instalação do ServBay (exemplo: /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/, dependente da versão/configuração).

Passo 7: Habilite o módulo

Após instalar, ative o módulo na configuração da versão desejada do PHP através da interface gráfica do ServBay:

• Abra o aplicativo do ServBay
• No menu à esquerda, navegue em Linguagens - PHP - PHP 8.3
• No painel à direita, selecione a aba PHP, vá até o final da página e, nos “Parâmetros adicionais”, insira extension=imagick.so
• Clique em Salvar; o processo do PHP será reiniciado automaticamente para carregar o novo módulo

Passo 8: Verifique o carregamento do módulo

Com o módulo habilitado, reinicie o pacote PHP do ServBay para aplicar a nova configuração. No painel do ServBay, localize o pacote PHP correspondente e clique em reiniciar, ou utilize a linha de comando conforme a documentação do ServBay.

Depois do restart, verifique pela linha de comando se o imagick foi corretamente carregado:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep imagick

Usar $SERVBAY_PACKAGE_FULL_PATH/php/8.3/current/bin/php garante que você está testando a versão específica do ServBay. O parâmetro -m lista todos os módulos ativos. Se tudo estiver certo, verá imagick no resultado.

Para uma checagem mais completa, crie um arquivo PHP (por exemplo, info.php) no diretório Web raiz (/Applications/ServBay/www por padrão), contendo <?php phpinfo(); ?>, e acesse via navegador em http://localhost/info.php. Procure por "imagick" na página para confirmar sua ativação e versões.

Compilando os módulos PHP sqlsrv/pdo_sqlsrv

Os módulos sqlsrv e pdo_sqlsrv são extensões oficiais do PHP para conexão e uso de bancos Microsoft SQL Server, baseados no driver ODBC da Microsoft. Para trabalhar com SQL Server no PHP do ServBay, siga as instruções abaixo.

Atenção: Pré-requisito importante

No macOS, para compilar e instalar os módulos sqlsrv, é imprescindível instalar o driver ODBC da Microsoft (msodbcsql18) e as ferramentas de linha de comando (mssql-tools18) manualmente através do Homebrew.

Execute:

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18

As bibliotecas costumam ser instaladas em /opt/homebrew/ (Macs com Apple Silicon) ou /usr/local/ (Macs Intel). Informe esses caminhos na configuração do build.

Dica

sqlsrv e pdo_sqlsrv são módulos distintos, devendo ser compilados separadamente, mas o processo é o mesmo. O exemplo abaixo é para sqlsrv.

Passo 1: Instale o driver e ferramentas Microsoft ODBC

(Conforme dito acima, use o Homebrew para instalar msodbcsql18 e mssql-tools18.)

Passo 2: Baixe o código-fonte do sqlsrv

Faça o download do código-fonte dos módulos sqlsrv e pdo_sqlsrv pelo site PECL. Exemplo com versão 5.12.0:

wget https://pecl.php.net/get/sqlsrv-5.12.0.tgz  # sqlsrv
wget https://pecl.php.net/get/pdo_sqlsrv-5.12.0.tgz  # pdo_sqlsrv

Passo 3: Extraia o pacote fonte e acesse o diretório

Após o download, extraia o código-fonte e entre na pasta:

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# Para pdo_sqlsrv, repita o procedimento, mas continue com sqlsrv no exemplo.

Passo 4: Prepare o ambiente de compilação (usando phpize)

Dentro do diretório, use o phpize da versão desejada do PHP:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

Passo 5: Configure as opções de compilação (incluindo caminhos de dependências)

Além de informar o caminho do php-config, é necessário apontar os diretórios do Homebrew onde foram instaladas as dependências, via variáveis de ambiente LDFLAGS e CPPFLAGS. Ajuste o caminho de acordo com a pasta do Homebrew de sua máquina.

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}"
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS: Informa ao linker onde buscar as bibliotecas. -L/opt/homebrew/lib é o caminho padrão do Homebrew para as libs.
• CPPFLAGS: Informa ao compilador onde estão os arquivos de cabeçalho. -I/opt/homebrew/opt/unixodbc/include é essencial (unixODBC é dependência do driver ODBC da Microsoft). Também inclua -I/opt/homebrew/include pelo mesmo motivo.

Passo 6: Compile e instale o módulo

Com o Makefile pronto, compile e instale:

make -j ${CPU_NUMBER}
make install

O make install irá copiar sqlsrv.so e, se buildar juntos, também pdo_sqlsrv.so para a pasta de extensões correta.

Passo 7: Habilite o módulo

Após instalar, ative os módulos na configuração da versão PHP desejada pelo painel gráfico do ServBay:

• Abra o aplicativo ServBay
• Navegue em Linguagens - PHP - PHP 8.3
• No painel direito, baixe até "Parâmetros adicionais" e adicione extension=sqlsrv.so e extension=pdo_sqlsrv.so
• Clique em Salvar, ao que o PHP será reiniciado e aplicará a nova configuração

Passo 8: Verifique o carregamento do módulo

Habilite os módulos e reinicie o pacote PHP do ServBay para aplicar as alterações.

Depois, cheque na linha de comando se os módulos estão ativos:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep sqlsrv
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep pdo_sqlsrv

Deve aparecer sqlsrv e pdo_sqlsrv no resultado. Você pode conferir também com phpinfo() para ver mais detalhes.

Perguntas Frequentes (FAQ)

• P: Durante a compilação, aparece "Cannot find autoconf" ou erro similar?
  • R: Isso indica que o ambiente de compilação do ServBay não foi corretamente inicializado. Volte à seção “Pré-requisitos” e siga o tutorial Compilação secundária com ServBay para configurar o ambiente. Confirme que ferramentas essenciais (autoconf, automake, libtool, etc.) estão instaladas e referenciadas nas variáveis de ambiente. Normalmente, executar o script de inicialização do ambiente ServBay e reiniciar o terminal resolve.
• P: O script configure falha dizendo que falta alguma biblioteca ou header?
  • R: Alguma dependência de sistema necessária não está presente ou não foi encontrada.
    • Para imagick, certifique-se de instalar a biblioteca ImageMagick via Homebrew: brew install imagemagick.
    • Para sqlsrv, obrigatoriamente instale o driver Microsoft ODBC (msodbcsql18) e mssql-tools18 via Homebrew, conforme pré-requisitos acima. Antes de rodar o ./configure, garanta que as variáveis LDFLAGS e CPPFLAGS estão corretas e incluem os diretórios necessários (/opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).
    • Certifique-se de que o ambiente de compilação do ServBay inclua o caminho do Homebrew, ou adicione o diretório bin do Homebrew ao seu PATH.
• P: Falha no make ou make install?
  • R: Vários motivos possíveis:
    • Falta de dependências: Verifique a mensagem de erro, que normalmente aponta o arquivo ou biblioteca ausente. Instale o que for solicitado.
    • Configuração errada: Volte ao passo do configure e confira os parâmetros, especialmente se o --with-php-config aponta corretamente para o PHP desejado.
    • Permissão: O make install pode precisar de permissão para copiar arquivos para o diretório de extensões do ServBay; se necessário, use sudo make install (com cautela, entenda os riscos).
    • Código-fonte corrompido: Baixe novamente o pacote caso suspeite do arquivo.
• P: O arquivo .so do módulo foi gerado, copiado para a pasta de extensões e habilitado em .ini, mas não aparece em php -m ou phpinfo()?
  • R:
    • Causa principal: O pacote PHP do ServBay não foi reiniciado. Após modificar o .ini, reinicie o PHP pelo painel ServBay ou linha de comando; só reiniciar o servidor Web (Caddy/Nginx) ou recarregar a página não basta.
    • Arquivo .ini com erro de sintaxe: confira o conteúdo (extension=modulename.so) para garantir que não há erros de digitação.
    • Caminho do diretório de extensões: cheque se o parâmetro extension_dir em php.ini aponta para a pasta correta. Use php-config --extension-dir para conferir.
    • Módulo corrompido ou incompatível: faça uma recompilação e verifique se a versão do código fonte é compatível com seu PHP. Veja os logs do PHP (em logs na pasta do ServBay) para mensagens de erro.

Conclusão

Seguindo este guia, você conseguirá compilar e instalar módulos PHP personalizados, como imagick e sqlsrv, no ambiente de desenvolvimento local do ServBay no macOS. Os principais pontos são:

1. Inicializar corretamente o ambiente de compilação do ServBay – é o pré-requisito fundamental.
2. Usar sempre o caminho correto da versão PHP desejada com phpize e php-config.
3. Atender os requisitos de dependências externas – instale bibliotecas e ferramentas requeridas (ImageMagick, ODBC, etc.) e ajuste variáveis como LDFLAGS e CPPFLAGS para apontar caminhos corretos.
4. Habilitar corretamente o módulo – criando ou editando arquivos .ini no diretório conf.d do PHP com extension=nomedomodulo.so.
5. Reiniciar o pacote PHP do ServBay – apenas assim o novo módulo será carregado.

O ServBay, além de oferecer suporte completo a diversas tecnologias (MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust e muito mais), também possui recursos como obtenção de certificados SSL reais (ACME), configuração de CORS, backup automatizado de dados, reset de senha root de banco de dados e suporte a Certificados CA locais para desenvolvimento HTTPS. Com isso, você constrói fluxos de trabalho locais poderosos, eficientes e repletos de recursos.

Esperamos que este guia ajude a expandir as capacidades do seu ambiente PHP no ServBay e otimize seu desenvolvimento Web. Caso precise de mais informações, consulte a documentação oficial do ServBay ou a comunidade de suporte.