Gerenciamento de Versões PHP no ServBay: Guia para Configuração na Linha de Comando e Ambiente de Sites

O ServBay é uma ferramenta poderosa para desenvolvimento local de aplicações web, compatível com macOS e Windows, suportando diversas linguagens de programação e bancos de dados. Este artigo explica em detalhes como gerenciar diferentes versões do PHP para cada projeto no ServBay, tanto para execução de scripts via linha de comando quanto para servir sites específicos. Dominar o sistema de gerenciamento de versões do PHP do ServBay pode aumentar muito sua produtividade, garantindo que cada projeto possua um ambiente isolado e estável.

1. Ambiente de Linha de Comando: Gerencie a Versão do PHP por Projeto com .servbay.config

Ao criar um arquivo de configuração .servbay.config na raiz do seu projeto, você pode definir uma versão específica do PHP para cada projeto individualmente. O ServBay detecta o arquivo baseado no diretório atual do terminal, gerenciando assim o isolamento das versões entre projetos e evitando conflitos de configuração global.

1. Função e Funcionamento do .servbay.config

• Controle de versão por projeto: O ServBay permite instalar e rodar múltiplas versões do PHP simultaneamente, desde PHP 5.6 até as mais recentes, incluindo versões de desenvolvimento. Com o .servbay.config, você pode especificar com precisão a versão desejada para cada projeto.
• Troca dinâmica e sem invasão: Ao navegar para um diretório contendo o arquivo .servbay.config no terminal (usando o comando cd), o ServBay detecta o arquivo automaticamente e modifica temporariamente variáveis de ambiente da sessão atual (principalmente o PATH). Dessa forma, comandos como php e composer passam a apontar para o executável da versão definida. Ao sair do diretório, as configurações retornam ao padrão global do ServBay, sem afetar o ambiente do sistema operacional.

2. Como configurar

Na raiz do seu projeto, crie um arquivo chamado .servbay.config e adicione o seguinte conteúdo para definir a versão do PHP:

# Define a versão do PHP utilizada neste projeto (exemplo: PHP 8.3)
PHP_VERSION=8.3

# Se seu projeto também exige uma versão específica do Node.js, pode configurar junto (exemplo: Node.js 20)
# NODE_VERSION=20

• O valor do PHP_VERSION deve ser o identificador da versão instalada no ServBay, normalmente apenas o número principal ou com subversão (como 7.4, 8.1, 8.3, 8.5, etc.). Verifique se a versão definida está instalada e habilitada no ServBay.
• A configuração de NODE_VERSION segue o mesmo padrão, permitindo definir a versão do Node.js usada no projeto.

Como verificar se está funcionando:

Com o terminal aberto no diretório do projeto contendo o .servbay.config, execute:

$ pwd # Confirme que está na raiz do projeto
$ php -v  # Verifique se o PHP exibido corresponde à versão definida (ex: PHP 8.3.x)
$ composer install  # A resolução e instalação de dependências será baseada na versão do PHP ativa

Caso não veja a versão do PHP ser trocada após alterar o .servbay.config, tente fechar e abrir novamente o terminal, ou execute cd . para forçar a recarga das configurações pelo ServBay.

3. Dicas e Atenção

• Compatibilidade de versões: Se encontrar erros como "Class not found" ou "Call to undefined function" ao rodar comandos do projeto, primeiro verifique os requisitos definidos em arquivos como composer.json, e confirme se a versão especificada no .servbay.config é compatível com o projeto e suas dependências. Projetos antigos podem exigir extensões removidas nas versões mais recentes do PHP (exemplo: o mcrypt foi removido no PHP 7.2).
• Valor padrão global: Se nenhum .servbay.config for detectado no diretório atual ou superior, o ServBay utilizará a versão global definida nas configurações da interface gráfica.
• Sincronização com outros serviços: O .servbay.config também pode ser usado para especificar a versão do Node.js (NODE_VERSION), o que é útil para projetos PHP que utilizam ferramentas front-end como Webpack ou Vite em Node.js.

4. Exemplo prático

Confira um exemplo de troca automática de versões do PHP em projetos diferentes via .servbay.config:

Descrição da imagem: Ao entrar em diretórios com diferentes arquivos .servbay.config no ServBay e executar o comando php -v, o terminal alterna automaticamente para a versão do PHP especificada em cada projeto.

2. Ambiente de Sites: Configure a Versão do PHP pela Interface Gráfica do ServBay

Pela interface gráfica do ServBay, você pode definir facilmente a versão do PHP de cada site hospedado localmente. A versão do PHP para websites é independente da versão usada na linha de comando, permitindo ajustar conforme as necessidades de cada aplicação.

1. Passos para configurar

1. Abra a interface gráfica do ServBay: Inicialize o aplicativo ServBay.
2. Acesse o gerenciamento de sites: Clique na aba Sites (Websites) na barra de navegação à esquerda.
3. Adicione ou edite um site:
   • Clique no botão + no canto inferior esquerdo para criar um novo site.
   • Ou selecione um site existente para editar.
4. Configure as propriedades do site:
   • Root Directory (Diretório raiz): Defina o caminho para os arquivos do seu site. Recomenda-se utilizar um subdiretório dentro de /Applications/ServBay/www/, como /Applications/ServBay/www/nome-do-site/public (para projetos em Laravel ou Symfony).
   • Domain (Domínio): Configure o domínio local para acesso ao site, por exemplo, nome-do-site.servbay.demo. O ServBay gerencia automaticamente DNS local e certificados HTTPS (via ServBay User CA ou ServBay Public CA) para estes domínios, facilitando desenvolvimento e testes.
   • PHP Version (Versão do PHP): Escolha a versão desejada do PHP para o site através do menu suspenso. O ServBay lista todas as versões instaladas e habilitadas (como 7.4, 8.1, 8.3, 8.5, etc.).
5. Salve as configurações: Após finalizar, clique em salvar. O ServBay aplicará as mudanças automaticamente; pode ser necessário reiniciar ou atualizar o servidor web e os processos PHP-FPM relacionados.

2. Detalhes Técnicos e Benefícios

• Isolamento entre ambientes: Cada site opera com seu próprio pool de processos PHP-FPM de acordo com a versão definida, garantindo que ambientes de sites diferentes fiquem completamente isolados — falhas ou vazamentos de memória em um site não afetam outros.
• Otimização para diferentes arquiteturas: Os pacotes do ServBay (incluindo todas as versões de PHP) são otimizados tanto para ARM64 (Apple Silicon) quanto para X86_64, garantindo desempenho máximo em qualquer hardware.
• Diagnóstico de erros:
  • Consulte os logs: erros de PHP dos sites são registrados em /Applications/ServBay/var/log/php/php_error.log.
  • Status dos processos PHP-FPM: utilize a ferramenta de linha de comando servbayctl para verificar o status da versão específica do PHP (ex: servbayctl status php 8.3).

3. Integração com servidores web e bancos de dados

O ServBay é extremamente flexível, permitindo escolher diferentes servidores web e bancos de dados conforme o projeto:

• Suporte a múltiplos servidores web: A partir da versão 1.7.0, é possível alternar facilmente o servidor utilizado pelo site, com suporte a Apache, Nginx e Caddy, todos integrados com o gerenciamento de processos PHP-FPM.
• Gerenciamento de bancos de dados: Instale e gerencie múltiplas versões de bancos como MySQL, MariaDB, PostgreSQL, MongoDB e Redis. Você pode conectar o site ou projeto a bancos específicos executando no ServBay, ideal para projetos que exigem versões específicas (por exemplo, Laravel que pode trabalhar melhor com MariaDB 11.x).

3. Colaboração entre Ambientes e Boas Práticas

Compreender a independência e o funcionamento das configurações de versão do PHP tanto na linha de comando quanto no ambiente de sites do ServBay te ajuda a escolher a abordagem ideal para cada situação de desenvolvimento:

Cenário	Configuração CLI (.servbay.config)	Configuração Site (Interface do ServBay)	Observações
Manutenção de sistemas legados	Configure PHP_VERSION=5.6 na raiz do projeto	Selecione PHP 5.6 na configuração do site	Certifique-se de instalar todas as extensões do PHP necessárias para projetos antigos.
Desenvolvimento de novos projetos (ex: Laravel 11)	Configure PHP_VERSION=8.3 (ou superior) e opcionalmente NODE_VERSION=20	Adicione site novo, direcione o root para public, escolha PHP 8.3+, defina domínio e habilite HTTPS	Mantenha as ferramentas CLI (Composer, Artisan, Node.js) na mesma versão do PHP usada no site.
Teste de versões futuras do PHP	Configure PHP_VERSION=8.5 na raiz do projeto de testes	Adicione site de testes e selecione PHP 8.5	Teste antecipadamente a compatibilidade do projeto com futuras versões.
Execução de comandos Composer	Garanta que o .servbay.config especifique a versão correta	N/A (Composer é utilizado principalmente na linha de comando)	Composer será executado usando a versão ativa do PHP no terminal.

Observações Importantes

• Diferenças entre CLI e Web: Apesar de utilizar o mesmo número de versão do PHP, as configurações padrão e módulos carregados podem variar entre o ambiente de linha de comando (CLI) e o de serviço web (PHP-FPM). Por exemplo, a extensão opcache costuma ser habilitada por padrão em PHP-FPM para melhorar desempenho, mas pode estar desativada no CLI. Se notar comportamentos distintos, verifique os arquivos php.ini individuais de cada versão e os módulos ativos.
• Mantenha ServBay atualizado: Deixe o seu ServBay e o Runtime sempre nas versões mais recentes. A equipe ServBay atualiza constantemente os pacotes, fornecendo novas versões e correções de segurança para o PHP. Ao atualizar o ServBay, o Runtime geralmente é atualizado automaticamente, garantindo as últimas funcionalidades e melhorias.

Perguntas Frequentes (FAQ)

P: O que fazer se houver conflito entre as versões de PHP da linha de comando e do site?

R: Os ambientes de linha de comando (configurados via .servbay.config) e de sites (configurados pela interface do ServBay) são independentes. O .servbay.config afeta somente comandos no terminal, enquanto a configuração de site define a versão do PHP usada pelo servidor web (Apache/Nginx/Caddy) via PHP-FPM. Não há conflito direto entre eles. Apesar de ser possível usar versões diferentes no mesmo projeto — um para comandos CLI (Composer/Artisan), outro para o funcionamento do site — recomenda-se unificar para garantir consistência entre os ambientes de desenvolvimento e produção.

Conclusão

Com o uso combinado do arquivo .servbay.config e da interface gráfica, o ServBay oferece enorme flexibilidade para gerenciar versões do PHP em ambientes locais. Seja para manter projetos legados que dependem de versões antigas, ou para adotar as novidades do PHP em novas aplicações, o ServBay facilita esse processo, aproximando seu ambiente de desenvolvimento local da produção, e aprimorando tanto a produtividade quanto a estabilidade dos projetos.