Gerenciamento de Versões PHP no ServBay: Guia de Configuração para CLI e Ambientes de Site

O ServBay é uma poderosa ferramenta de ambiente local para desenvolvimento web, criada especialmente para macOS, com suporte a diversas linguagens e bancos de dados. Neste artigo, você vai aprender em detalhes como gerenciar diferentes versões do PHP no ServBay, seja para execução de scripts via linha de comando ou para servir sites específicos. Dominar esse mecanismo de controle das versões do PHP no ServBay aumentará significativamente sua produtividade e garantirá o isolamento e a estabilidade de cada projeto.

1. Ambiente de Linha de Comando: Gerenciando Versões PHP por Projeto com .servbay.config

Ao criar um arquivo .servbay.config no diretório raiz do seu projeto, você pode especificar qual versão do PHP será usada apenas por aquele projeto ao executar comandos via terminal. O ServBay detecta automaticamente a configuração com base no diretório atual do terminal, proporcionando isolamento de versões entre projetos e evitando conflitos de configuração global.

1.1. Função e Princípios do .servbay.config

• Controle de versão por projeto: O ServBay permite instalar e executar múltiplas versões do PHP simultaneamente, desde o PHP 5.6 até as versões mais recentes e em desenvolvimento. Através do .servbay.config, você define com precisão a versão do PHP requerida por cada projeto.
• Troca não-invasiva: Ao navegar até um diretório que contenha o arquivo .servbay.config usando o comando cd no terminal, o ServBay detecta esse arquivo e altera temporariamente as variáveis de ambiente (principalmente o PATH) da sessão do terminal, direcionando comandos como php e composer para os executáveis da versão indicada. Ao sair do diretório, o ambiente é restaurado para os padrões globais do ServBay, sem afetar o sistema como um todo.

1.2. Como Configurar

No diretório raiz do seu projeto, crie um arquivo chamado .servbay.config e insira o conteúdo abaixo para definir a versão do PHP:

# Especifique a versão do PHP do projeto (exemplo: usando PHP 8.3)
PHP_VERSION=8.3

# Se seu projeto também dependa de uma versão específica do Node.js, defina também (exemplo: usando Node.js 20)
# NODE_VERSION=20

• O valor de PHP_VERSION deve corresponder às versões já instaladas e ativadas no ServBay, geralmente informando apenas o número principal ou principal+secundário (7.4, 8.1, 8.3, 8.5, etc).
• A configuração do NODE_VERSION segue a mesma lógica, caso deseje especificar a versão do Node.js usada pelo projeto.

Como verificar se funcionou:

Abra um terminal no diretório do projeto (com .servbay.config) e execute:

$ pwd # Confirme que está no diretório raiz do projeto
$ php -v  # Verifique se a versão do PHP mostrada é a mesma definida (por exemplo: PHP 8.3.x)
$ composer install  # As dependências serão processadas usando a versão ativada do PHP

Se, após editar o .servbay.config, a versão não mudar, tente fechar e abrir o terminal novamente, ou use cd . para forçar o ServBay a recarregar a configuração.

1.3. Cuidados e Dicas Avançadas

• Compatibilidade de versões: Se aparecerem erros como "Class not found" ou "Call to undefined function", certifique-se de que tanto o projeto quanto suas dependências (como indicado no composer.json) são compatíveis com a versão do PHP definida. Alguns projetos antigos podem precisar de extensões ou recursos que foram removidos em versões recentes (por exemplo, o mcrypt foi removido a partir do PHP 7.2).
• Valor padrão global: Se não existir .servbay.config no diretório atual ou em nenhum dos diretórios ascendentes, o ServBay usará a versão global padrão configurada na interface gráfica (“Configurações”).
• Gerenciamento simultâneo de serviços: Você pode também definir a versão do Node.js (via NODE_VERSION) pelo .servbay.config, útil para projetos que usam PHP no backend e Node.js para o frontend (webpack, Vite, etc).

1.4. Exemplo de Uso

Veja um exemplo prático de troca automática de versão do PHP em diferentes projetos usando .servbay.config:

Descrição da imagem: No ServBay, ao acessar diretórios com diferentes arquivos .servbay.config e executar php -v, o terminal muda automaticamente para a versão do PHP definida no arquivo.

2. Ambiente de Site: Gerenciando Versões PHP pela Interface Gráfica do ServBay

A interface gráfica do ServBay oferece um método visual e simples para configurar diferentes versões do PHP para cada site criado no ambiente local. O ambiente PHP do site é independente do ambiente CLI, te permitindo configurar para cada projeto web aquilo que for mais adequado.

2.1. Passo a Passo da Configuração

1. Abra o ServBay: Inicie o aplicativo ServBay.
2. Acesse “Websites”: No menu do lado esquerdo, clique em Websites.
3. Adicione ou edite um site:
   • Para criar uma nova configuração, clique no botão + no canto inferior esquerdo.
   • Para editar um site já existente, selecione-o na lista.
4. Defina as propriedades do site:
   • Root Directory (diretório raiz): Selecione a pasta dos arquivos do site. Recomenda-se seguir o padrão do ServBay, usando subdiretórios de /Applications/ServBay/www/, por exemplo: /Applications/ServBay/www/nome-do-seu-site/public (para projetos Laravel ou Symfony).
   • Domain (domínio): Defina o domínio local de desenvolvimento, como nome-do-seu-site.servbay.demo. O ServBay configura automaticamente o DNS local e o certificado HTTPS (usando ServBay User CA ou ServBay Public CA), facilitando o desenvolvimento seguro.
   • PHP Version (versão do PHP): No menu de seleção, escolha qual versão do PHP esse site irá usar. O ServBay mostrará todas as versões já instaladas e habilitadas (ex: 7.4, 8.1, 8.3, 8.5...).
5. Salve as configurações: Clique no botão de salvar. O ServBay aplicará as alterações automaticamente; pode ser necessário recarregar ou reiniciar o servidor web ou os processos PHP-FPM.

2.2. Detalhes Técnicos e Vantagens

• Isolamento de serviços: Cada site roda com sua própria instância do PHP-FPM correspondente à versão selecionada. Dessa forma, sites diferentes podem ter ambientes PHP totalmente isolados—erros ou vazamentos de memória em um não afetam os demais.
• Desempenho otimizado: Os pacotes do ServBay (incluindo todas as versões de PHP) são otimizados tanto para ARM64 (Apple Silicon), quanto para x86_64, garantindo ótima performance independente do hardware.
• Resolução de problemas:
  • Verifique o log de erros do PHP: erros envolvendo o site serão registrados em /Applications/ServBay/var/log/php/php_error.log.
  • Para checar o status do PHP-FPM, utilize o comando servbayctl, exemplo: servbayctl status php 8.3.

2.3. Integração com Servidores Web e Banco de Dados

O ServBay é flexível o suficiente para que você escolha a melhor combinação de servidores web e bancos de dados conforme a necessidade do projeto:

• Servidores web: A partir do ServBay 1.7.0, é possível alternar facilmente entre Apache, Nginx e Caddy para cada site, todos integrados com os processos PHP-FPM gerenciados pelo ServBay.
• Bancos de dados: Gerencie múltiplas versões de MySQL, MariaDB, PostgreSQL, MongoDB e Redis. No próprio painel ou pelo código do projeto, conecte-se ao banco mais adequando para cada projeto (por exemplo, para certos projetos Laravel que preferem MariaDB 11.x).

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

Compreender a independência entre o gerenciamento de versões PHP no terminal e nos sites do ServBay te permite adotar as melhores estratégias de configuração em cada cenário:

Situação	Configuração CLI (.servbay.config)	Configuração Site (GUI ServBay)	Observações
Manutenção de sistemas legados	No diretório do projeto: PHP_VERSION=5.6	Selecionar PHP 5.6 na configuração do site	Verifique se a versão e as extensões requeridas estão instaladas no ServBay.
Novo projeto (ex: Laravel 11)	PHP_VERSION=8.3 (ou superior), possivelmente também NODE_VERSION=20	Crie novo site, aponte para o public do projeto, use PHP 8.3+, configure domínio e HTTPS	Mantenha as versões do CLI (Composer, Artisan, Node) e do site alinhadas.
Testes com versões futuras do PHP	No projeto de testes: PHP_VERSION=8.5	Crie site de testes com PHP 8.5	Para validar se o projeto está compatível com novas versões do PHP.
Execução de comandos Composer	O .servbay.config do diretório deve especificar a versão correta	N/A (Composer é executado pela linha de comando)	Composer usará a versão do PHP ativada no terminal.

Observações Importantes

• Diferenças entre CLI e Web: Mesmo usando o mesmo número de versão, o ambiente de linha de comando (CLI) pode apresentar configurações e extensões carregadas diferentes do ambiente web (PHP-FPM). Por exemplo, a extensão opcache normalmente só está ativa no PHP-FPM para performance, mas pode estar desativada no CLI. Se notar alguma diferença de comportamento, verifique os arquivos php.ini correspondentes de cada versão e observe quais extensões estão habilitadas.
• Mantenha o ServBay atualizado: Procure manter o ServBay e todos os seus pacotes sempre atualizados para garantir acesso a novos recursos e correções de segurança. Ao atualizar o ServBay, o Runtime também será atualizado automaticamente, entregando melhorias e novidades.

Perguntas Frequentes (FAQ)

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

R: O ambiente de linha de comando (controlado pelo .servbay.config) e o ambiente do site (interface gráfica do ServBay) são completamente independentes. O arquivo .servbay.config só afeta o terminal atual (qual executável do PHP será invocado), enquanto a configuração do site determina com qual versão de PHP-FPM o servidor web irá processar as requisições. Não há conflito direto entre eles. Você pode, se desejar, usar uma versão na linha de comando (por exemplo, para o Composer ou Artisan) e outra no web, mas o ideal é mantê-las alinhadas para garantir consistência com o ambiente de produção.

Conclusão

O ServBay oferece gerenciamento de versões PHP poderoso e flexível por meio do arquivo .servbay.config e sua interface gráfica intuitiva. Seja para manter projetos legados em versões antigas ou desenvolver novas aplicações com o PHP mais recente, o ServBay facilita todo o processo. Utilize esses recursos para tornar seu ambiente local o mais próximo possível da produção, garantindo eficiência e estabilidade no desenvolvimento.