PHP Composer: installare pacchetti e autoload delle classi

Composer è il gestore di pacchetti di PHP. Esegui composer require vendor/package nella cartella del progetto: Composer scarica la libreria in vendor/, la registra in composer.json, e la carichi, insieme a tutto il resto che hai installato, con una sola riga, 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%']);

Nessun include per ogni file: l'autoloader carica Logger, StreamHandler e tutto ciò che usano la prima volta che ciascuna classe serve. I pacchetti arrivano da Packagist, il registro pubblico in cui Composer cerca di default.

Installare Composer

Composer richiede prima PHP sulla tua macchina (vedi installare PHP).

Windows: scarica ed esegui Composer-Setup.exe da getcomposer.org. Trova il tuo php.exe e aggiunge composer al PATH. Apri poi un nuovo terminale.

macOS con Homebrew:

brew install composer

Linux: il pacchetto della tua distribuzione (sudo apt install composer su Debian e Ubuntu) funziona ma spesso è una versione più vecchia. L'installer ufficiale dà quella attuale:

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

La pagina di download su getcomposer.org mostra anche una riga che verifica l'hash dell'installer prima di eseguirlo; copia i comandi da lì per avere l'hash attuale. Poi verifica che funzioni:

composer --version

composer.json e composer.lock

composer init fa qualche domanda e scrive composer.json, oppure composer require lo crea al primo pacchetto. Uno tipico:

{
    "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 elenca ciò che serve al progetto per girare, compresa la versione di PHP.
• require-dev elenca gli strumenti solo per lo sviluppo (test, analisi statica). composer require --dev phpunit/phpunit aggiunge lì, e composer install --no-dev li salta sui server di produzione.
• autoload dice a Composer dove si trovano le tue classi (vedi sotto).

Accanto, Composer scrive composer.lock con la versione esatta di ogni pacchetto installato, compresi i pacchetti da cui dipendono i tuoi. Fai il commit di entrambi i file. Non fare il commit di vendor/: aggiungilo a .gitignore, perché composer install lo ricostruisce dal file di lock.

composer install vs 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

Esegui composer install dopo aver clonato un progetto e a ogni deploy: tutti ricevono le stesse versioni che sono state testate. Esegui composer update solo quando intendi aggiornare, poi testa e fai il commit del nuovo composer.lock. Eseguire update su un server di produzione installa versioni che nessuno ha testato.

Vincoli di versione: ^ e ~

composer require vendor/package senza versione sceglie la release stabile più recente e scrive un vincolo ^ per essa, che di solito è ciò che vuoi.

Autoload delle tue classi con PSR-4

PSR-4 è la convenzione che associa un namespace a una cartella: con "App\\": "src/", la classe App\Text\Slug si trova in src/Text/Slug.php. Dopo aver aggiunto la sezione autoload, esegui:

composer dump-autoload

L'autoloader di Composer è una funzione registrata con spl_autoload_register(), che PHP chiama ogni volta che il codice usa una classe non ancora caricata. Questo blocco scrive due file di classe e registra un suo piccolo autoloader PSR-4, così puoi vedere la mappatura al lavoro. Aggiungi un terzo file di classe e usalo.

<?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";

L'autoloader viene eseguito una volta per classe: la seconda chiamata a Slug::from() non stampa alcuna riga autoload:, perché la classe è già caricata. In un progetto reale non scrivi mai tu questa funzione; vendor/autoload.php registra la versione di Composer, che gestisce anche i pacchetti in vendor/. I namespace sono trattati nella pagina sui namespace.

Errori comuni

• Class "Monolog\Logger" not found. Lo script non ha fatto require 'vendor/autoload.php', oppure il percorso è sbagliato. Usa __DIR__ . '/vendor/autoload.php' così il percorso non dipende dalla cartella corrente.
• La tua classe non viene trovata dopo averla aggiunta ad autoload. Esegui composer dump-autoload, e verifica che il percorso del file corrisponda esattamente al namespace, maiuscole e minuscole comprese: App\Text\Slug deve essere src/Text/Slug.php, e i server Linux trattano src/text/slug.php come un file diverso.
• Your requirements could not be resolved to an installable set of packages. Due pacchetti richiedono versioni incompatibili di qualcosa, spesso di PHP stesso. Il messaggio elenca il conflitto; composer why-not vendor/package 2.0 spiega cosa blocca una versione.
• composer non viene riconosciuto. Il terminale era stato aperto prima dell'installazione, oppure la cartella non è nel PATH. Apri un nuovo terminale, oppure chiama direttamente php composer.phar.