Composer es el gestor de dependencias estándar de PHP. Permite declarar las librerías que necesita un proyecto, descargarlas con sus versiones exactas y generar el autoloader automáticamente. El fichero composer.json describe las dependencias y composer.lock fija las versiones instaladas para garantizar reproducibilidad entre entornos.
composer.json: estructura básica
El fichero composer.json reside en la raíz del proyecto y describe el paquete, sus dependencias de producción (require), las de desarrollo (require-dev) y la configuración del autoloading.
<?php
// composer.json
// {
// "name": "miempresa/mi-proyecto",
// "description": "Aplicación web en PHP",
// "type": "project",
// "require": {
// "php": "^8.2",
// "guzzlehttp/guzzle": "^7.8",
// "vlucas/phpdotenv": "^5.6",
// "nesbot/carbon": "^3.0",
// "monolog/monolog": "^3.5"
// },
// "require-dev": {
// "phpunit/phpunit": "^11.0",
// "symfony/var-dumper": "^7.0"
// },
// "autoload": {
// "psr-4": {
// "App\": "src/"
// }
// },
// "autoload-dev": {
// "psr-4": {
// "Tests\": "tests/"
// }
// }
// }
?>
composer install y composer update
composer install descarga las versiones exactas registradas en composer.lock. Si no existe el fichero lock, resuelve las versiones y lo genera. composer update actualiza a las versiones más recientes compatibles con las restricciones de composer.json y regenera el lock. En producción siempre se usa install; en desarrollo se puede usar update.
<?php // Comandos de consola (no PHP, se ejecutan en la terminal) // Instalar a partir del lock file (reproducible): // composer install --no-dev --optimize-autoloader // Añadir una dependencia nueva: // composer require monolog/monolog // Añadir dependencia solo de desarrollo: // composer require --dev phpunit/phpunit // Actualizar un paquete concreto: // composer update nesbot/carbon // Actualizar todo (con cuidado en producción): // composer update // Regenerar el autoloader sin instalar nada: // composer dump-autoload --optimize ?>
La carpeta vendor/ y .gitignore
Composer descarga todos los paquetes en la carpeta vendor/. Esta carpeta no debe incluirse en el repositorio de git: es reproducible a partir del composer.lock, contiene binarios de distintas plataformas y puede tener un tamaño considerable. El fichero composer.lock, en cambio, sí debe versionarse para garantizar que todos los desarrolladores y entornos usan exactamente las mismas versiones.
<?php // .gitignore // /vendor/ ? nunca en git // .env ? tampoco las variables de entorno // composer.lock ? SÍ en git (garantiza reproducibilidad) // composer.json ? SÍ en git (describe las dependencias) // En el código, solo hace falta un require: require __DIR__ . '/vendor/autoload.php'; ?>
Versionado semántico en composer.json
Composer utiliza restricciones de versión para indicar qué versiones son compatibles. El operador ^ (caret) permite actualizaciones que no rompen compatibilidad hacia atrás según semver. El operador ~ (tilde) es más restrictivo.
<?php // Restricciones de versión más habituales: // ^7.8 => >=7.8.0 <8.0.0 (permite minor y patch, no major) // ^3.0 => >=3.0.0 <4.0.0 // ~7.8 => >=7.8.0 <7.9.0 (solo permite patch) // 7.8.* => >=7.8.0 <7.9.0 (equivalente a ~7.8) // 7.8.3 => exactamente 7.8.3 (no recomendado, muy rígido) // * => cualquier versión (nunca usar en producción) // Para librerías (no proyectos), no fijar versiones exactas: // "guzzlehttp/guzzle": "^7.0 || ^6.5" // compatible con v6 y v7 ?>
Cuatro ejemplos reales con paquetes populares
<?php
require __DIR__ . '/vendor/autoload.php';
use GuzzleHttpClient;
use DotenvDotenv;
use CarbonCarbon;
use MonologLogger;
use MonologHandlerStreamHandler;
// 1. Cargar variables de entorno desde .env
$dotenv = Dotenv::createImmutable(__DIR__);
$dotenv->load();
// 2. Petición HTTP con Guzzle
$http = new Client(['base_uri' => 'https://api.ejemplo.com/']);
$respuesta = $http->get('usuarios/42');
$datos = json_decode((string) $respuesta->getBody(), true);
// 3. Fechas legibles con Carbon
$creado = Carbon::parse($datos['fecha_creacion']);
echo $creado->diffForHumans(); // "hace 3 meses"
// 4. Logs estructurados con Monolog
$log = new Logger('app');
$log->pushHandler(new StreamHandler(__DIR__ . '/var/log/app.log', Logger::DEBUG));
$log->info('Usuario cargado', ['id' => $datos['id'], 'nombre' => $datos['nombre']]);
?>
La documentación oficial de Composer explica la gestión de repositorios privados, la publicación de paquetes en Packagist, los scripts de Composer para automatizar tareas y las opciones de instalación para entornos de CI/CD.