Composer en PHP: instalar paquetes y autoload de clases

Composer es el gestor de paquetes de PHP. Ejecuta composer require vendor/package en la carpeta de tu proyecto: Composer descarga la librería en vendor/, la registra en composer.json, y la cargas, junto con todo lo demás que hayas instalado, con una sola línea, 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%']);

Sin un include para cada archivo: el autoloader carga Logger, StreamHandler y todo lo que usan la primera vez que se necesita cada clase. Los paquetes vienen de Packagist, el registro público en el que Composer busca por defecto.

Instalar Composer

Composer necesita antes PHP en tu equipo (consulta instalar PHP).

Windows: descarga y ejecuta Composer-Setup.exe desde getcomposer.org. Encuentra tu php.exe y añade composer al PATH. Abre después una terminal nueva.

macOS con Homebrew:

brew install composer

Linux: el paquete de tu distribución (sudo apt install composer en Debian y Ubuntu) funciona, pero suele ser una versión antigua. El instalador oficial da la actual:

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 página de descarga de getcomposer.org también muestra una línea que comprueba el hash del instalador antes de ejecutarlo; copia los comandos de ahí para obtener el hash actual. Luego comprueba que funciona:

composer --version

composer.json y composer.lock

composer init hace unas cuantas preguntas y escribe composer.json, o bien composer require lo crea con el primer paquete. Uno 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 enumera lo que el proyecto necesita para funcionar, incluida la versión de PHP.
• require-dev enumera herramientas solo para desarrollo (tests, análisis estático). composer require --dev phpunit/phpunit añade a esta lista, y composer install --no-dev la omite en los servidores de producción.
• autoload le dice a Composer dónde están tus propias clases (más abajo).

A su lado, Composer escribe composer.lock con la versión exacta de cada paquete que instaló, incluidos los paquetes de los que dependen tus paquetes. Sube los dos archivos al repositorio. No subas vendor/: añádelo a .gitignore, porque composer install lo reconstruye a partir del archivo 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

Ejecuta composer install después de clonar un proyecto y en cada despliegue: todo el mundo obtiene las mismas versiones que se probaron. Ejecuta composer update solo cuando quieras actualizar, y luego prueba y sube el nuevo composer.lock. Ejecutar update en un servidor de producción instala versiones que nadie ha probado.

Restricciones de versión: ^ y ~

composer require vendor/package sin versión elige la versión estable más reciente y escribe una restricción ^ para ella, que normalmente es lo que quieres.

Autoload de tus propias clases con PSR-4

PSR-4 es la convención que asigna un namespace a una carpeta: con "App\\": "src/", la clase App\Text\Slug está en src/Text/Slug.php. Después de añadir la sección autoload, ejecuta:

composer dump-autoload

El autoloader de Composer es una función registrada con spl_autoload_register(), a la que PHP llama cada vez que el código usa una clase que aún no se ha cargado. Este bloque escribe dos archivos de clase y registra un pequeño autoloader PSR-4 propio, para que veas funcionar la asignación. Añade un tercer archivo de clase y úsalo.

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

El autoloader se ejecuta una vez por clase: la segunda llamada a Slug::from() no imprime ninguna línea autoload:, porque la clase ya está cargada. En un proyecto real nunca escribes tú esta función; vendor/autoload.php registra la versión de Composer, que además maneja los paquetes de vendor/. Los namespaces se explican en la página de namespaces.

Errores frecuentes

• Class "Monolog\Logger" not found. El script no hizo require 'vendor/autoload.php', o la ruta es incorrecta. Usa __DIR__ . '/vendor/autoload.php' para que la ruta no dependa del directorio actual.
• No se encuentra tu propia clase después de añadirla a autoload. Ejecuta composer dump-autoload y comprueba que la ruta del archivo coincide exactamente con el namespace, incluidas mayúsculas y minúsculas: App\Text\Slug debe estar en src/Text/Slug.php, y los servidores Linux tratan src/text/slug.php como un archivo distinto.
• Your requirements could not be resolved to an installable set of packages. Dos paquetes necesitan versiones incompatibles de algo, a menudo del propio PHP. El mensaje enumera el conflicto; composer why-not vendor/package 2.0 explica qué bloquea una versión.
• composer no se reconoce como comando. La terminal se abrió antes de la instalación, o la carpeta no está en tu PATH. Abre una terminal nueva, o llama directamente a php composer.phar.