Composer no PHP: instalar pacotes e autoload de classes

O Composer é o gerenciador de pacotes do PHP. Rode composer require vendor/package na pasta do seu projeto: o Composer baixa a biblioteca para vendor/, registra-a no composer.json, e você a carrega, junto com tudo o que instalou, com uma linha, require __DIR__ . '/vendor/autoload.php';.

composer require monolog/monolog

<?php
require __DIR__ . '/vendor/autoload.php';

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Level;

$log = new Logger('app');
$log->pushHandler(new StreamHandler(__DIR__ . '/app.log', Level::Warning));
$log->warning('Disk almost full', ['free' => '2%']);

Nenhum include para cada arquivo: o autoloader carrega Logger, StreamHandler e tudo o que eles usam na primeira vez que cada classe é necessária. Os pacotes vêm do Packagist, o registro público em que o Composer busca por padrão.

Instalar o Composer

O Composer precisa do PHP na sua máquina primeiro (veja instalar PHP).

Windows: baixe e rode o Composer-Setup.exe de getcomposer.org. Ele encontra o seu php.exe e adiciona composer ao PATH. Abra um novo terminal depois.

macOS com Homebrew:

brew install composer

Linux: o pacote da sua distribuição (sudo apt install composer no Debian e no Ubuntu) funciona, mas muitas vezes é uma versão mais antiga. O instalador oficial dá a atual:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

A página de download em getcomposer.org também mostra uma linha que confere o hash do instalador antes de executá-lo; copie os comandos de lá para ter o hash atual. Depois confira se funciona:

composer --version

composer.json e composer.lock

O composer init faz algumas perguntas e escreve o composer.json, ou o composer require o cria no primeiro pacote. Um típico:

{
    "name": "acme/shop",
    "require": {
        "php": ">=8.2",
        "monolog/monolog": "^3.0",
        "vlucas/phpdotenv": "^5.6"
    },
    "require-dev": {
        "phpunit/phpunit": "^11.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

• require lista o que o projeto precisa para rodar, incluindo a versão do PHP.
• require-dev lista ferramentas só de desenvolvimento (testes, análise estática). composer require --dev phpunit/phpunit adiciona a ela, e composer install --no-dev a pula em servidores de produção.
• autoload diz ao Composer onde ficam as suas próprias classes (abaixo).

Ao lado dele, o Composer escreve o composer.lock com a versão exata de cada pacote que instalou, incluindo os pacotes de que os seus pacotes dependem. Faça commit dos dois arquivos. Não faça commit da vendor/: adicione-a ao .gitignore, porque o composer install a reconstrói a partir do arquivo lock.

composer install ou composer update

composer install          # install exactly what composer.lock says
composer update           # pick the newest allowed versions, rewrite composer.lock
composer update monolog/monolog   # update one package only
composer remove monolog/monolog   # uninstall and remove from composer.json
composer outdated         # list packages with newer versions available

Rode composer install depois de clonar um projeto e em cada deploy: todos recebem as mesmas versões que foram testadas. Rode composer update só quando quiser atualizar, depois teste e faça commit do novo composer.lock. Rodar update num servidor de produção instala versões que ninguém testou.

Restrições de versão: ^ e ~

composer require vendor/package sem versão escolhe a versão estável mais nova e escreve uma restrição ^ para ela, o que normalmente é o que você quer.

Autoload das suas próprias classes com PSR-4

O PSR-4 é a convenção que liga um namespace a uma pasta: com "App\\": "src/", a classe App\Text\Slug fica em src/Text/Slug.php. Depois de adicionar a seção autoload, rode:

composer dump-autoload

O autoloader do Composer é uma função registrada com spl_autoload_register(), que o PHP chama sempre que o código usa uma classe ainda não carregada. Este bloco escreve dois arquivos de classe e registra um pequeno autoloader PSR-4 próprio, para você ver o mapeamento funcionando. Adicione um terceiro arquivo de classe e use-o.

<?php
// Two class files, laid out the PSR-4 way
is_dir('src/Text') || mkdir('src/Text', 0777, true);

file_put_contents('src/Greeter.php', <<<'PHP'
<?php
namespace App;

class Greeter
{
    public function hello(string $name): string
    {
        return "Hello, $name";
    }
}
PHP);

file_put_contents('src/Text/Slug.php', <<<'PHP'
<?php
namespace App\Text;

class Slug
{
    public static function from(string $title): string
    {
        return trim(preg_replace('/[^a-z0-9]+/', '-', strtolower($title)), '-');
    }
}
PHP);

// What vendor/autoload.php does for "App\\": "src/"
spl_autoload_register(function (string $class): void {
    $prefix = 'App\\';
    if (!str_starts_with($class, $prefix)) {
        return;
    }
    $file = __DIR__ . '/src/' . str_replace('\\', '/', substr($class, strlen($prefix))) . '.php';
    echo "autoload: $class => ", substr($file, strlen(__DIR__) + 1), "\n";
    if (is_file($file)) {
        require $file;
    }
});

echo (new App\Greeter())->hello('Ada'), "\n";
echo App\Text\Slug::from('Composer & PSR-4, Explained'), "\n";
echo App\Text\Slug::from('Loaded once, used twice'), "\n";

O autoloader roda uma vez por classe: a segunda chamada a Slug::from() não imprime nenhuma linha autoload:, porque a classe já está carregada. Num projeto real você nunca escreve essa função; o vendor/autoload.php registra a versão do Composer, que também cuida dos pacotes em vendor/. Namespaces são explicados na página sobre namespaces.

Erros comuns

• Class "Monolog\Logger" not found. O script não fez require 'vendor/autoload.php', ou o caminho está errado. Use __DIR__ . '/vendor/autoload.php' para que o caminho não dependa do diretório atual.
• A sua própria classe não é encontrada depois de adicioná-la ao autoload. Rode composer dump-autoload e confira se o caminho do arquivo bate exatamente com o namespace, incluindo maiúsculas e minúsculas: App\Text\Slug precisa ser src/Text/Slug.php, e servidores Linux tratam src/text/slug.php como outro arquivo.
• Your requirements could not be resolved to an installable set of packages. Dois pacotes precisam de versões incompatíveis de algo, muitas vezes do próprio PHP. A mensagem lista o conflito; composer why-not vendor/package 2.0 explica o que bloqueia uma versão.
• composer não é reconhecido. O terminal foi aberto antes da instalação, ou a pasta não está no seu PATH. Abra um novo terminal, ou chame php composer.phar diretamente.