Qué es Composer y cómo usarlo en tus proyectos PHP

Si programas en PHP, Composer es una de esas herramientas que usas todos los días casi sin pensarla. Y si estás empezando, probablemente ya lo ejecutaste alguna vez copiando un comando de un tutorial, sin tener del todo claro qué hacía.

En este artículo vamos a ver qué es Composer, qué problema resuelve, cómo funcionan los dos archivos que lo controlan y cuáles son los comandos que realmente necesitas.

Qué es Composer

Composer es la herramienta de administración de dependencias de PHP. Permite simplificar y automatizar la gestión de las bibliotecas y paquetes que un proyecto necesita para funcionar, en lugar de descargarlos uno por uno de forma manual.

Es multiplataforma y funciona en Windows, Linux y macOS. Está ampliamente adoptado en la comunidad de PHP: hoy prácticamente cualquier proyecto serio, y desde luego cualquier proyecto Laravel, se apoya en él.

Si vienes de JavaScript, la comparación directa es npm. Si no, piénsalo así: Composer es la lista de compras de tu proyecto. Tú anotas qué necesitas, y él se encarga de traerlo, de traer lo que a su vez eso necesite, y de que todo sea compatible entre sí.

El problema que resuelve

Para entender por qué importa, vale la pena recordar cómo era antes.

Sin Composer, si querías usar una librería la descargabas en un .zip desde su página, la descomprimías dentro de tu proyecto y la incluías a mano:

require 'librerias/PHPMailer/src/PHPMailer.php';
require 'librerias/PHPMailer/src/SMTP.php';
require 'librerias/PHPMailer/src/Exception.php';

Y ahí empezaban los problemas de verdad:

• Las dependencias de tus dependencias. Esa librería necesitaba otras dos, que a su vez necesitaban otra. Había que ir a buscarlas una por una.
• Las actualizaciones. Salía una versión con un fallo de seguridad corregido y tocaba repetir todo el proceso a mano.
• El «en mi máquina funciona». Cada integrante del equipo tenía versiones ligeramente distintas y nadie sabía cuáles.

Composer resuelve los tres. Declaras qué necesitas, y él calcula el resto.

Instalar Composer

En Windows hay un instalador .exe que lo deja configurado y disponible desde cualquier terminal. Si usas Laragon no necesitas hacer nada: ya viene incluido, junto con PHP, y puedes verlo en la guía de instalación de Laragon.

En Linux y macOS la instalación se hace por línea de comandos, siguiendo los pasos del sitio oficial.

Para comprobar que quedó bien:

composer --version

Deberías ver algo como Composer version 2.10.2. Al momento de actualizar este artículo esa es la versión estable, y requiere PHP 7.2 o superior.

composer.json: el archivo que lo define todo

Este es el corazón de Composer. Es un archivo de texto, en la raíz de tu proyecto, donde declaras lo que necesitas:

{
    "require": {
        "php": "^8.2",
        "guzzlehttp/guzzle": "^7.8"
    },
    "require-dev": {
        "phpunit/phpunit": "^11.0"
    }
}

Fíjate en dos cosas.

Hay dos bloques. require es lo que el proyecto necesita para funcionar en producción. require-dev es lo que solo hace falta mientras desarrollas: herramientas de pruebas, depuradores, generadores de código. En el servidor de producción esas no se instalan.

El símbolo ^ no es decorativo. Indica hasta dónde puede actualizarse un paquete de forma automática:

• ^7.8 acepta cualquier versión desde la 7.8 hasta antes de la 8.0. Es decir, correcciones y mejoras, pero nada que rompa.
• ~7.8 es más restrictivo: solo acepta hasta antes de la 7.9.
• 7.8.1 fija esa versión exacta y no se mueve.

En general ^ es lo que quieres, porque te trae las correcciones de seguridad sin cambios que rompan tu código.

composer.lock: el archivo que nadie debe borrar

Cuando ejecutas Composer por primera vez, además de descargar todo genera un composer.lock. Ese archivo anota la versión exacta que quedó instalada de cada paquete, incluidas las dependencias de tus dependencias.

Por qué importa: tu composer.json dice «quiero Guzzle 7.x». El composer.lock dice «quedó instalada la 7.8.1». Gracias a eso, cuando otra persona del equipo o el servidor de producción instalen el proyecto, van a recibir exactamente las mismas versiones que tú tienes.

Dos reglas que se derivan de esto:

• El composer.lock sí va al repositorio. Es lo que garantiza que todos trabajen sobre lo mismo.
• No lo borres para «arreglar» un error. Borrarlo no arregla nada: solo hace que la próxima instalación traiga versiones distintas y que el problema aparezca en otro lado.

install o update: la confusión más común

Estos dos comandos parecen intercambiables y no lo son. Es probablemente el punto donde más se equivoca quien empieza.

composer install

Lee el composer.lock e instala exactamente esas versiones. Si el archivo no existe, lo genera. Este es el comando que usas el 95 % de las veces: al clonar un proyecto, al desplegar a producción, al empezar el día.

composer update

Ignora las versiones fijadas, va a buscar las versiones más nuevas que permita tu composer.json y reescribe el composer.lock. Esto es lo que quieres cuando deliberadamente vas a actualizar dependencias, con tiempo para probar que nada se rompió.

La regla práctica: nunca ejecutes composer update en producción. Ahí siempre composer install, y con esto:

composer install --no-dev --optimize-autoloader

Así no instalas herramientas de desarrollo en el servidor y el autoload queda optimizado.

Los comandos que vas a usar

Agregar un paquete nuevo, que además lo escribe en tu composer.json:

composer require guzzlehttp/guzzle

Agregarlo solo para desarrollo:

composer require --dev phpunit/phpunit

Quitar un paquete:

composer remove guzzlehttp/guzzle

Ver qué tienes instalado y en qué versión:

composer show

Y uno que te va a salvar más de una vez, cuando PHP se queja de que no encuentra una clase que sí existe:

composer dump-autoload

El autoload: por qué dejas de escribir require

Esta es la ventaja de Composer que menos se explica y más se disfruta.

Composer genera un archivo, vendor/autoload.php, que sabe dónde vive cada clase de cada paquete. Lo incluyes una sola vez:

require 'vendor/autoload.php';

Y a partir de ahí, cualquier clase que uses se carga sola, en el momento en que la necesitas. Se acabaron las veinte líneas de require al inicio de cada archivo.

Esto funciona gracias al estándar PSR-4, que asocia un espacio de nombres con una carpeta. Y no es solo para paquetes externos: puedes declarar tu propio código en el composer.json y aprovecharlo igual:

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Con eso, la clase App\Models\Cliente se busca sola en src/Models/Cliente.php. En Laravel esto ya viene configurado, y es la razón por la que nunca escribes un require en un proyecto Laravel.

La carpeta vendor no va a Git

Todo lo que Composer descarga queda en la carpeta vendor. Esa carpeta no se sube al repositorio: se reconstruye con un solo comando a partir del composer.json y el composer.lock.

En tu .gitignore:

/vendor

Subirla infla el repositorio con miles de archivos que no escribiste. Si te suena a poco, mira qué es Git para entender por qué el historial no perdona.

Composer y Laravel

Laravel se instala y se mantiene con Composer, así que si trabajas con el framework ya lo estás usando aunque no lo notes. Un laravel new o un composer create-project es Composer resolviendo decenas de paquetes por ti.

Y cuando clonas un proyecto Laravel de un compañero, el primer comando es siempre el mismo:

composer install

Errores comunes

• Ejecutar composer update cuando querías install. Te actualiza medio proyecto sin querer, y el fallo aparece en otro lado dos días después.
• No subir el composer.lock al repositorio. Ahí nace el clásico «en mi máquina funciona».
• Subir la carpeta vendor. No aporta nada y ensucia todos los cambios.
• Instalar dependencias de desarrollo en producción. Además de peso, algunas exponen información que no debería estar en un servidor público.
• Editar archivos dentro de vendor. Se pierden en la próxima instalación. Si necesitas cambiar el comportamiento de un paquete, hay formas correctas de hacerlo.

Para cerrar

Composer es una herramienta esencial para la gestión de dependencias en proyectos PHP y, muy en particular, en Laravel. Facilita enormemente la tarea de administrar las bibliotecas y paquetes que un proyecto necesita.

Si tuviera que resumir lo importante en tres líneas: el composer.json dice qué quieres, el composer.lock dice qué te tocó, y install respeta el lock mientras update lo reescribe. Con eso claro, el resto se aprende usándolo.

En Norvic Software trabajamos con este stack a diario. Si tu empresa necesita un sistema hecho a medida, puedes ver cómo lo desarrollamos o todo lo que hacemos.

Saludos y éxitos.