Compilando e Instalando Módulos PHP Personalizados no ServBay

O ServBay é um potente ambiente de desenvolvimento web local para macOS e Windows, integrando uma vasta gama de pacotes para atender às necessidades dos desenvolvedores modernos. Ele traz versões múltiplas pré-configuradas de PHP, Node.js, Python, Go, Java, bancos de dados (MySQL, PostgreSQL, MongoDB), caches (Redis) e servidores web (Caddy, Nginx, Apache), oferecendo máxima flexibilidade para adaptar o ambiente conforme as exigências dos seus projetos.

Embora o ServBay já inclua diversos módulos PHP populares, pode haver situações específicas em que você precise compilar e instalar módulos PHP adicionais, seja para ampliar funcionalidades do PHP ou integrar serviços de terceiros.

Este guia detalha o processo para compilar e instalar módulos PHP personalizados no ambiente ServBay. Usaremos como exemplo os módulos imagick (para processamento de imagens) e sqlsrv (driver do Microsoft SQL Server) para ilustrar cada etapa e ajudá-lo a adicionar as funcionalidades que deseja ao seu ambiente PHP no ServBay.

Pré-requisitos

Aviso Importante

Antes de compilar qualquer módulo PHP, o passo mais essencial é inicializar corretamente o ambiente de compilação e configurar as variáveis de ambiente conforme as diretrizes da documentação oficial do ServBay. Esse procedimento é fundamental para compilar pacotes no ServBay (incluindo módulos PHP) com sucesso. Ignorar ou executar incorretamente essa etapa, muito provavelmente, resultará em falhas na compilação, como erros de comandos, bibliotecas ou arquivos de header não encontrados.

O script de inicialização do ambiente de compilação do ServBay configura variáveis essenciais como PATH (apontando para as ferramentas de build internas do ServBay), SERVBAY_PACKAGE_FULL_PATH (diretório raiz dos pacotes do ServBay) e CPU_NUMBER (total de núcleos para compilação paralela). Essas variáveis são fundamentais para os comandos de compilação.

Para instruções detalhadas sobre como inicializar o ambiente de compilação do ServBay, consulte a documentação: Recompilando Pacotes no ServBay. Certifique-se de entender plenamente e seguir rigorosamente todas as configurações necessárias desse documento.

Antes de prosseguir com a compilação dos módulos, tenha certeza absoluta de que você efetuou corretamente a inicialização do ambiente de compilação do ServBay e que todas as variáveis de ambiente relevantes estão configuradas na sessão atual do seu terminal.

A Importância de Especificar a Versão do PHP

Um dos diferenciais do ServBay é o suporte para instalar e executar múltiplas versões do PHP no mesmo sistema. Isso oferece flexibilidade ao desenvolvedor para alternar entre diferentes ambientes conforme cada projeto. Contudo, ao compilar módulos PHP, é obrigatório proceder para uma versão específica do PHP. As ferramentas essenciais, como phpize e php-config, são intimamente vinculadas à versão do PHP alvo.

• phpize: Script para preparar o ambiente de compilação de módulos PHP. Ele lê o arquivo config.m4 e gera o script padrão configure, primeiro passo típico em compilações de softwares C/C++.
• php-config: Fornece detalhes da configuração da instalação do PHP específico, incluindo flags do compilador, diretórios de includes, diretórios de bibliotecas e o diretório de instalação das extensões. O script configure recorre ao php-config para assegurar que o módulo será construído e linkado corretamente à versão desejada do PHP.

Portanto, ao utilizar phpize, php-config ou outros comandos relativos à construção do PHP, sempre especifique o caminho absoluto referente à versão de PHP que deseja compilar o módulo.

Exemplos de Caminho

Se quiser compilar um módulo para o PHP 8.3 instalado no ServBay:

macOS:

• phpize: /Applications/ServBay/package/php/8.3/current/bin/phpize
• php-config: /Applications/ServBay/package/php/8.3/current/bin/php-config

Windows:

• phpize: C:\ServBay\package\php\8.3\current\bin\phpize
• php-config: C:\ServBay\package\php\8.3\current\bin\php-config

A escolha correta da versão garante a compatibilidade do módulo com o ambiente PHP alvo, evitando erros de compilação e problemas como "símbolo não encontrado" em tempo de execução.

Todos os exemplos deste guia utilizam o PHP 8.3 do ServBay. Substitua o caminho nos comandos pela versão de PHP correspondente à sua necessidade.

Compilando o Módulo PHP imagick

O imagick é uma extensão PHP amplamente utilizada que, baseada na poderosa biblioteca ImageMagick, oferece funcionalidades avançadas de manipulação de imagens. Com ela é possível gerar operações de redimensionamento, corte, conversão de formatos, inserção de marcas d’água e composição de imagens via PHP. Siga os passos abaixo para compilar e instalar o imagick para uma versão específica do PHP no ServBay:

Passo 1: Instalar a Biblioteca ImageMagick

O módulo imagick requer a instalação da biblioteca ImageMagick no sistema.

macOS

Recomenda-se utilizar o gerenciador de pacotes Homebrew. Caso não esteja instalado, acesse o site oficial do Homebrew para instruções.

Abra o terminal e execute para instalar o ImageMagick e seus arquivos de desenvolvimento:

brew install imagemagick

Windows

No Windows, baixe e instale manualmente o ImageMagick pelo site oficial de downloads.

Durante a instalação, selecione a opção que inclui as bibliotecas de desenvolvimento e adicione o caminho de instalação nas variáveis de ambiente do sistema.

Passo 2: Obter o Código-Fonte do Módulo imagick

Faça o download do pacote fonte do módulo imagick no site oficial do PECL. Visite a página PECL imagick, escolha a versão desejada (geralmente a mais recente e estável) e copie o link de download. Neste exemplo, usaremos a versão 3.7.0:

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

Passo 3: Extrair o Código-Fonte e Entrar no Diretório

Após o download, extraia o pacote com o comando tar e, em seguida, acesse o diretório dos fontes:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Passo 4: Preparar o Ambiente de Compilação (usando phpize)

Dentro do diretório de fontes, utilize a ferramenta phpize da versão específica do PHP. Como explicado antes, é crucial usar o caminho absoluto do phpize. Supondo PHP 8.3, e que você já definiu a variável SERVBAY_PACKAGE_FULL_PATH:

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

Caso ocorra tudo certo, o phpize irá gerar o script configure e demais arquivos necessários. O terminal exibirá mensagens indicando que o ambiente está pronto para compilação.

Passo 5: Configurar as Opções de Compilação

Execute o script configure gerado para definir as opções de compilação. Use sempre o parâmetro --with-php-config para indicar o caminho do php-config da versão alvo:

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

O script irá verificar as dependências do ImageMagick e utilizar as informações do php-config para gerar o Makefile de compilação. Em caso de erro, geralmente indica dependência não instalada ou caminho incorreto.

Passo 6: Compilar e Instalar o Módulo

Depois do Makefile gerado, inicie a compilação com o comando make e depois instale com make install. O ${CPU_NUMBER} indica o número de núcleos usados para acelerar o build:

make -j ${CPU_NUMBER}
make install

O make install copia automaticamente o módulo compilado para o diretório padrão de extensões do PHP da versão correspondente no ServBay:

• macOS: /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/
• Windows: C:\ServBay\package\php\8.3\current\lib\php\extensions\no-debug-non-zts-YYYYMMDD\

O caminho exato depende das opções de compilação e versão do PHP.

Passo 7: Habilitar o Módulo

Instalado o módulo, é preciso habilitá-lo no arquivo de configuração do PHP. O ServBay facilita esse processo via interface gráfica:

• Abra o programa ServBay
• No menu à esquerda navegue para Linguagens - PHP - PHP 8.3
• No painel direito, selecione a aba PHP, role até o final e, na seção “Parâmetros Extras”, adicione extension=imagick.so
• Clique em Salvar; o ServBay irá reiniciar automaticamente o processo do PHP e aplicar a configuração

Passo 8: Verificar o Carregamento do Módulo

Depois de habilitar o módulo, reinicie o pacote do PHP no ServBay para valer as mudanças. Use o painel de controle do ServBay para reiniciar a versão desejada do PHP, ou utilize a ferramenta de linha de comando (consulte a documentação ServBay para o comando exato).

Reiniciado o PHP, verifique via terminal se o módulo foi carregado:

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

Esse comando garante que você está usando o executável do PHP correto do ServBay. O parâmetro -m lista todos os módulos PHP carregados; se tudo der certo, a saída mostrará imagick.

Para uma verificação mais detalhada, crie um arquivo PHP (por exemplo, info.php) com o código <?php phpinfo(); ?> na pasta web root:

• macOS: /Applications/ServBay/www
• Windows: C:\ServBay\www

Acesse via navegador http://localhost/info.php ou pelo domínio configurado no ServBay. No resultado do phpinfo(), procure por "imagick" para confirmar se foi habilitado e verificar configurações e versão.

Compilando o Módulo PHP sqlsrv/pdo_sqlsrv

Os módulos sqlsrv e pdo_sqlsrv são extensões oficiais do PHP para conectar e operar com bancos de dados Microsoft SQL Server, utilizando o driver ODBC fornecido pela Microsoft. Se você precisa acessar o SQL Server via PHP no ServBay, será necessário compilar e instalar estes módulos conforme o procedimento abaixo:

Atenção: Pré-requisito importante

Antes de compilar o módulo sqlsrv, você deve instalar o driver Microsoft ODBC para SQL Server e as ferramentas relacionadas. Esses componentes não vêm com o ServBay e necessitam instalação manual.

macOS

Use o Homebrew para instalar as dependências. Se não tiver o Homebrew, visite o site oficial.

Os comandos do Homebrew para instalar o driver ODBC e as ferramentas são (pode ser preciso aceitar o EULA via variável HOMEBREW_ACCEPT_EULA=Y):

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

Geralmente, essas dependências ficam instaladas em /opt/homebrew/ (Apple Silicon) ou /usr/local/ (Intel). É preciso apontar corretamente esses caminhos na compilação.

Windows

No Windows, baixe e instale o driver ODBC para SQL Server pelo site oficial da Microsoft.

Faça o download da versão adequada, instale e certifique-se de que o driver está disponível no sistema.

Confirme que todas as dependências estão instaladas antes de tentar compilar o sqlsrv.

Dica

sqlsrv e pdo_sqlsrv são módulos separados e precisam ser compilados individualmente, mas o processo é o mesmo; abaixo usaremos sqlsrv como exemplo.

Passo 1: Instalar o Driver ODBC da Microsoft e Ferramentas

(Como detalhado acima: certifique-se de ter instalado msodbcsql18 e mssql-tools18 usando o Homebrew.)

Passo 2: Obter o Código-Fonte do Módulo sqlsrv

Baixe os fontes dos módulos sqlsrv e pdo_sqlsrv pelo site do PECL. Na página PECL sqlsrv, pegue o link de download da versão desejada. Neste exemplo, usamos a 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: Extrair o Código-Fonte e Entrar no Diretório

Descompacte o pacote e acesse o diretório:

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# Para o pdo_sqlsrv, faça os mesmos passos; aqui mostraremos somente sqlsrv.

Passo 4: Preparar o Ambiente de Compilação (usando phpize)

No diretório fonte, execute o phpize correto para a versão desejada:

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

Passo 5: Configurar as Opções de Compilação (incluindo caminhos das dependências)

Execute o script configure, mas antes configure as variáveis de ambiente LDFLAGS e CPPFLAGS para que ele encontre as bibliotecas do Homebrew. Continue utilizando o parâmetro --with-php-config para indicar a versão certa do PHP.

Adapte o caminho de acordo com seu Homebrew (Apple Silicon: /opt/homebrew, Intel: /usr/local). Exemplo para /opt/homebrew:

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # Inclui /opt/homebrew/include para garantir todos headers necessários
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS: Indica ao linker onde buscar as bibliotecas (-L/opt/homebrew/lib).
• CPPFLAGS: Indica ao pré-processador os diretórios de headers. Mantenha ${CPPFLAGS} e ${LDFLAGS} para eventuais configurações já existentes no ServBay.

Passo 6: Compilar e Instalar o Módulo

Com o Makefile gerado, compile e instale o módulo:

make -j ${CPU_NUMBER}
make install

O comando instalará os arquivos sqlsrv.so e pdo_sqlsrv.so (se compilados juntos) no diretório de extensões do PHP correspondente no ServBay.

Passo 7: Habilitar o Módulo

Após instalar, habilite os módulos pelo painel:

• Abra o ServBay
• No menu à esquerda, vá em Linguagens - PHP - PHP 8.3
• Na aba PHP, role até “Parâmetros Extras” e inclua as linhas extension=sqlsrv.so e extension=pdo_sqlsrv.so
• Clique em Salvar; o ServBay reiniciará o PHP automaticamente para aplicar as alterações

Passo 8: Verificar o Carregamento do Módulo

Após habilitar os módulos, reinicie o pacote PHP do ServBay.

Para checar se os módulos foram carregados, use:

${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

Se bem sucedida a instalação, surgirão sqlsrv e pdo_sqlsrv na lista. Use também phpinfo() para confirmação detalhada.

Perguntas Frequentes (FAQ)

• P: Recebo "Cannot find autoconf" ou erro semelhante na compilação?
  • R: Isso geralmente significa que o ambiente de compilação do ServBay não foi corretamente inicializado. Retorne à seção “pré-requisitos” e revise o passo a passo da Recompilação de Pacotes no ServBay. Certifique-se de que as ferramentas necessárias (autoconf, automake, libtool etc.) estão instaladas e corretamente referenciadas nas variáveis de ambiente. Normalmente, basta rodar o script de inicialização do ServBay e reiniciar o terminal para corrigir.
• P: O script configure falha reclamando de biblioteca ou header não encontrados?
  • R: Alguma dependência não está instalada ou o script não consegue localizar.
    • Para o imagick, confirme que o ImageMagick de desenvolvimento está instalado (no macOS: brew install imagemagick).
    • Para sqlsrv, certifique-se de que o driver ODBC (msodbcsql18) e mssql-tools18 foram instalados conforme o pré-requisito. Verifique se as variáveis LDFLAGS e CPPFLAGS estão corretas e incluem os caminhos adequados (/opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).
    • Confira se o ambiente ServBay inclui os diretórios do Homebrew no PATH, caso os binários sejam necessários; se não, adicione manualmente.
• P: Usar make ou make install causa erro?
  • R: Os motivos possíveis são:
    • Falta de dependências: Verifique no erro qual arquivo ou biblioteca está exigindo e instale conforme indicado.
    • Configuração deficiente: Revise os parâmetros do configure, em especial se --with-php-config aponta para o PHP correto do ServBay.
    • Permissões: O make install precisa gravar na pasta de extensões do PHP. Caso o script de ambiente não configure permissões corretamente, haverá falha. Tente executar com sudo make install (cuidado! Use se realmente souber o que está fazendo).
    • Código-fonte corrompido: Verifique se o pacote fonte baixado está íntegro.
• P: O arquivo .so do módulo está no diretório, já está referenciado no .ini, mas não aparece em php -m ou phpinfo()?
  • R:
    • Causa mais comum: O pacote PHP do ServBay não foi reiniciado. Após alterar o .ini, reinicie o PHP pelo painel do ServBay ou pela linha de comando; reiniciar apenas o servidor web (Caddy/Nginx) não basta, é preciso reiniciar o PHP.
    • Erro de sintaxe: Verifique se o conteúdo do .ini está correto (extension=modulonome.so).
    • Diretório de extensões incorreto: Veja se o extension_dir do php.ini aponta para a pasta correta das extensões do ServBay. O make install instala conforme o que o php-config --extension-dir retorna.
    • Arquivo do módulo corrompido ou incompatível: Recomponha o módulo, escolha o fonte certo e revise se é compatível com sua versão de PHP. Também cheque os logs do PHP no diretório logs do ServBay para mensagens sobre erro de carregamento do módulo.

Conclusão

Seguindo cuidadosamente as etapas deste guia, você conseguirá compilar e instalar módulos PHP personalizados como imagick ou sqlsrv no ambiente de desenvolvimento local ServBay. Os pontos-chave são:

1. Inicialização adequada do ambiente de compilação do ServBay – Fundamental para que todo o processo ocorra sem problemas.
2. Utilização do caminho correto para cada versão do PHP – No uso de phpize e php-config, sempre direcione para a versão desejada instalada no ServBay.
3. Instalação e configuração das dependências – Instale as bibliotecas e ferramentas necessárias conforme exigido pelo módulo; no passo do ./configure, configure variáveis de ambiente (LDFLAGS, CPPFLAGS) ou parâmetros específicos para apontar os diretórios corretos e garantir que o script localize tudo que precisa.
4. Habilitação adequada dos módulos – Edite ou crie o arquivo .ini na pasta conf.d da versão do PHP, adicionando extension=nomedomodulo.so.
5. Reinicialização do pacote PHP no ServBay – Fundamental para carregar a nova configuração e extensões.

O ServBay é um ambiente local completo e flexível para a maioria dos fluxos de desenvolvimento web profissionais. Além da compilação de módulos PHP, suporta e integra MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust e muito mais. Traz recursos úteis, como emissão de certificados SSL reais via ACME, configuração facilitada de CORS, backup automatizado de dados (incluindo configurações, sites, bancos de dados, certificados SSL), redefinição de senha root de bancos, e suporte às CAs locais ServBay User CA e ServBay Public CA para desenvolvimento HTTPS local.

Este material deve ajudá-lo a adicionar todas as funcionalidades ao seu PHP do ServBay e aprimorar seu fluxo de desenvolvimento web. Para dúvidas adicionais, consulte a documentação oficial ou recorra à comunidade ServBay.