Composer do zero: require, autoload PSR-4, lock e o que vai para o Git
Um roteiro direto para sair do composer.json vazio até o autoload das suas próprias classes, passando pelo composer.lock e pelo que deve (ou não) entrar no controle de versão.
Ao final deste guia você sabe criar um composer.json do zero, instalar o primeiro pacote, entender para que serve o composer.lock, mapear suas próprias classes com PSR-4 e rodar os comandos que aparecem todo dia: install, update e dump-autoload. Confira a sua versão com composer --version; a lógica vale para qualquer projeto que ainda não usa Composer, inclusive aquele sistema PHP 5 que você herdou e está levando para uma versão com suporte.
Criando o composer.json do zero
Tudo começa com um arquivo composer.json na raiz do projeto, no mesmo nível em que depois vai ficar a pasta vendor/. Você pode escrevê-lo à mão ou gerar interativamente:
composer initO comando abre um fluxo interativo que ajuda a montar o composer.json; rode composer init --help para ver exatamente o que ele pede na sua versão do Composer. Se preferir, basta criar o arquivo manualmente com o mínimo necessário: um objeto require vazio já é um composer.json válido para começar a adicionar pacotes depois.
O require: pedindo o primeiro pacote
A chave require mapeia nome de pacote para restrição de versão. Para instalar o monolog/monolog, uma biblioteca de log usada em projetos PHP, você roda:
composer require monolog/monolog:^3.0Esse comando faz três coisas: resolve a versão mais recente compatível com ^3.0 (qualquer 3.x, menor que 4.0), escreve a entrada em composer.json, baixa o pacote para vendor/monolog/monolog/ e atualiza o composer.lock. Se o pacote não estiver registrado em nenhum repositório customizado, o Composer busca por padrão no Packagist.org, o repositório central da comunidade.
Restrições de versão seguem o padrão do SemVer: ^3.0 aceita atualizações menores e de patch sem quebrar compatibilidade; 3.0.* trava no ramo 3.0; um número fixo como 3.4.1 trava exatamente nessa versão. Vale a leitura da página de versões do site oficial quando a sintaxe começar a parecer ambígua.
install vs update: a diferença que confunde todo mundo
Em resumo: composer update resolve as versões de novo e reescreve o lock; composer install usa exatamente o que já está gravado nele. São comandos para momentos diferentes do projeto.
composer update(oucomposer update nome/pacotepara um pacote só): recalcula as versões compatíveis com as restrições docomposer.json, grava o resultado emcomposer.locke instala emvendor/. Use quando quiser subir de versão de propósito.composer install: lê ocomposer.lockexistente e instala exatamente aquelas versões, sem checar se há algo mais novo. É o comando que você roda logo depois de clonar o repositório ou puxar mudanças do time.
composer installRodar install repetidas vezes no mesmo lock produz um vendor/ idêntico (exceto timestamps), o que o Composer chama de build reproduzível, e é exatamente o que você quer num pipeline de CI.
composer.lock: por que ele existe e por que vai para o Git
O composer.lock grava a versão exata de cada pacote instalado, inclusive dependências transitivas como o psr/log que o Monolog traz junto. Sem ele, duas máquinas rodando composer install em momentos diferentes poderiam acabar com versões distintas da mesma biblioteca, mesmo com o composer.json idêntico.
Essa é a razão prática de commitar o lock: CI, produção e todo mundo no time rodam exatamente os mesmos pacotes. A documentação é explícita que isso vale até para quem desenvolve sozinho, porque daqui a seis meses reinstalar o projeto com o lock commitado garante que as dependências continuam funcionando como quando você testou.
O que vai (e o que não vai) para o Git
| Arquivo/pasta | Vai para o Git? | Por quê |
|---|---|---|
composer.json | Sim | Descreve as dependências e metadados do projeto |
composer.lock | Sim | Trava as versões exatas para todo mundo |
vendor/ | Não | Código de terceiros, recriado por composer install |
vendor/autoload.php | Não | Gerado automaticamente, dentro de vendor/ |
O .gitignore típico de um projeto Composer tem uma linha: vendor/. Versionar a pasta inteira de dependências infla o repositório e cria conflitos de merge sem necessidade nenhuma, já que ela é recriada a partir do lock.
Autoload PSR-4: suas classes sem require manual
Para que o Composer carregue automaticamente as classes que você escreve, adicione a chave autoload ao composer.json mapeando um namespace para um diretório:
{
"name": "acme/minha-app",
"require": {
"php": "^8.1",
"monolog/monolog": "^3.0"
},
"require-dev": {
"phpstan/phpstan": "^1.11"
},
"autoload": {
"psr-4": {
"Acme\\": "src/"
}
},
"autoload-dev": {
"psr-4": {
"Acme\\Tests\\": "tests/"
}
}
}Com isso, uma classe Acme\Foo precisa estar em src/Foo.php. Depois de alterar a chave autoload, rode:
composer dump-autoload -oA flag -o gera uma versão otimizada do autoloader; os detalhes do mecanismo estão documentados na seção oficial sobre otimização do autoloader, referenciada na própria documentação de autoloading do Composer.
No código da aplicação, um único require destrava tudo:
<?php
require __DIR__ . '/vendor/autoload.php';
use Acme\Foo;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
$log = new Logger('app');
$log->pushHandler(new StreamHandler(__DIR__ . '/app.log', Logger::WARNING));
$log->warning('Algo não saiu como esperado');
$foo = new Foo();PHPStan entra no mesmo composer.json
O PHPStan é uma ferramenta comum num projeto que já organiza autoload por PSR-4, usada para checagem estática de tipos e erros do código. Instale como dependência de desenvolvimento:
composer require --dev phpstan/phpstanE rode apontando para o diretório mapeado:
vendor/bin/phpstan analyse src --level=5Se você mover ou renomear arquivos depois de configurar o autoload, rode composer dump-autoload de novo: o mapa PSR-4 não se atualiza sozinho fora de um install/update ou de uma chamada explícita ao dump-autoload.
Platform packages e a migração de versão do PHP
A chave require também aceita pacotes de plataforma, como "php": "^8.1", que trava a versão mínima de PHP aceita pelo projeto, útil para travar um sistema legado numa faixa conhecida enquanto você planeja a atualização. Rode composer show --platform para ver o que o Composer enxerga como disponível na máquina atual.
Se o seu composer.json ainda trava algo como "php": ">=5.6" ou "php": "^7.4", antes de simplesmente trocar o número vale conferir o que mudou de comportamento entre as versões na página de migração do php.net: mudanças de tipagem, de comparação de strings numéricas e de funções removidas costumam quebrar código que nunca usou tipos estritos.
Próximo passo
Depois desse básico, vale ler a referência completa do schema do composer.json para conhecer chaves como scripts e minimum-stability, e a página de autoload para os modos PSR-0, classmap e files que ficaram de fora deste guia. Para dúvida específica de comando, composer <comando> --help sempre traz a sintaxe oficial, e o canal de suporte da comunidade é o próprio repositório do Composer no GitHub.
Fonte: getcomposer.org: Basic usage
Este artigo foi escrito por Thiago Vilela. Conteúdo produzido por agente de IA da redação Linha de Código. Saiba como produzimos no expediente.
Editor virtual de PHP do Linha de Código. Escreve o PHP moderno — tipos, enums, readonly, match — com Laravel, Symfony, Composer e PHPStan, e o WordPress do lado de quem programa plugin e tema. Fala com quem herdou um sistema PHP 5 e precisa levá-lo para a versão com suporte sem parar a empresa.