blog
Infraestrutura web

Composer sem memória no cPanel: PHP, binário ou cgroup

Como distinguir o fatal error de memória do PHP do kill por cgroup da conta, e por que resolver o grafo de dependências fora do servidor é o caminho mais barato.

JR · · 6 min de leitura · 2 tabelas · 13 blocos de código

Resposta curta: em conta compartilhada cPanel, chame o binário completo da versão certa (`/opt/cpanel/ea-php82/root/usr/bin/php`) com `-d memory_limit=-1` e `COMPOSER_MEMORY_LIMIT=-1`. Se o processo morrer com `Killed` e código 137, o limite é do cgroup, não do PHP: resolva as dependências fora e rode só `install` no servidor.

Neste artigo
  1. Três erros diferentes, e a mensagem diz qual é o seu
  2. Descobrir qual binário PHP o SSH está entregando
  3. Instalar o composer.phar e invocá-lo com o binário certo
  4. Por que update come memória e install não
  5. As três formas de afrouxar o limite, e quando nenhuma adianta
  6. O caminho que custa menos é resolver fora e instalar dentro
  7. Checklist na ordem em que cada passo elimina uma causa

Três erros diferentes, e a mensagem diz qual é o seu

Quem roda Composer por SSH em conta compartilhada costuma colidir com dois problemas distintos, e misturá-los faz perder horas. Antes de mexer em qualquer coisa, leia a mensagem literal:

PHP Fatal error:  Allowed memory size of 134217728 bytes exhausted (tried to allocate 20480 bytes) in phar:///home/usuario/composer.phar/...

Isso é o PHP batendo no memory_limit do processo CLI. O número em bytes é o limite do ini em vigor naquele binário.

Your requirements could not be resolved to an installable set of packages.
  - Root composer.json requires php ^8.1 but your php version (7.2.34) does not satisfy that requirement.

Isso é o binário errado. O php que o $PATH do SSH entrega não é o mesmo que serve o site pelo handler do EasyApache.

E existe um terceiro caso, o mais ingrato:

Killed

Sem fatal error, sem stack trace, status 137. Aí quem matou o processo foi o kernel, por limite de memória do cgroup da conta. Nenhuma flag do Composer resolve isso.

Qual mensagem aponta para qual causaAllowed memory size exhaustedPHP abortou: ajuste memory_limitphp version does not satisfyBinário errado: use caminho absolutoKilled, status 137Kernel matou: limite do cgroupSem mensagem claraRode composer diagnose antes de teorizar
A mensagem literal separa limite do PHP, binário errado e corte do cgroup.

Descobrir qual binário PHP o SSH está entregando

Em servidor cPanel com EasyApache 4, cada versão de PHP vive em um prefixo próprio em /opt/cpanel/. O php do $PATH tende a ser o binário do sistema, que não carrega as extensões habilitadas para o seu domínio.

which php
php -v
ls -d /opt/cpanel/ea-php*

O caminho completo segue o padrão /opt/cpanel/ea-phpXX/root/usr/bin/php. Exemplos:

Versão Caminho do binário CLI
PHP 7.4 /opt/cpanel/ea-php74/root/usr/bin/php
PHP 8.1 /opt/cpanel/ea-php81/root/usr/bin/php
PHP 8.2 /opt/cpanel/ea-php82/root/usr/bin/php
PHP 8.3 /opt/cpanel/ea-php83/root/usr/bin/php

Confira o que esse binário enxerga antes de instalar nada:

/opt/cpanel/ea-php82/root/usr/bin/php -v
/opt/cpanel/ea-php82/root/usr/bin/php -i | grep -E '^(Loaded Configuration File|memory_limit)'
/opt/cpanel/ea-php82/root/usr/bin/php -m | grep -iE 'json|mbstring|openssl|zip|curl'

Dois detalhes que mordem:

Se which php não aponta para /opt/cpanel/..., não lute com $PATH no meio de um deploy. Chame o caminho absoluto. É explícito, é reproduzível e sobrevive a cron, a script de CI e a .bashrc que ninguém lembra que existe.

Instalar o composer.phar e invocá-lo com o binário certo

A documentação do cPanel descreve instalar o Composer na própria conta via SSH, usando o instalador oficial (How to Set Up PHP Composer). O que a documentação não cobre: usar o mesmo binário ea-php em todas as etapas.

Baixar o instalador e conferir o SHA-384

mkdir -p ~/bin
cd ~
PHPBIN=/opt/cpanel/ea-php82/root/usr/bin/php
EXPECTED=$(curl -sS https://composer.github.io/installer.sig)
curl -sS https://getcomposer.org/installer -o composer-setup.php
ACTUAL=$($PHPBIN -r "echo hash_file('sha384', 'composer-setup.php');")
[ "$EXPECTED" = "$ACTUAL" ] || { echo 'instalador corrompido'; rm composer-setup.php; exit 1; }
$PHPBIN composer-setup.php --install-dir=$HOME/bin --filename=composer.phar
rm composer-setup.php

O installer.sig publica o SHA-384 do instalador oficial. Se os dois valores divergirem, não execute o arquivo: ou o download veio truncado, ou veio de um proxy que você não controla.

Criar um wrapper em vez de confiar no PATH

cat > ~/bin/composer82 <<'EOF'
#!/bin/sh
exec /opt/cpanel/ea-php82/root/usr/bin/php \
  -d memory_limit=-1 \
  $HOME/bin/composer.phar "$@"
EOF
chmod +x ~/bin/composer82

Confirmar com diagnose o que o Composer está usando

~/bin/composer82 diagnose
~/bin/composer82 --version

O diagnose mostra a versão de PHP em uso, se o allow_url_fopen está ligado, se há proxy e se o cache está gravável. É o primeiro comando a rodar quando o erro é esquisito, antes de qualquer teoria.

Por que update come memória e install não

composer update resolve um problema de satisfação: para cada pacote do require, ele carrega os metadados de todas as versões candidatas do repositório, monta as regras de conflito e procura um conjunto consistente. O custo de memória cresce com o número de pacotes, com o número de versões por pacote e com a quantidade de restrições cruzadas. Projeto com framework completo, pacote de testes e dezenas de dependências transitivas puxa um grafo grande para a RAM de uma vez.

composer install é outra história: existe composer.lock, as versões já estão decididas, e o trabalho vira download, extração e geração de autoload. Sem solver.

Daí a regra prática: update é tarefa de máquina de desenvolvimento, install é tarefa de servidor.

As três formas de afrouxar o limite, e quando nenhuma adianta

São três formas de afrouxar o limite, com efeitos diferentes:

Forma O que faz Observação
COMPOSER_MEMORY_LIMIT=-1 Variável de ambiente lida pelo Composer, que ajusta o limite do próprio processo Só afeta o Composer, não outros scripts
php -d memory_limit=-1 composer.phar ... Sobrescreve o ini apenas nessa invocação Precisa vir antes do .phar na linha de comando
memory_limit no php.ini do CLI Vale para todo processo CLI daquele binário Muda mais do que você queria

Na prática:

COMPOSER_MEMORY_LIMIT=-1 /opt/cpanel/ea-php82/root/usr/bin/php \
  -d memory_limit=-1 ~/bin/composer.phar install --no-dev --optimize-autoloader

-1 significa sem limite do lado do PHP. Não significa memória infinita. O PHP deixa de abortar por conta própria e passa a pedir ao kernel até onde conseguir. Em conta compartilhada, o teto real é o do cgroup da conta.

Killed com código 137 significa cgroup, não memory_limit

Sintomas de cgroup:

Um teste rápido dentro da conta:

cat /sys/fs/cgroup/memory/memory.limit_in_bytes 2>/dev/null
cat /sys/fs/cgroup/memory.max 2>/dev/null

O primeiro caminho é cgroup v1, o segundo é v2. Pode ser que a leitura não esteja disponível na conta, dependendo de como o host monta o namespace. Se não houver leitura, o par Killed + 137 continua sendo o indício bom.

Quando o limite é do cgroup, as opções honestas são: parar de resolver dependências no servidor, reduzir o grafo, ou pedir mais memória ao provedor. Flag de PHP não vence limite de kernel.

O caminho que custa menos é resolver fora e instalar dentro

Na máquina local ou no runner de CI, onde a RAM é sua:

composer update
# commit obrigatório
git add composer.json composer.lock
git commit -m "deps: atualiza lock"

No servidor, apenas:

COMPOSER_MEMORY_LIMIT=-1 /opt/cpanel/ea-php82/root/usr/bin/php \
  ~/bin/composer.phar install --no-dev --optimize-autoloader --no-interaction

Se nem isso couber, suba o diretório vendor/ já pronto (rsync, artefato de build, release zipada) e rode no servidor só a regeneração do mapa de classes:

/opt/cpanel/ea-php82/root/usr/bin/php ~/bin/composer.phar \
  dump-autoload --optimize --no-dev

Por que isso é mais barato em memória e em I/O:

Uma ressalva: vendor/ versionado no Git funciona, mas engorda o repositório e gera conflito feio em merge. Para projeto com deploy por Git, o mais limpo é manter vendor/ fora do repositório e usar install com lock no servidor, deixando o upload de vendor/ como plano B para quando o cgroup realmente não permitir o install.

Resolver fora, instalar dentroLocal: composer updateSolver roda onde a RAM é suaCommit do composer.lockVersões ficam decididas no repositórioServidor: composer installSem solver, só download e extraçãodump-autoload --optimize --no-devMapa de classes estático em produção
Resolver fora e instalar dentro tira o grafo de versões da RAM do servidor.

Checklist na ordem em que cada passo elimina uma causa

Na ordem, porque cada passo elimina uma causa:

  1. php -v e which php. Se não for /opt/cpanel/ea-phpXX/..., pare e troque para o caminho absoluto.
  2. /opt/cpanel/ea-php82/root/usr/bin/php -m para conferir as extensões exigidas pelo composer.json.
  3. composer diagnose com esse binário.
  4. Rodou update no servidor? Troque por install com composer.lock versionado.
  5. Mensagem com Allowed memory size ... exhausted: aplique COMPOSER_MEMORY_LIMIT=-1 e -d memory_limit=-1.
  6. Saída Killed com código 137: é cgroup. Mova a resolução para fora do servidor ou peça mais memória.
  7. Depois de resolver, rode dump-autoload --optimize --no-dev e confirme que o site carrega com a mesma versão de PHP usada no CLI.

Um último alinhamento que evita bug de produção: a versão escolhida no seletor de PHP do cPanel para o domínio deve ser a mesma do binário usado no CLI. Instalar dependências com ea-php82 e servir o site com ea-php74 produz erro de sintaxe em runtime que não aparece em nenhum passo do deploy.

Referências

  1. Documentação oficial (cpanel) — How to Set Up PHP Composer. Consultado em 2026-09-28.
Leia também