Composer para PHP: qué es y cómo instalar librerías en tu proyecto

Antes de Composer, añadir una librería a PHP era un proceso que daba vergüenza: buscabas el zip en GitHub, lo descargabas, lo descomprimías dentro de tu proyecto, y rezabas para que la librería no dependiera de otras librerías que a su vez dependieran de otras. Cuando actualizabas algo, repetías todo a mano.

Composer resuelve eso exactamente igual que npm en JavaScript: le dices qué necesitas en una sola línea y él se encarga del resto. Descarga la librería, descarga sus dependencias, y genera el código para que PHP las encuentre automáticamente. Lo que tardabas 20 minutos ahora son 10 segundos.

Instalar Composer en Windows

Composer necesita PHP instalado para funcionar. Si tienes XAMPP, ya lo tienes en C:\xampp\php\php.exe. Si no, instala XAMPP primero.

Ve a getcomposer.org y descarga Composer-Setup.exe. Ejecútalo como administrador — si no lo haces como administrador, el instalador no puede añadir Composer al PATH de Windows y luego te preguntarás por qué el comando no se reconoce desde ningún sitio.

En un paso del instalador te pide la ruta de php.exe. Con XAMPP es siempre esta:

C:\xampp\php\php.exe

Siguiente, siguiente, instalar. Cuando termine, cierra cualquier terminal que tengas abierta y abre una nueva. Esto es importante: las terminales cargan el PATH al abrirse, no lo actualizan mientras están abiertas. Si usas la misma que tenías, Composer no existirá para ella aunque esté bien instalado.

composer --version

Tu primer composer require

Composer trabaja siempre dentro de la carpeta de un proyecto concreto. Abre la terminal, ve a tu proyecto y ejecuta el require. Usamos PHPMailer como ejemplo porque es la librería que vamos a necesitar en el siguiente tutorial:

cd C:\xampp\htdocs\mi-proyecto

composer require phpmailer/phpmailer

Verás cómo Composer descarga cosas. Al terminar, tienes tres archivos o carpetas nuevas en tu proyecto que antes no estaban:

composer.json es la lista de intenciones: qué librerías quieres y en qué rango de versiones. Lo gestiona Composer automáticamente cuando ejecutas require o update, no lo toques a mano salvo que sepas lo que haces.

composer.lock es la lista de realidades: exactamente qué versión de cada librería (y de cada dependencia de esas librerías) está instalada ahora mismo. Este archivo sí va a Git. Es lo que garantiza que cuando otro desarrollador clone el proyecto y ejecute composer install, tenga exactamente las mismas versiones que tú, no "las más recientes compatibles".

vendor/ contiene el código descargado. Esta carpeta no va a Git — puede pesar 50 MB o más y cualquiera puede regenerarla con composer install. Añade vendor/ a tu .gitignore.

El autoload y los namespaces

Composer genera vendor/autoload.php. Inclúyelo una vez al principio de tu script y PHP encontrará automáticamente cualquier clase de cualquier librería instalada, sin que hagas require de cada archivo por separado.

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

// Ya puedes usar cualquier librería instalada
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;

$mail = new PHPMailer(true);

El use PHPMailer\PHPMailer\PHPMailer puede parecer raro al principio. Eso es un namespace: la ruta completa de la clase dentro de la librería. Es como la ruta de un archivo pero con barras invertidas. El primer PHPMailer es el nombre del paquete, el segundo es la carpeta dentro del paquete, el tercero es el nombre de la clase.

Si tu archivo PHP está en una subcarpeta del proyecto — por ejemplo en includes/email.php — la ruta al autoload cambia porque es relativa a dónde está el archivo:

<?php
// Desde includes/email.php, vendor/ está un nivel arriba
require_once __DIR__ . '/../vendor/autoload.php';

// Desde la raíz del proyecto
require_once 'vendor/autoload.php';

Usa siempre __DIR__ cuando el archivo está en una subcarpeta. __DIR__ es la ruta absoluta de la carpeta donde está el archivo PHP que se está ejecutando — no depende de desde dónde llames al script, así que funciona siempre igual.

Si ves Class "PHPMailer\PHPMailer\PHPMailer" not found, el 99% de las veces es uno de estos dos problemas: olvidaste el require del autoload, o la ruta al autoload está mal porque estás en una subcarpeta.

El composer.json por dentro

Después del primer require, composer.json tiene esto:

{
    "require": {
        "phpmailer/phpmailer": "^6.9"
    }
}

El ^6.9 es un rango de versión. Significa "6.9 o cualquier versión mayor que sea compatible hacia atrás, pero nunca un salto de versión mayor" — es decir, aceptará 6.10, 6.11, pero no 7.0. Los saltos de versión mayor suelen romper compatibilidad.

Cuando ejecutas composer install en una máquina nueva, Composer no mira solo el composer.json — mira el composer.lock y descarga exactamente esas versiones, punto. Así dos desarrolladores trabajando en el mismo proyecto tienen el mismo código de librerías, sin sorpresas.

Conflictos de versiones: el error que más asusta

En algún momento instalarás dos librerías que se pelean entre ellas porque cada una requiere una versión diferente de una tercera librería. Composer te lo dice claramente:

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Root composer.json requires libreria-a ^2.0
    - libreria-a 2.0 requires libreria-c ^1.5
    - libreria-b 3.1 requires libreria-c ^2.0
    - Conclusion: don't install libreria-b 3.1

Lee el error de abajo hacia arriba. Te está diciendo que libreria-a necesita libreria-c en versión 1.x y libreria-b la necesita en versión 2.x, y eso es incompatible. Las opciones son: buscar una versión anterior de una de las dos librerías que sí sea compatible, o buscar una alternativa que no tenga ese conflicto.

Para instalar una versión específica en vez de la última:

# Instalar una versión concreta
composer require libreria-b:3.0.5

# O restringir el rango
composer require "libreria-b:^3.0"

Los comandos del día a día

# Añadir una librería nueva
composer require nombre/libreria

# Clonar un proyecto y tienes composer.json pero no vendor/
composer install

# Actualizar a versiones más recientes dentro del rango del composer.json
composer update

# Actualizar solo una librería concreta, no todo
composer update phpmailer/phpmailer

# Ver qué tienes instalado y en qué versión exacta
composer show

# Ver si hay versiones más nuevas disponibles
composer outdated

Sobre composer update: úsalo con cabeza. Actualiza las librerías a las versiones más recientes dentro del rango permitido y reescribe el composer.lock. Si una librería cambió su API entre versiones — algo que pasa, aunque con menor frecuencia de lo que debería — tu código puede dejar de funcionar. Antes de hacer un update en un proyecto que ya está en producción, prueba en local y verifica que todo sigue bien.