Composer en PHP: dependencias, autoload y composer.json
Composer es el gestor de dependencias del ecosistema PHP y permite declarar paquetes, instalar bibliotecas, controlar versiones y cargar clases automáticamente. Aprender Composer es uno de los pasos que separa un proyecto PHP compuesto por archivos sueltos de una aplicación organizada mediante namespaces, paquetes y dependencias reproducibles.
¿Qué es Composer en PHP?
Composer es una herramienta para gestionar las dependencias de un proyecto PHP.
En lugar de descargar bibliotecas manualmente y copiar sus archivos dentro del proyecto, declaras qué paquetes necesita tu aplicación y Composer se encarga de instalarlos junto con sus propias dependencias.
También puede generar un sistema de autoload para cargar clases automáticamente, normalmente siguiendo convenciones como PSR-4.
Los archivos principales son composer.json, que declara las necesidades del proyecto, y composer.lock, que registra las versiones concretas utilizadas en una instalación reproducible.
Composer organiza varias piezas que aparecen cuando un proyecto PHP comienza a crecer
Dependencias
Declara bibliotecas que necesita el proyecto.
Versiones
Define rangos compatibles de paquetes.
Autoload
Carga clases sin require manual constante.
Reproducibilidad
Mantiene versiones concretas mediante composer.lock.
Desarrollo
Separa dependencias productivas y de desarrollo.
Ecosistema
Facilita utilizar paquetes PHP reutilizables.
Sin un gestor de dependencias, cada biblioteca puede convertirse en trabajo manual
Supongamos que tu aplicación necesita una biblioteca externa.
Podrías visitar su repositorio, descargar archivos, copiarlos al proyecto y utilizar require manualmente.
El problema aumenta cuando esa biblioteca depende a su vez de otros paquetes.
También necesitas controlar versiones
Una actualización puede introducir cambios incompatibles.
Si varias personas trabajan en el proyecto, todas necesitan instalar dependencias compatibles.
Composer automatiza gran parte de ese proceso
En lugar de almacenar manualmente una colección de bibliotecas, declaras las dependencias del proyecto.
Es una herramienta que administra paquetes utilizados por aplicaciones PHP.
Conviene comprender PHP y POO antes de estudiar Composer en profundidad
Puedes ejecutar Composer sin saber programación orientada a objetos.
Pero gran parte de su utilidad aparece cuando comienzas a organizar clases, namespaces y paquetes.
Aprende primero clases
Composer puede cargar automáticamente las clases de tu aplicación.
Aprende namespaces
Son fundamentales para organizar código moderno y evitar conflictos.
Aprende dependencias
Cuando una clase utiliza otra biblioteca, aparece una relación que debes comprender.
Si clases, interfaces y dependencias todavía te resultan confusas, profundiza primero en POO
Composer tendrá mucho más sentido después.
composer.json describe las dependencias y parte de la configuración del proyecto
El archivo composer.json vive normalmente en la raíz del proyecto.
{
"name": "ciborg/mi-aplicacion",
"description": "Proyecto PHP de ejemplo",
"require": {
"php": "^8.2"
}
}name identifica el paquete
Habitualmente sigue una estructura similar a vendor/proyecto.
require declara dependencias necesarias para ejecutar
Allí pueden aparecer paquetes externos y restricciones de la propia versión de PHP.
Composer lee esa configuración y calcula un conjunto compatible de dependencias.
composer init puede ayudarte a crear composer.json
composer initEl comando realiza una serie de preguntas y genera una configuración inicial.
También puedes crear el archivo manualmente si sabes exactamente qué necesitas.
composer require añade una dependencia al proyecto
composer require vendor/paqueteComposer buscará una versión compatible, actualizará la configuración necesaria e instalará las dependencias.
Después aparecerá dentro de require
{
"require": {
"php": "^8.2",
"vendor/paquete": "^2.0"
}
}También pueden instalarse varias dependencias
Composer se encarga de resolver sus relaciones y restricciones de versiones.
Las restricciones de versión indican qué actualizaciones consideras compatibles
Imagina que tu proyecto utiliza una biblioteca en su versión 2.x.
Puedes declarar un rango en lugar de fijar manualmente un único archivo.
"vendor/paquete": "^2.3"El operador ^ expresa un rango compatible
No significa simplemente “instala siempre la última versión”.
Composer compara las restricciones de todos los paquetes que participan en el proyecto.
Un conflicto puede indicar que dos dependencias necesitan versiones incompatibles entre sí.
Composer instala dependencias dentro del directorio vendor
Después de instalar dependencias, normalmente aparece una estructura similar a esta:
mi-proyecto/
│
├── composer.json
├── composer.lock
├── src/
├── public/
└── vendor/
├── autoload.php
└── ...vendor contiene código administrado por Composer
No deberías editar manualmente los archivos de una dependencia dentro de ese directorio.
La siguiente instalación o actualización podría sobrescribir esos cambios.
Tu código debería vivir fuera de vendor
Por ejemplo, dentro de src/ u otra estructura propia del proyecto.
vendor/autoload.php permite cargar automáticamente clases y paquetes
<?php
require __DIR__ . '/vendor/autoload.php';Esta única inclusión permite utilizar el sistema de carga automática generado por Composer.
Ya no necesitas require para cada clase
En lugar de:
require 'src/Usuario.php';
require 'src/Pedido.php';
require 'src/Producto.php';
require 'src/Notificador.php';puedes configurar reglas de autoload para que las clases se encuentren automáticamente.
Los namespaces ayudan a organizar clases y evitar conflictos de nombres
Dos bibliotecas diferentes podrían tener una clase llamada Usuario.
Los namespaces permiten distinguirlas.
<?php
namespace Ciborg\Usuarios;
final class Usuario
{
}Su nombre completo pasa a ser:
Ciborg\Usuarios\Usuariouse permite importar el nombre
<?php
use Ciborg\Usuarios\Usuario;
$usuario = new Usuario();PSR-4 relaciona namespaces con directorios del proyecto
Supongamos que queremos que todas las clases bajo:
Ciborg\estén dentro del directorio:
src/Podemos declarar:
{
"autoload": {
"psr-4": {
"Ciborg\\": "src/"
}
}
}Entonces una clase puede seguir la estructura del namespace
src/
└── Usuarios/
└── Usuario.phpDentro del archivo:
<?php
namespace Ciborg\Usuarios;
final class Usuario
{
}La configuración de autoload establece la relación entre namespaces y directorios.
composer dump-autoload regenera la configuración de carga automática
Después de modificar determinadas reglas de autoload en composer.json, puedes regenerar los archivos correspondientes.
composer dump-autoloadEsto no equivale a actualizar todas las dependencias.
Su propósito es reconstruir el autoload.
composer.lock registra las versiones concretas resueltas para el proyecto
composer.json puede permitir un rango de versiones.
Por ejemplo:
"vendor/paquete": "^2.3"Pero cuando Composer resuelve la instalación, selecciona versiones concretas compatibles.
Esa resolución se registra en composer.lock.
Esto permite instalaciones reproducibles
Otro desarrollador, CI/CD o servidor puede instalar exactamente el conjunto registrado en el lock.
De lo contrario, distintos entornos podrían resolver versiones diferentes en momentos distintos.
composer install y composer update no hacen exactamente lo mismo
| Comando | Objetivo principal | composer.lock |
|---|---|---|
| composer install | Instalar las dependencias del proyecto | Utiliza las versiones ya registradas cuando existe el lock |
| composer update | Resolver versiones nuevamente según las restricciones | Puede actualizar composer.lock |
install es habitual al desplegar o clonar un proyecto
composer installupdate cambia la resolución de versiones
composer updateActualizar dependencias debería formar parte de un proceso controlado con pruebas.
Puedes actualizar una dependencia concreta sin resolver todo el proyecto desde cero
composer update vendor/paqueteEsto permite limitar el alcance de determinados cambios.
Aun así, debes revisar qué dependencias relacionadas podrían verse afectadas.
Algunas dependencias son necesarias para desarrollar, pero no para ejecutar la aplicación
Herramientas de testing, análisis estático o calidad de código pueden utilizarse únicamente durante desarrollo.
Composer permite declararlas por separado.
{
"require": {
"php": "^8.2"
},
"require-dev": {
"vendor/herramienta-desarrollo": "^1.0"
}
}También puedes añadirlas mediante comando
composer require --dev vendor/herramienta-desarrolloEsta separación documenta mejor qué necesita realmente la aplicación en producción.
Puedes instalar el proyecto sin dependencias de desarrollo
composer install --no-devEsto omite los paquetes declarados en require-dev.
Es útil cuando esas herramientas no son necesarias para ejecutar la aplicación.
Packagist es una de las piezas centrales del ecosistema de paquetes PHP
Cuando utilizas Composer, puedes instalar paquetes publicados dentro del ecosistema.
Antes de añadir una dependencia, no te limites a copiar el primer comando que encuentres.
Revisa quién mantiene el paquete
Una dependencia pasa a formar parte de tu aplicación.
Revisa documentación
Debes saber cómo integrarla, configurarla y actualizarla.
Revisa realmente si la necesitas
Instalar un paquete para evitar escribir cinco líneas puede introducir una dependencia innecesaria.
Puede necesitar actualizaciones, introducir cambios o dejar de ser compatible con otras piezas del proyecto.
Un paquete puede necesitar otros paquetes que tú nunca instalaste directamente
Supongamos que instalas:
Tu aplicación
↓
Paquete A
↓
Paquete B
↓
Paquete CTu proyecto declaró directamente el Paquete A.
Pero A necesita B, y B necesita C.
Composer resuelve ese árbol de dependencias de forma conjunta.
Esto explica muchos conflictos de versiones
Dos paquetes pueden depender de versiones incompatibles de una tercera biblioteca.
composer why ayuda a descubrir por qué existe una dependencia
composer why vendor/paqueteEsto puede ayudarte a identificar qué paquete necesita esa dependencia.
También es útil al investigar conflictos
Comprender el árbol de dependencias suele ser mejor que comenzar a borrar archivos dentro de vendor.
composer remove elimina una dependencia de manera controlada
composer remove vendor/paqueteComposer puede actualizar la configuración y retirar dependencias que ya no sean necesarias.
Es preferible a borrar manualmente un directorio dentro de vendor.
Combinar Composer, namespaces y POO permite una estructura mucho más limpia
app/
│
├── composer.json
├── composer.lock
├── public/
│ └── index.php
│
├── src/
│ ├── Usuarios/
│ │ ├── Usuario.php
│ │ └── UsuarioService.php
│ │
│ ├── Pedidos/
│ │ └── PedidoService.php
│ │
│ └── Database/
│ └── Conexion.php
│
└── vendor/composer.json:
{
"autoload": {
"psr-4": {
"Ciborg\\": "src/"
}
}
}Y el punto de entrada puede cargar Composer una sola vez:
<?php
require dirname(__DIR__)
. '/vendor/autoload.php';
use Ciborg\Usuarios\UsuarioService;Este modelo conecta directamente con la POO
Namespaces, clases, interfaces e inyección de dependencias pasan a integrarse dentro de una estructura coherente.
Composer tiene mucho más sentido cuando entiendes cómo organizar clases
Continúa profundizando en diseño orientado a objetos.
Composer también encaja naturalmente en aplicaciones PHP con base de datos
PDO forma parte del entorno PHP, pero tu proyecto puede utilizar Composer para organizar las clases que encapsulan el acceso a datos.
Por ejemplo
src/
├── Database/
│ └── Conexion.php
│
└── Usuarios/
├── UsuarioRepository.php
└── UsuarioService.phpEl autoload encuentra las clases mientras cada componente mantiene una responsabilidad determinada.
Combina Composer con PDO, SQL y arquitectura
Construye aplicaciones donde acceso a datos no esté mezclado con toda la interfaz.
Composer también puede ser útil dentro de plugins WordPress
WordPress posee su propio ecosistema, pero un plugin personalizado también puede utilizar Composer.
Autoloading
Un plugin grande puede organizar sus clases mediante namespaces y PSR-4.
SDK de terceros
Una integración con pagos, APIs, email u otros servicios puede necesitar paquetes externos.
Separación de responsabilidades
Composer facilita una estructura mucho más mantenible que una colección enorme de require_once.
Un plugin distribuido debe asegurarse de disponer de las dependencias necesarias en el entorno donde se ejecutará.
Comandos de Composer que conviene conocer
| Comando | Uso |
|---|---|
| composer init | Crear configuración inicial. |
| composer require | Añadir una dependencia. |
| composer require –dev | Añadir una dependencia de desarrollo. |
| composer install | Instalar dependencias del proyecto. |
| composer update | Resolver versiones y actualizar lock. |
| composer remove | Eliminar una dependencia. |
| composer dump-autoload | Regenerar autoload. |
| composer why | Investigar por qué existe un paquete. |
Qué evitar cuando comienzas a utilizar Composer
En qué orden aprender Composer
PHP y POO
Comprende clases, namespaces y dependencias.
composer.json
Aprende qué declara el proyecto.
require
Añade tu primer paquete.
vendor
Comprende dónde viven las dependencias.
Autoload
Elimina require manuales innecesarios.
Namespaces
Organiza clases correctamente.
PSR-4
Relaciona namespace y directorios.
composer.lock
Comprende versiones reproducibles.
install vs update
Controla las actualizaciones.
Proyecto real
Aplica Composer con POO, PDO o WordPress.
Recursos que conviene aprender a consultar
Documentación oficial de Composer — instalación, comandos, configuración y conceptos principales.
Uso básico de Composer — composer.json, instalación y lock.
Esquema de composer.json — campos disponibles y configuración.
PSR-4 — especificación de autoloading utilizada ampliamente en PHP.
Packagist — exploración de paquetes del ecosistema Composer.
Composer convierte dependencias y autoloading en partes explícitas de un proyecto PHP
composer.json declara qué necesita tu proyecto.
Composer resuelve versiones compatibles entre paquetes.
composer.lock registra la resolución concreta utilizada por una aplicación.
vendor contiene dependencias administradas por Composer.
vendor/autoload.php permite utilizar carga automática.
PSR-4 conecta namespaces con directorios.
require-dev separa herramientas que solo necesitas durante desarrollo.
La verdadera utilidad de Composer aparece cuando dejas de pensar en PHP como una colección de archivos y comienzas a verlo como un proyecto con clases, paquetes y dependencias controladas.
Continúa profundizando en PHP
Preguntas sobre Composer en PHP
Composer es un gestor de dependencias para PHP. Permite declarar, instalar y actualizar paquetes utilizados por una aplicación y también generar un sistema de autoload.
composer.json es el archivo donde se declaran dependencias y otras configuraciones del proyecto, como reglas de autoloading.
composer.lock registra las versiones concretas de las dependencias resueltas por Composer. En una aplicación permite que diferentes entornos instalen el mismo conjunto de versiones.
composer install instala las dependencias del proyecto y utiliza composer.lock cuando está disponible. composer update vuelve a resolver versiones según las restricciones de composer.json y puede actualizar el archivo lock.
vendor es el directorio donde Composer instala las dependencias y genera archivos relacionados con autoloading. No debería editarse manualmente el código de los paquetes instalados allí.
PSR-4 es una especificación de autoloading que permite relacionar namespaces PHP con directorios dentro de un proyecto. Composer puede generar el autoload correspondiente.
No necesitas Composer para ejecutar pequeños scripts PHP. Sin embargo, resulta muy importante en proyectos modernos que utilizan paquetes, namespaces, autoloading y múltiples dependencias.
Sí. Un plugin WordPress puede utilizar Composer para organizar autoloading e incorporar dependencias. Debe controlarse correctamente cómo se empaquetan y distribuyen esas dependencias dentro del entorno WordPress.
Cuando dominas Composer, namespaces y autoloading, PHP deja de sentirse como una colección de archivos sueltos
Aprende composer.json, composer.lock, require, install, update, PSR-4 y dependencias. Después combínalos con POO, MySQL y proyectos reales.
Continuar con POO en PHP →