Como Carregar Extensões PHP de Terceiros no ServBay

O ServBay é uma poderosa solução de ambiente local para desenvolvimento web, trazendo diversas extensões PHP populares já pré-instaladas. Normalmente, o usuário só precisa acessar Pacotes (Packages) -> Linguagens (Languages) -> Versão do PHP -> Extensões no ServBay para configurar e ativar módulos.

No entanto, desenvolvedores podem precisar carregar extensões PHP de terceiros ou personalizadas que não vêm incluídas por padrão. Este tutorial mostra, passo a passo, como carregar essas extensões para versões específicas do PHP no ServBay — usando o ionCube Loader como exemplo. O mesmo procedimento se aplica a outras Zend extensions ou arquivos .so compilados por você.

Nota especial sobre Zend extensions: O ionCube Loader é uma Zend extension e interage profundamente com o Zend Engine do PHP. Portanto, a configuração exige o uso da diretiva zend_extension ao invés da usual extension. Garanta que use a diretiva correta de acordo com o tipo de extensão.

Pré-requisitos

• ServBay já instalado e em execução em seu macOS.
• Permissão de administrador e acesso aos arquivos do sistema e à interface do ServBay.
• Familiaridade com o uso do Terminal do macOS.
• O arquivo de extensão PHP de terceiros (.so), compatível com a versão do PHP, arquitetura (Intel ou Apple Silicon) e opções de compilação (NTS/ZTS) corretas do ServBay.

Atenção: Compatibilidade de arquitetura é fundamental

O ServBay fornece pacotes PHP nativos para ambas as arquiteturas: Intel (x86_64) e Apple Silicon (ARM64, como os chips M1/M2/M3/M4). Ao carregar um arquivo .so, é crucial garantir que a arquitetura para a qual o arquivo foi compilado seja idêntica à do pacote PHP correspondente no ServBay.

Não é possível misturar arquivos de diferentes arquiteturas; a incompatibilidade de arquitetura fará o PHP não iniciar ou travar.

Você pode utilizar o comando file para identificar a arquitetura de um executável ou arquivo .so:

1. Verifique a arquitetura do pacote PHP do ServBay (substitua 8.3 pela sua versão):

   file /Applications/ServBay/package/php/8.3/current/bin/php

   A saída será semelhante a:

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable arm64 # Apple Silicon ARM64

   ou

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable x86_64 # Intel x86_64

2. Verifique a arquitetura do seu arquivo de extensão .so (substitua xdebug.so pelo seu arquivo):

   file xdebug.so

   Saída semelhante a:

   xdebug.so: Mach-O 64-bit bundle arm64 # Apple Silicon ARM64

   ou

   xdebug.so: Mach-O 64-bit bundle x86_64 # Intel x86_64

   Os resultados das etapas 1 e 2 devem coincidir completamente.

Passo a Passo

Passo 1: Baixe o arquivo de extensão de terceiros (exemplo ionCube Loader)

1. Acesse a página oficial de downloads do ionCube Loader. Baixe a versão adequada ao seu macOS. Para macOS ARM64 (chips Apple Silicon M series), baixe a versão Darwin ARM64. Use, por exemplo, o link abaixo (confira sempre se há uma versão mais recente no site oficial): https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
2. Após o download, você terá um arquivo .tar.gz, como ioncube_loaders_dar_arm64.tar.gz.

Passo 2: Identifique a versão do PHP de destino e o diretório de extensões do ServBay

1. Abra o aplicativo ServBay.

2. No menu lateral, clique em Pacotes (Packages) e depois em Linguagens (Languages).

3. Na lista à direita, localize a versão do PHP para instalar o ionCube Loader (por exemplo, PHP 8.3). Anote a versão.

4. Descubra o diretório de extensões (extension_dir) usado por essa versão do PHP. Normalmente, extensões .so são armazenadas aí. O caminho pode variar conforme a instalação, versão e opções do PHP.

   O método mais seguro é via Terminal:

   Abra o Terminal e execute (substitua o caminho, caso necessário):

   /Applications/ServBay/package/php/8.3/current/bin/php -i | grep extension_dir

   O terminal mostrará algo como extension_dir => /caminho/para/o/diretorio/das/extensoes. Por exemplo:

   extension_dir => /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831

   Anote o caminho exato para uso nos próximos passos.

Passo 3: Extraia e posicione o arquivo Loader

1. No Terminal, acesse a pasta de download (geralmente ~/Downloads):

   cd ~/Downloads

2. Extraia o arquivo baixado:

   tar -zxvf ioncube_loaders_dar_arm64.tar.gz

   Isso criará uma pasta chamada ioncube.

3. Acesse a pasta criada:

   cd ioncube

4. Você verá vários arquivos .so para diferentes versões do PHP. Localize o correspondente à sua versão, por exemplo, ioncube_loader_dar_8.3.so.

5. Copie esse arquivo para o extension_dir identificado no passo 2. Supondo /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/ como destino e o PHP 8.3:

   cp ioncube_loader_dar_8.3.so /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/

   • Substitua o caminho de destino pelo seu real, obtido pelo comando php -i.
   • Certifique-se de copiar o arquivo .so da versão correta e compatível com a arquitetura do PHP do ServBay.

Passo 4: Configure o PHP pelo ServBay

1. Volte ao aplicativo ServBay.

2. Certifique-se de estar em Linguagens (Languages), clique na versão do PHP a ser configurada (por exemplo, PHP 8.3).

3. Na área de configurações à direita, vá até a aba PHP.

4. Role até encontrar o campo Additional Parameters (Parâmetros Adicionais).

5. Nesse campo, adicione a seguinte linha, informando o nome do arquivo:

   zend_extension = ioncube_loader_dar_8.3.so

   • Importante: Substitua ioncube_loader_dar_8.3.so conforme o nome do arquivo que você copiou.
   • Use zend_extension, pois o ionCube Loader é uma Zend extension.
   • Como ele já está em extension_dir, apenas o nome do arquivo é suficiente, não é necessário o caminho completo.
   • Se já houver outras linhas de configuração, adicione esta em uma linha separada.

   (Imagem ilustrativa; sua interface pode ter pequenas diferenças)

6. Clique em Salvar (Save) no canto inferior direito para guardar as alterações.

Passo 5: Reinicie o serviço PHP

Após clicar em Salvar, o ServBay normalmente detecta alterações e reinicia automaticamente os serviços envolvidos (incluindo o PHP). Geralmente não é preciso reiniciar manualmente.

Passo 6: Confirme se o carregamento foi bem-sucedido

Confira se o ionCube Loader foi carregado corretamente por um destes métodos:

1. Verificação pelo terminal:

   • Abra o Terminal.

   • Rode o comando para listar os módulos carregados (ajuste o caminho do PHP, se necessário):

     /Applications/ServBay/package/php/8.3/current/bin/php -m | grep -i ioncube

     O resultado deve mostrar uma linha com ionCube Loader se tudo estiver ok.

   • Você também pode exibir a versão do PHP, que mostrará detalhes sobre o ionCube Loader logo abaixo das informações do Zend Engine:

     /Applications/ServBay/package/php/8.3/current/bin/php -v

     Exemplo de saída (os números de versão podem variar):

     PHP 8.3.16 (cli) (built: Jan 31 2025 15:09:39) (NTS)
     Copyright (c) The PHP Group
     Zend Engine v4.3.16, Copyright (c) Zend Technologies
         with the ionCube PHP Loader v14.4.0, Copyright (c) 2002-2024, by ionCube Ltd.

     Veja a linha with the ionCube PHP Loader ....

2. Verificação via função phpinfo():

   • Crie um arquivo PHP, por exemplo, info.php, na raiz do seu site (por exemplo, /Applications/ServBay/www/servbay.demo/ ou qualquer pasta configurada como site).
   • O conteúdo deve ser:

     <?php
     phpinfo();
     ?>

   • Visite este arquivo pelo navegador, por exemplo: http://servbay.demo/info.php (ajuste para o seu domínio local).
   • No resultado do phpinfo(), procure por "ionCube" (use Cmd + F ou Ctrl + F). Caso esteja instalado, um bloco específico do ionCube Loader será exibido com versão e detalhes de licença.

Se você visualizar as informações do ionCube Loader em qualquer um dos métodos acima, a extensão foi carregada com sucesso.

Problemas Comuns e Soluções

• Falha ao iniciar o PHP ou travamento: Geralmente ocorre por incompatibilidade de arquitetura entre o arquivo de extensão e o PHP instalado. Revise cuidadosamente o passo sobre compatibilidade e confira versão e opções de compilação.
• extension_dir errado: Confirme se você copiou o arquivo .so no diretório extension_dir real, obtido com o comando php -i | grep extension_dir.
• Erro na diretiva de configuração: Revise se as diretivas no campo Parâmetros Adicionais do ServBay estão corretas. Use sempre zend_extension = arquivo.so para Zend extensions e extension = arquivo.so para extensões normais. O nome do arquivo deve coincidir exatamente (maiúsculas/minúsculas).
• Problemas de permissão: O usuário que executa o ServBay (normalmente o seu usuário do macOS) deve ter permissão de leitura no arquivo .so e em sua pasta. Se você alterou permissões manualmente, revise-as.
• ServBay não reiniciou: Normalmente o ServBay reinicia automaticamente, mas se necessário, pare e reinicie os serviços manualmente ou reinicie todo o ServBay.
• ionCube não aparece no phpinfo(): Confirme que você está acessando o ambiente PHP gerenciado pelo ServBay e a versão específica configurada. Se houver várias versões ou múltiplos sites, certifique-se de estar no ambiente correto.

Resumo

Seguindo atentamente estes passos, você conseguirá carregar o ionCube Loader ou qualquer extensão PHP .so de terceiros em uma versão específica gerenciada pelo ServBay. O fundamental é: identificar corretamente a versão do PHP, localizar o diretório de extensões (extension_dir), posicionar o arquivo .so compatível e configurar seu nome corretamente na interface do ServBay em Parâmetros Adicionais (usando zend_extension ou extension). Caso enfrente problemas, consulte a seção de solução de problemas, em especial a parte sobre compatibilidade de arquitetura e caminhos de arquivo.