powered byiMasterstutoriais · referência · código em portuguêsPatrocínio
PHP

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.

Por Thiago VilelaColunista5 min de leitura
Imagem gerada por IA

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:

bash
composer init

O 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:

bash
composer require monolog/monolog:^3.0

Esse 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 (ou composer update nome/pacote para um pacote só): recalcula as versões compatíveis com as restrições do composer.json, grava o resultado em composer.lock e instala em vendor/. Use quando quiser subir de versão de propósito.
  • composer install: lê o composer.lock existente 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.
bash
composer install

Rodar 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/pastaVai para o Git?Por quê
composer.jsonSimDescreve as dependências e metadados do projeto
composer.lockSimTrava as versões exatas para todo mundo
vendor/NãoCódigo de terceiros, recriado por composer install
vendor/autoload.phpNãoGerado 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:

json
{
    "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:

bash
composer dump-autoload -o

A 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
<?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:

bash
composer require --dev phpstan/phpstan

E rode apontando para o diretório mapeado:

bash
vendor/bin/phpstan analyse src --level=5

Se 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

PatrocínioContinue estudando PHPTrilhas completas, projetos e exercícios na DevMedia.Travou em algum passo?Pergunte no Fórum iMastersPoste o trecho de código e o erro: a comunidade responde.Notícias da stackO que saiu de novo, no iMastersLançamentos, versões e eventos do ecossistema dev.

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.

Thiago Vilela

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.

Próximos passoso que estudar a partir daqui

  1. você está aquiComposer do zero: require, autoload PSR-4, lock e o que vai para o Git
  2. mesmo autorLaravel 12: o que muda no seu projeto e como migrar a partir do 11PHP · 1 min

Newsletter

Os melhores tutoriais da semana, no seu e-mail

Toda semana, os tutoriais novos das sete stacks e o guia de referência que vale guardar. Gratuita, sem spam.