Guia de Configuração do PHP no ServBay: Ajustando php.ini, PHP-FPM e Módulos de Extensão

O ServBay oferece aos desenvolvedores web um ambiente PHP local poderoso e flexível. Para atender diferentes necessidades de projeto, talvez seja necessário ajustar várias configurações do PHP, como limite de memória, tamanho de upload de arquivos, nível de relatório de erros ou ativar módulos de extensão específicos.

Este artigo detalha como modificar as configurações do PHP no ServBay. O ServBay recomenda — e fornece — uma interface gráfica (UI) conveniente para gerenciar essas definições. Embora conhecer a localização e a estrutura dos arquivos de configuração (como php.ini e php-fpm.conf) seja útil, é altamente recomendado fazer alterações através da interface do ServBay, garantindo persistência e compatibilidade das configurações.

Aviso Importante

Por favor, não edite manualmente os arquivos de configuração PHP gerados pelo ServBay (localizados em /Applications/ServBay/etc/php/<version>/ e seus subdiretórios). Estes arquivos são gerenciados pelo ServBay, e quaisquer alterações manuais serão sobrescritas durante atualizações, reinicializações ou outras operações. Todas as modificações devem ser feitas via interface do usuário do ServBay.

Visão Geral

No ServBay, cada versão do PHP possui seu próprio diretório de configuração. Por exemplo, os principais arquivos de configuração do PHP 8.3 ficam em /Applications/ServBay/etc/php/8.3.

Os arquivos de configuração principais incluem:

• php.ini: O arquivo principal de configuração do PHP, afetando tanto o CLI quanto o ambiente web.
• php-fpm.conf: Arquivo de configuração do PHP-FPM (FastCGI Process Manager), responsável pelo desempenho e modo de execução do PHP em servidores web como Caddy ou Nginx.
• conf.d/: Este diretório contém arquivos de configuração (.ini) de cada módulo de extensão PHP, como xdebug.ini, opcache.ini, etc.

Embora esses arquivos existam, o ServBay oferece um jeito muito mais seguro e prático de alterar suas configurações.

Configurando via Interface Gráfica do ServBay (Recomendado)

O ServBay oferece uma interface gráfica intuitiva que permite modificar facilmente os diversos parâmetros do PHP. Após salvar as alterações pelo UI, o ServBay aplicará automaticamente as mudanças e, quando necessário, reinicializará o serviço PHP (geralmente de modo autônomo), sem precisar editar arquivos ou executar comandos manualmente.

Para acessar a interface de configuração do PHP:

1. Abra a janela principal do ServBay.
2. No menu de navegação à esquerda, clique em Linguagens.
3. Na lista de linguagens de desenvolvimento, encontre e selecione a versão do PHP desejada (por exemplo, clique em PHP 8.3).
4. O painel à direita exibirá detalhes e opções de configuração dessa versão do PHP.

Um exemplo de interface de configuração do PHP é mostrado abaixo:

Geralmente, a interface é dividida em três seções: configurações do PHP-FPM, configurações do PHP (php.ini) e configurações de extensões do PHP. Veja cada uma a seguir.

Configuração do PHP FPM

Dica

As configurações do php-fpm.conf afetam principalmente o comportamento do PHP no ambiente web. As opções ajustadas no UI do ServBay aqui têm prioridade (sobrescrevem) configurações equivalentes do php.ini, porém, afetam apenas as requisições web. Estas configurações não afetam a execução do PHP via linha de comando (CLI).

O serviço web do ServBay (Caddy ou Nginx) se comunica com o PHP através do PHP-FPM. A tela de configuração do FPM permite ajustar parâmetros que afetam o desempenho e estabilidade do ambiente web, como por exemplo:

• Gerenciamento de processos (pm): Controla como o PHP-FPM gerencia processos de trabalho (ex: dynamic, static).
• Quantidade de processos (pm.max_children, pm.start_servers, etc.): Define o número máximo de processos filhos, quantos são criados na inicialização e afeta a capacidade de processamento simultâneo.
• Limite de memória (memory_limit): Esta opção sobrescreve o mesmo parâmetro definido no php.ini, mas apenas para as requisições web.
• Registro e exibição de erros: Determina caminho do log, nível de erro e se as mensagens aparecem no navegador.

Se você quiser, por exemplo, aumentar o limite de memória do PHP no ambiente web de um valor padrão (como 64M ou 128M) para 1G, bastará encontrar a opção memory_limit na seção de FPM do UI do ServBay, escolher 1G no menu suspenso e clicar em salvar. Essa mudança afetará apenas scripts PHP acessados via web; scripts rodando na linha de comando continuarão seguindo o limite de memória do php.ini.

Exemplo de comparação: Se o memory_limit estiver ajustado como 512M no php.ini e 128M na configuração do PHP-FPM:

• Scripts PHP executados no CLI terão limite de 512M.
• Scripts acessados pela web terão limite de 128M.

Configuração do php.ini

Dica

As configurações do php.ini são globais, afetando tanto o PHP em linha de comando quanto o ambiente web. No entanto, as configurações equivalentes definidas no PHP-FPM sobrescrevem o php.ini no ambiente web.

A seção de configuração do PHP corresponde às opções principais do arquivo php.ini. Aqui você encontra parâmetros gerais de execução do PHP, como:

• post_max_size: Limita o tamanho máximo de dados enviados via método POST.
• upload_max_filesize: Define o tamanho máximo de arquivos permitidos para upload.
• date.timezone: Define o fuso horário padrão utilizado pelo PHP.
• display_errors / error_reporting: Determina se erros serão exibidos na tela e quais níveis serão relatados.
• max_execution_time: Define o tempo máximo de execução de um script (em segundos).
• disable_functions / disable_classes: Desabilita funções ou classes específicas do PHP para reforçar a segurança.
• open_basedir: Restringe os diretórios do sistema de arquivos acessíveis pelo PHP. Recomenda-se armazenar todas os projetos no diretório padrão /Applications/ServBay/www do ServBay, permitindo apontar facilmente o open_basedir para este local e evitar múltiplos caminhos.

Você pode modificar esses e outros parâmetros comuns do php.ini diretamente na interface do ServBay.

Para explicações detalhadas sobre todas as opções do php.ini, consulte a documentação oficial do PHP: PHP Runtime Configuration.

Configuração dos Módulos de Extensão PHP

O ServBay já inclui muitos módulos de extensão PHP populares, abrangendo conexão com bancos de dados, cache, depuração, suporte a frameworks e muito mais. O UI do ServBay permite ativar/desativar módulos com facilidade e ajustar seus parâmetros específicos.

Algumas extensões comuns suportadas pelo ServBay, incluem (mas não se limitam a): xDebug, OPcache, ImageMagick, Redis, MongoDB, Phalcon, Swoole, entre outros. O ServBay também oferece suporte a múltiplos outros módulos para bancos de dados (MySQL, PostgreSQL, MongoDB), filas de mensagens, sistemas de cache etc.

Ativar ou desativar extensões é simples:

1. Na interface do PHP do ServBay, acesse a aba "Módulos de Extensão" (ou similar).
2. Encontre a extensão desejada (ex: xdebug).
3. Clique no botão de alternância para habilitar ou desabilitar.
4. Para módulos com opções avançadas (como xDebug), ajuste os parâmetros ao lado (ex: xdebug.mode, xdebug.client_port etc).
5. Clique em salvar para aplicar as alterações.

Para a lista completa de módulos de extensão suportados no ServBay e mais detalhes, acesse a Lista de Módulos PHP na documentação oficial (consulte sempre a versão mais recente).

Entendendo a Estrutura dos Arquivos de Configuração PHP (Não Recomendada a Modificação Manual)

Embora seja recomendado alterar as configurações somente pela interface do ServBay, entender a localização e estrutura dos arquivos ajuda a compreender melhor o funcionamento do PHP.

Os arquivos de configuração do PHP gerados pelo ServBay ficam em /Applications/ServBay/etc/php/<version>/.

• php.ini: Arquivo principal de configuração.
• php-fpm.conf: Arquivo de configuração do PHP-FPM.
• conf.d/: Pasta com arquivos .ini de cada módulo/extensão.

Exemplo de Estrutura do php.ini

O arquivo php.ini utiliza o formato INI. Veja abaixo exemplos de configuração comuns:

; Ajustar limite de memória
memory_limit = 256M

; Ajustar limite de upload de arquivos
upload_max_filesize = 50M
post_max_size = 50M

; Ajustar fuso horário
date.timezone = "Asia/Shanghai" ; Ou "UTC", "America/New_York" etc. Altere conforme necessário

; Ativar exibição de erros (apenas para desenvolvimento!)
display_errors = On
error_reporting = E_ALL

; Ajustar tempo máximo de execução
max_execution_time = 300

; Restringir caminhos acessíveis (Exemplo)
; open_basedir = /Applications/ServBay/www/:/tmp/

Exemplo de Estrutura do php-fpm.conf

O arquivo php-fpm.conf contém configurações globais e de pools de processos. O ServBay geralmente configura um pool padrão chamado www.

[global]
; Caminho do log global de erros
error_log = /Applications/ServBay/logs/php/8.3/errors.log

[www]
; Endereço e porta de escuta ou arquivo de socket
listen = /Applications/ServBay/tmp/php-cgi-8.3.sock
listen.backlog = -1
listen.allowed_clients = 127.0.0.1

; Usuário e grupo (ServBay geralmente executa com o usuário atual)
; user = servbay-demo
; group = staff

; Modo de gerenciamento de processos (static, dynamic, ondemand)
pm = dynamic
pm.max_children = 10       ; Número máximo de processos filhos
pm.start_servers = 2       ; Processos criados ao iniciar
pm.min_spare_servers = 1   ; Mínimo de processos ociosos
pm.max_spare_servers = 6   ; Máximo de processos ociosos
pm.max_requests = 1024     ; Máximo de requisições por processo antes de reiniciar (ajuda a evitar vazamento de memória)

; Ativar slow log (registra execuções acima do limite definido)
request_slowlog_timeout = 5s
slowlog = /Applications/ServBay/logs/php/8.3/slow.log

; Ajustes do PHP que sobrescrevem o php.ini (exemplo)
; php_admin_value[memory_limit] = 128M
; php_admin_flag[display_errors] = on

Exemplo de Configuração de Módulo PHP (conf.d/)

No diretório conf.d/, cada arquivo .ini carrega e ajusta uma extensão PHP específica. Veja um exemplo de xdebug.ini:

[Xdebug]
; Carregar a extensão Xdebug
zend_extension = xdebug.so

; Modo do Xdebug (debug, develop, profile, trace, coverage)
xdebug.mode=debug,develop

; Como iniciar a depuração (yes, trigger, develop)
; yes: sempre ativar
; trigger: inicia com parâmetros específicos (ex: GET/POST/cookie)
; develop: habilita apenas recursos para desenvolvimento (ex: stack trace)
xdebug.start_with_request=yes

; Host e porta para conexão do cliente (IDE)
xdebug.client_host=localhost
xdebug.client_port=39083

; Caminho do log do Xdebug
xdebug.log=/Applications/ServBay/logs/xdebug/8.3/xdebug.log

Reforçando: mesmo que você encontre esses arquivos/funções, evite modificá-los manualmente. Use sempre a interface do ServBay para as configurações.

Aplicando Alterações: Reiniciando o Serviço PHP

Após modificar configurações na UI do ServBay, normalmente as mudanças são detectadas e aplicadas automaticamente. Em alguns casos, pode ser necessário reiniciar o PHP para garantir que as alterações entrem em vigor.

Há duas formas de reiniciar o serviço PHP:

Reiniciar via Interface do ServBay

1. Abra a janela principal do ServBay.
2. No menu lateral esquerdo, clique em Pacotes.
3. Localize a versão do PHP que você alterou.
4. Clique no botão de reiniciar ao lado desta versão (normalmente um ícone de seta circular).

Reiniciar pela ferramenta de linha de comando servbayctl

Se você prefere usar o terminal, o ServBay oferece o utilitário servbayctl para gerenciar serviços, incluindo reiniciar versões específicas do PHP.

Abra o Terminal e execute o comando (substitua 8.3 pela versão adequada):

servbayctl restart php 8.3

Após executar, o ServBay reiniciará o PHP-FPM correspondente, aplicando as novas configurações.

Perguntas Frequentes (FAQ)

• P: Editei manualmente o arquivo php.ini, por que as mudanças não funcionaram ou foram revertidas?

  • R: O ServBay gerencia e gera os arquivos de configuração dos seus pacotes. Alterações manuais podem ser sobrescritas durante atualizações, reinicializações ou outras operações internas. Sempre utilize a interface do ServBay para garantir que as configurações sejam mantidas.

• P: Como aumento o limite de memória ou o tamanho de upload do PHP?

  • R: Abra o ServBay, vá em Linguagens -> escolha a versão do PHP. No FPM, ajuste o memory_limit (afeta ambiente web); no php.ini, ajuste upload_max_filesize e post_max_size (afeta globalmente, mas no web pode ser sobrescrito pelo FPM). Salve e reinicie o serviço PHP.

• P: Como habilito/configuro o Xdebug?

  • R: Abra o ServBay, vá em Linguagens -> escolha a versão do PHP. No painel de módulos/extensões, localize xdebug, habilite e ajuste as opções como xdebug.mode, xdebug.client_host, xdebug.client_port conforme necessário. Salve e reinicie o PHP.

• P: Qual a diferença entre php.ini e as configurações do PHP-FPM? Qual devo modificar?

  • R: O php.ini é o arquivo global, afetando CLI e ambiente web. As configurações do PHP-FPM (php-fpm.conf) se aplicam apenas ao ambiente web, e sobrescrevem o que estiver no php.ini, caso haja conflito no nome da opção. Em geral, altere FPM quando quiser impactar o uso web (memória, tempo de execução, exibição de erros); altere o php.ini para influenciar CLI ou configurações globais (fuso horário, funções desabilitadas etc.). O UI do ServBay separa claramente essas opções.

Resumo

O ServBay oferece, via interface gráfica, um método seguro e prático para gerenciar todas as configurações do PHP, incluindo php.ini, PHP-FPM e módulos de extensão. Alterando, salvando e reiniciando via UI do ServBay você garante que o ambiente PHP funcione de acordo com a sua necessidade. Apesar de conhecer a estrutura dos arquivos ser útil, evite alterar arquivos manualmente, pois alterações podem ser perdidas. Com o poder de configuração do ServBay, você personaliza rapidamente o melhor ambiente PHP para cada projeto.