blog
Infraestrutura web

php_value parou de funcionar: o .user.ini no LiteSpeed

O arquivo continua sendo lido, mas quem executava essas linhas era o mod_php. Veja onde reescrever o ajuste, como provar pelo phpinfo que ele vale só naquela pasta e como reverter.

JR · · 10 min de leitura · 3 tabelas · 4 blocos de código

Resposta curta: Sob LiteSpeed com o PHP em LSAPI, o .htaccess não tem mais quem execute php_value: essa diretiva era do mod_php, que saiu do caminho. O ajuste passa a viver em um arquivo .user.ini na pasta do script, e o valor novo só aparece depois que o cache expira, por padrão 300 segundos.

Neste artigo
  1. Por que a linha do .htaccess virou enfeite
  2. Confirme em dois minutos que é isso mesmo
  3. De php_value para a sintaxe do php.ini
  4. Nem toda diretiva aceita mudar de lugar
  5. Onde o .user.ini precisa morar para ser lido
  6. Criando o .user.ini passo a passo
  7. A prova: dois phpinfo e uma espera
  8. Sete motivos para o .user.ini continuar sem efeito
  9. Como reverter e voltar ao padrão

Por que a linha do .htaccess virou enfeite

php_value e php_flag nunca foram diretivas do PHP. São diretivas do mod_php, o módulo que rodava o PHP dentro do processo do Apache. Quem lia aquela linha no .htaccess e aplicava a configuração era o módulo, não o interpretador.

Quando o site passa a rodar sob LiteSpeed com o PHP em SAPI própria (LSAPI, com suEXEC, cada conta no seu próprio processo), o mod_php deixa de existir no caminho. O .htaccess continua sendo lido para o que é de servidor web (redirect, rewrite, deny, cabeçalho), mas a linha php_value upload_max_filesize 64M não tem mais ninguém para executá-la.

O sintoma é traiçoeiro porque quase sempre não há erro. O arquivo carrega, o site abre, o limite continua o mesmo de antes. Em servidor Apache com PHP-FPM o mesmo php_value costuma derrubar a página com HTTP 500 ("Invalid command"), o que pelo menos avisa. Sob LiteSpeed você fica com a impressão de que editou e não adiantou.

A saída documentada pelo próprio LiteSpeed para ajuste por diretório nesse cenário é o arquivo .user.ini (PHP user.ini, LiteSpeed com cPanel). Este guia é documental: ele se apoia nessa documentação e no comportamento padrão do mecanismo user_ini do PHP. Não há medição de laboratório nossa aqui, e os valores de exemplo estão identificados como exemplo.

Confirme em dois minutos que é isso mesmo

Antes de criar arquivo, confirme o diagnóstico. Você vai precisar de um phpinfo() temporário, que também será a ferramenta de prova mais adiante.

Crie um phpinfo temporário com nome difícil de adivinhar

No cPanel, abra Gerenciador de Arquivos, entre em public_html e clique em + Arquivo. Dê um nome que ninguém adivinhe. Exemplo (é só um exemplo, use outro): zz-diag-8f3a.php. Clique com o botão direito no arquivo, escolha Editar e cole:

<?php
phpinfo();

Salve. Acesse https://seudominio.com.br/zz-diag-8f3a.php.

Risco: a página phpinfo() expõe caminhos, versões e módulos do servidor. Deixe no ar o tempo do teste e apague depois. Não use o nome info.php nem phpinfo.php, que são varridos por bot o dia inteiro.

Leia Server API, user_ini.filename e cache_ttl

Na tabela do topo, procure:

Anote o que está escrito nessas duas últimas linhas em vez de assumir o padrão. É o servidor que você tem, não o da documentação.

De php_value para a sintaxe do php.ini

O .user.ini usa a sintaxe do php.ini, com sinal de igual. Não é a sintaxe do Apache.

No .htaccess (mod_php) No .user.ini
php_value upload_max_filesize 64M upload_max_filesize = 64M
php_value post_max_size 64M post_max_size = 64M
php_value max_execution_time 300 max_execution_time = 300
php_value memory_limit 256M memory_limit = 256M
php_flag display_errors on display_errors = On
php_flag display_errors off display_errors = Off
php_admin_value ... sem equivalente por diretório

Duas observações que economizam uma tarde:

Nem toda diretiva aceita mudar de lugar

O PHP classifica cada diretiva por onde ela pode ser alterada. O .user.ini só aceita as de nível PHP_INI_PERDIR e PHP_INI_USER. O rótulo PHP_INI_ALL que você vê na documentação significa "alterável em qualquer lugar", o que inclui PERDIR e USER: por isso as diretivas marcadas como ALL na tabela abaixo também funcionam. As de nível PHP_INI_SYSTEM são lidas uma vez, na subida do processo, e ignoram o arquivo por diretório sem reclamar.

Diretiva Nível Funciona no .user.ini
upload_max_filesize PERDIR sim
post_max_size PERDIR sim
max_input_vars PERDIR sim
max_input_time PERDIR sim
memory_limit ALL sim
max_execution_time ALL sim
display_errors ALL sim
error_reporting ALL sim
error_log ALL sim
date.timezone ALL sim
file_uploads SYSTEM não
disable_functions SYSTEM não
opcache.* (maioria) SYSTEM não
extension= / zend_extension= carregamento de módulo não

Se a diretiva que você precisa está na metade de baixo da tabela, pare aqui. Ela não vai para o .user.ini. O lugar dela é o Selecionar Versão do PHP (aba Opções) ou o MultiPHP INI Editor do cPanel, que escrevem no arquivo de configuração da conta. Se o painel resolve, use o painel: dá menos arquivo solto para você esquecer.

Um detalhe sobre max_execution_time: sob LSAPI, o servidor web também tem o tempo limite dele. Se o script continua morrendo antes do valor que você configurou, quem está cortando é o tempo limite do próprio servidor web, que não se muda por arquivo dentro da conta. Aí as saídas são duas: pedir ao suporte da hospedagem um limite maior para o seu domínio, explicando qual rotina precisa disso, ou reduzir o trabalho do script (processar em lotes menores, importar por partes, mover a tarefa para o WP-Cron).

Decidir onde a diretiva deve ficarServer API mostra LiteSpeed?Se não, php_value ainda valeuser_ini.filename está preenchido?Vazio: recurso desligado, use o painelNível da diretiva é PERDIR ou ALL?SYSTEM não muda por diretórioPrecisa de valor por pasta?Se não, resolva no MultiPHP INI EditorCrie o .user.iniNa raiz ou em wp-admin
Caminho de decisão antes de criar qualquer arquivo. Baseado na documentação do LiteSpeed e no mecanismo user_ini do PHP.

Onde o .user.ini precisa morar para ser lido

Esta é a parte que mais gera arquivo criado no lugar errado.

O PHP procura o .user.ini a partir da pasta do script que está executando e vai subindo até o diretório raiz do site. Ele não para no primeiro arquivo que encontra: lê todos os que existirem no caminho e mescla o resultado. Se a mesma diretiva aparecer em dois níveis, vence a do arquivo mais próximo do script. Não é a pasta da URL. Não é a pasta do arquivo que você está enviando.

Em WordPress isso significa:

Regra prática: se o ajuste é do site inteiro, coloque na raiz (public_html ou a pasta do domínio). Se o ajuste é só para o painel (limite maior de upload sem afrouxar o front-end), coloque em wp-admin, e é exatamente esse caso que o teste da seção seguinte prova.

Criando o .user.ini passo a passo

Faça backup do .htaccess antes de editar

No Gerenciador de Arquivos, clique com o botão direito no .htaccess e escolha Copiar ou Baixar. Se o arquivo não aparecer, clique em Configurações, no canto superior direito, e marque Mostrar arquivos ocultos (dotfiles).

Um .htaccess quebrado derruba o site inteiro. Com a cópia baixada, voltar atrás é arrastar o arquivo de volta.

Comente as linhas mortas no .htaccess

Não apague de primeira. Coloque # na frente para poder reverter lendo o próprio arquivo:

# php_value upload_max_filesize 64M
# php_value post_max_size 64M

Salve e recarregue o site. Ele tem que continuar abrindo normalmente.

Crie o .user.ini na pasta escolhida

Entre na pasta, clique em + Arquivo e digite exatamente .user.ini, com o ponto na frente. Botão direito, Editar, e cole o conteúdo. Exemplo para um caso de upload de mídia travando (valores de exemplo, ajuste aos seus):

upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 300
memory_limit = 256M

Mantenha post_max_size igual ou maior que upload_max_filesize. O envio inteiro do formulário passa pelo post_max_size, então um valor menor ali anula o outro.

Se preferir terminal, por SSH, o equivalente para a raiz é:

cd ~/public_html
cat > .user.ini <<'EOF'
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 300
memory_limit = 256M
EOF
cat .user.ini

A linha cd entra na pasta. O bloco cat > ... <<'EOF' grava tudo até o EOF dentro do arquivo, sobrescrevendo o que houver. O cat .user.ini do final imprime o resultado: você deve ver de volta as mesmas quatro linhas. Se não vir, o arquivo não foi criado onde você pensou.

Confira permissão 0644 e o nome exato do arquivo

O arquivo precisa ser legível pelo usuário que roda o PHP. 0644 resolve. E confira o nome: o Gerenciador de Arquivos às vezes salva como .user.ini.txt se você criou pelo editor de texto do desktop e subiu por upload. Nome errado por um caractere é nome errado.

A prova: dois phpinfo e uma espera

O teste que fecha a questão compara o mesmo phpinfo() em dois diretórios diferentes.

Duplique o diagnóstico na pasta do .user.ini

Deixe o zz-diag-8f3a.php na raiz e crie uma cópia dentro da pasta onde você colocou o .user.ini (no exemplo, wp-admin). São dois arquivos, mesmo conteúdo, pastas diferentes.

Espere o TTL do cache antes de concluir qualquer coisa

O PHP guarda o conteúdo já lido do .user.ini pelo tempo de user_ini.cache_ttl, aquele número que você anotou lá no começo (padrão 300 segundos). Antes disso, o processo que atendeu sua requisição pode continuar servindo o valor antigo. Não é bug e não adianta salvar o arquivo de novo: o contador é por tempo, não por modificação.

Então: crie o arquivo, olhe o relógio, espere o TTL e só depois conclua alguma coisa. Boa parte dos casos de "criei o .user.ini e não funcionou" é só o TTL ainda correndo.

Compare Local Value e Master Value

Abra os dois phpinfo e procure a diretiva na seção Core. A tabela tem três colunas:

Coluna O que significa
Directive nome da diretiva
Local Value valor em vigor para este script, neste diretório
Master Value valor do php.ini do servidor, o padrão

O resultado esperado do teste:

Quando as duas colunas divergem só no diretório onde você pôs o arquivo, está provado que o .user.ini foi lido e que o escopo é o diretório, não o site todo.

Não procure o nome .user.ini na linha Loaded Configuration File nem em additional .ini files parsed. Ele não aparece ali. Essas linhas listam a configuração do servidor. A única evidência de que o .user.ini pegou é a divergência entre Local Value e Master Value.

Apague os dois arquivos de diagnóstico

Assim que terminar o teste. Os dois, o da raiz e o da subpasta.

Como provar que o .user.ini foi lidoDois phpinfoRaiz e pasta do .user.iniSalve o arquivoPermissão 0644, nome exatoEspere o TTLVeja user_ini.cache_ttl no phpinfoCompare os valoresLocal Value contra Master ValueApague os diagnósticosOs dois arquivos, sempre
Sequência do teste que prova a leitura do .user.ini. A divergência entre Local e Master Value é a única evidência.

Sete motivos para o .user.ini continuar sem efeito

Antes de abrir chamado, percorra esta lista:

Como reverter e voltar ao padrão

A reversão tem que ser tão simples quanto a aplicação, e neste caso é:

  1. Apague o .user.ini ou renomeie para .user.ini.bak. Renomear é melhor: você mantém o conteúdo para consultar depois. Qualquer nome diferente do que está em user_ini.filename deixa o arquivo inerte.
  2. Espere o TTL de novo. Sim, para voltar ao padrão também vale a espera.
  3. Confirme no phpinfo() que Local Value e Master Value voltaram a ser iguais.
  4. Restaure o .htaccess do backup, se você tiver mexido além de comentar linhas.
  5. Apague os arquivos de diagnóstico.

Um último conselho contra o nosso próprio discurso de "faça você mesmo": se o objetivo é só aumentar o limite de upload do WordPress e o cPanel da sua conta tem o MultiPHP INI Editor, resolva por lá e não crie arquivo nenhum. O .user.ini ganha quando você precisa de valor diferente em uma pasta específica, quando o site é gerenciado por deploy versionado e a configuração precisa viajar junto com o código, ou quando o painel não expõe a diretiva. Fora disso, é mais um arquivo oculto para o próximo a mexer no site descobrir do jeito difícil.

Referências

  1. Documentação oficial (litespeed) — PHP user.ini (LiteSpeed com cPanel). Consultado em 2026-09-28.
Leia também