# 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.

> 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.

João Rizzon · 2026-10-03 · Infraestrutura web

---

## 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.

## 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.

```bash
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:

```bash
/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:

- O `php.ini` do CLI pode não ser o mesmo arquivo que o do FPM/handler. O `memory_limit` que você vê no `phpinfo()` do site não vale necessariamente para o CLI.
- Extensão desabilitada no seletor de versão do cPanel não aparece aqui, e o Composer vai reclamar de `ext-*` na hora de resolver.

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](https://docs.cpanel.net/knowledge-base/web-services/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

```bash
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

```bash
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

```bash
~/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:

```bash
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:

- A saída termina em `Killed` e `echo $?` devolve `137`.
- Não há `PHP Fatal error: Allowed memory size ...`.
- Subir `memory_limit` só faz o processo morrer mais tarde, não mais longe.

Um teste rápido dentro da conta:

```bash
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:

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

No servidor, apenas:

```bash
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:

```bash
/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:

- Sem solver, não há grafo de versões na RAM.
- Sem download de metadados do repositório, não há centenas de requisições HTTPS e JSON para parsear.
- O `--optimize-autoloader` troca a busca por arquivo em runtime por um mapa de classes estático, o que reduz `stat()` a cada autoload em produção.
- `--no-dev` tira PHPUnit e companhia, menos arquivos escritos no disco compartilhado.

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`.

## Checklist na ordem em que cada passo elimina uma causa

Na ordem, porque cada passo elimina uma causa:

- `php -v` e `which php`. Se não for `/opt/cpanel/ea-phpXX/...`, pare e troque para o caminho absoluto.
- `/opt/cpanel/ea-php82/root/usr/bin/php -m` para conferir as extensões exigidas pelo `composer.json`.
- `composer diagnose` com esse binário.
- Rodou `update` no servidor? Troque por `install` com `composer.lock` versionado.
- Mensagem com `Allowed memory size ... exhausted`: aplique `COMPOSER_MEMORY_LIMIT=-1` e `-d memory_limit=-1`.
- Saída `Killed` com código 137: é cgroup. Mova a resolução para fora do servidor ou peça mais memória.
- 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.

