Como Usar o Arquivo .user.ini no ServBay: Guia de Configuração Local de PHP

O ServBay é um ambiente local de desenvolvimento web integrado e poderoso, desenvolvido para atender às necessidades dos desenvolvedores. Ele suporta múltiplas linguagens e stacks tecnológicos, incluindo gerenciamento flexível de versões do PHP e opções de configuração convenientes. No cotidiano do desenvolvimento, diferentes projetos podem exigir configurações distintas do PHP, como limites de tamanho de upload de arquivos, limite de memória ou níveis de relatório de erros. Alterar diretamente o arquivo global php.ini afeta todos os projetos, o que é pouco prático ao gerenciar múltiplos ambientes.

Felizmente, o PHP oferece o recurso do arquivo .user.ini, permitindo que desenvolvedores definam configurações personalizadas do PHP para diretórios específicos e seus subdiretórios, sem precisar mexer no php.ini global. O ServBay oferece suporte completo ao .user.ini, tornando simples e eficiente a personalização das configurações do PHP para projetos ou diretórios individualmente.

Este guia explica em detalhes como funciona o arquivo .user.ini, como utilizá-lo no ServBay e mostra exemplos práticos de como definir configurações PHP sob medida para projetos específicos.

Introdução ao arquivo .user.ini

O .user.ini foi introduzido no PHP 5.3.0 como uma forma mais flexível e segura de definir parâmetros do PHP em diretórios web, substituindo as antigas diretivas php_value e php_flag nos arquivos de configuração do servidor web (como o .htaccess do Apache). Ele permite que você inclua um arquivo .user.ini em qualquer diretório acessível via web, e as diretivas ali presentes só afetam os scripts PHP naquele diretório e em seus subdiretórios.

Principais Características

1. Escopo Local: As configurações definidas no .user.ini são válidas somente para o diretório onde o arquivo está localizado e para seus subdiretórios, não afetando o php.ini global do ServBay nem os demais projetos.
2. Alta Flexibilidade: Cada projeto pode ter um conjunto independente de configurações do PHP, conforme suas necessidades.
3. Fácil de Gerenciar: Não é necessário alterar arquivos de configuração globais do servidor ou do PHP, reduzindo o risco de conflitos e tornando as configurações mais independentes e portáveis.
4. Sem necessidade de reiniciar: Ao contrário das mudanças no php.ini (que geralmente exigem reiniciar o PHP-FPM ou o servidor web), alterações no .user.ini passam a valer automaticamente após um intervalo de tempo definido pela diretiva user_ini.cache_ttl (em geral 300 segundos, ou 5 minutos).

Diretivas Configuráveis

Nem todas as diretivas do PHP podem ser definidas no .user.ini. Isso depende do "modo de alteração" de cada diretiva. Apenas as diretivas marcadas como PHP_INI_USER, PHP_INI_PERDIR ou PHP_INI_ALL podem ser definidas em um .user.ini.

Entre as diretivas mais comuns que podem ser usadas no .user.ini estão:

• upload_max_filesize
• post_max_size
• memory_limit
• display_errors
• log_errors
• max_execution_time
• session.save_path
• date.timezone

Diretivas do tipo PHP_INI_SYSTEM (como extension_dir, zend_extension, disable_functions etc.) não podem ser configuradas via .user.ini. Elas só podem ser ajustadas no arquivo php.ini principal ou nas configurações do servidor web.

Consulte a documentação oficial do PHP com a lista das diretivas do ini para verificar o modo de cada diretiva.

Utilizando .user.ini no ServBay

O processo de uso do .user.ini no ServBay é bastante simples. A seguir, veja o passo a passo usando os exemplos das diretivas upload_max_filesize e memory_limit.

Vamos supor que o diretório raiz do seu site fica em /Applications/ServBay/www/ por padrão no ServBay e que você quer configurar o PHP para um projeto chamado myproject, cujo diretório web é /Applications/ServBay/www/myproject/public.

Passo 1: Identifique o Diretório Alvo

Primeiramente, decida em qual diretório deseja aplicar as configurações customizadas do PHP. Normalmente, será o diretório raiz exposto ao web server do seu projeto (por exemplo, o diretório public em projetos Laravel ou Symfony), ou algum subdiretório específico que necessite de configuração própria.

Exemplo: /Applications/ServBay/www/myproject/public

Passo 2: Crie ou Edite o Arquivo .user.ini

No diretório desejado, crie um novo arquivo chamado .user.ini (caso ele já exista, basta editá-lo). Atenção: arquivos que começam com ponto, como .user.ini, costumam ser ocultos na maioria dos sistemas de arquivos. Talvez seja necessário configurar seu gerenciador de arquivos para exibi-los.

Você pode criar o arquivo pelo terminal:

cd /Applications/ServBay/www/myproject/public
touch .user.ini

Depois, abra o .user.ini no editor de texto de sua preferência e adicione as diretivas de configuração PHP, uma por linha. Exemplo:

; Define o tamanho máximo de upload de arquivos para 20MB
upload_max_filesize = 20M

; Define o limite de memória para scripts PHP como 256MB
memory_limit = 256M

; Exibe erros (recomendado apenas em ambiente de desenvolvimento)
display_errors = On

Salve e feche o arquivo .user.ini.

Passo 3: Aguarde ou Force a Atualização da Configuração

As mudanças no .user.ini não entram em vigor imediatamente, pois o PHP faz cache desses arquivos para melhorar o desempenho. Por padrão, o tempo de validade do cache é controlado pela diretiva user_ini.cache_ttl, geralmente definida em 300 segundos (5 minutos). Após esse período o PHP lê novamente o arquivo.

Caso precise ver o efeito imediatamente, tente uma das opções abaixo (a disponibilidade pode variar conforme a versão e configuração do ServBay):

1. Reiniciar o processo PHP-FPM relevante: No painel do ServBay, localize a versão do PHP usada pelo seu site, pare e reinicie o serviço PHP-FPM correspondente.
2. Reiniciar o ServBay: Essa opção garantirá a atualização, mas interrompe todos os serviços locais.
3. Aguardar o cache expirar: Normalmente, essa é a maneira mais recomendada, a menos que a mudança seja urgente.

Passo 4: Verifique se o .user.ini Está em Funcionamento

Para conferir se as suas configurações no .user.ini estão sendo aplicadas, crie um arquivo PHP simples para exibir as informações do PHP.

No mesmo diretório onde está o .user.ini (ex. /Applications/ServBay/www/myproject/public), crie um arquivo chamado info.php com o conteúdo:

<?php
phpinfo();
?>

Salve o info.php.

Depois, acesse no navegador o endereço onde o arquivo está hospedado via ServBay. Exemplo: se você configurou o site em myproject.servbay.demo e o info.php está dentro da pasta public, acesse https://myproject.servbay.demo/info.php.

Na página do phpinfo(), procure pelas diretivas definidas no .user.ini (por exemplo, upload_max_filesize, memory_limit, display_errors). Você verá duas colunas: Master Value e Local Value.

• Master Value mostra o valor global do php.ini.
• Local Value mostra o valor efetivo para o script atual, que pode vir do .user.ini ou da configuração do servidor web.

Se o Local Value reflete o que você definiu no .user.ini (ex. 20M, 256M, On), significa que as configurações do .user.ini estão ativas.

Atenção: Após a verificação, por motivos de segurança, exclua ou restrinja o acesso ao arquivo info.php, pois ele revela informações detalhadas sobre a configuração do seu servidor.

Observações e Cuidados

• Nome e Localização do Arquivo: O nome deve ser exatamente .user.ini e ele precisa estar na pasta na qual se deseja aplicar a configuração. A configuração é propagada para todos os subdiretórios.
• Modo da Diretiva: Reforçando: somente diretivas com modo PHP_INI_USER, PHP_INI_PERDIR ou PHP_INI_ALL podem ser definidas no .user.ini. Tentar configurar uma diretiva PHP_INI_SYSTEM não surtirá efeito e frequentemente não aparecerá nenhuma mensagem de erro. Consulte a documentação oficial do PHP para conferir.
• Cache de Configuração: O tempo de cache é controlado por user_ini.cache_ttl. Se você precisar testar mudanças no .user.ini com frequência, pode definir temporariamente esse valor para algo pequeno (ex. user_ini.cache_ttl = 5) no php.ini global — lembre-se de que isso pode impactar a performance em produção. Alterações no php.ini exigem reinício do PHP-FPM.
• Prioridade das Configurações: A hierarquia das configurações do PHP é: valor padrão < php.ini (ou ini extras) < configuração via servidor web (php_value/php_flag, se usar módulos do Apache/nginx) < .user.ini < função ini_set() em scripts PHP. Assim, configurações no .user.ini sobrepõem as do php.ini, mas ainda podem ser sobrescritas por chamadas a ini_set() no código.
• Segurança: Não salve informações sensíveis no .user.ini. Mesmo que valha apenas para o diretório corrente, o arquivo está em um caminho web — por padrão não é acessível diretamente, mas sempre confira a segurança desses arquivos.

Perguntas Frequentes (FAQ)

P: Criei o arquivo .user.ini e adicionei configurações, mas elas não parecem funcionar. O que pode ser?

R: Possíveis causas incluem:

1. Nome ou local incorreto do arquivo .user.ini: Confira se ele está corretamente nomeado e colocado no diretório adequado.
2. Diretiva não suportada: Talvez você tentou ajustar uma diretiva não permitida em .user.ini (ou seja, que não seja PHP_INI_USER ou PHP_INI_PERDIR). Veja a documentação do PHP.
3. Cache não expirado: Aguarde o tempo definido em user_ini.cache_ttl (por padrão, 5 minutos) ou reinicie o PHP-FPM.
4. Erro de sintaxe: Revise se há algum erro de digitação no .user.ini.
5. Sobreposição de prioridade: O valor pode ter sido sobrescrito via função ini_set() no código.

P: Qual a diferença entre o .user.ini e o arquivo global php.ini?

R: O arquivo global php.ini afeta todo o ambiente PHP (ou todos os aplicativos de uma mesma versão do PHP), seus valores são padrões para todos os scripts (salvo sobreposição em instâncias mais específicas). O .user.ini é válido apenas para os scripts do diretório onde está (e subdiretórios), sendo limitado às diretivas permitidas. O principal benefício do .user.ini é o escopo local e a liberdade de configurar sem impactar outros projetos.

Resumo

Usar o arquivo .user.ini no ServBay é a forma recomendada para gerenciar configurações PHP específicas por projeto. Ele proporciona grande flexibilidade, permitindo customizar facilmente o ambiente PHP de acordo com as necessidades de cada projeto, sem afetar outros projetos ou as configurações globais do ServBay. Com as orientações e exemplos apresentados neste tutorial, você poderá aplicar com tranquilidade o uso de .user.ini em seus projetos no ServBay, aumentando a eficiência no desenvolvimento e a praticidade na gestão do ambiente local. O objetivo do ServBay é justamente oferecer ao desenvolvedor ferramentas locais robustas e flexíveis — e o suporte nativo ao .user.ini é a prova desse compromisso.