Contents
Introducción
Este artículo explica con todo lujo de detalles cómo integrar Composer en un plugin de WordPress. Cubriremos desde la configuración inicial de composer.json, autoload con PSR-4, buenas prácticas para evitar conflictos con otros plugins, opciones de despliegue (publicación en WordPress.org o empaquetado en ZIP), y ejemplos prácticos de código y comandos. El objetivo es que tu plugin use dependencias modernas y un autoload robusto sin romper el ecosistema WordPress.
Por qué usar Composer en un plugin de WordPress
- Gestión de dependencias: declarar versiones, actualizarlas y reproducir instalaciones con composer.lock.
- Autoloading: evitar require manuales y cargar clases según namespaces (PSR-4).
- Organización del código: separación clara entre código del plugin y librerías externas en vendor/.
- Optimización: usar dump-autoload optimizado en producción para mejor rendimiento.
Requisitos y consideraciones previas
- Composer (versión 2 recomendada) instalado en tu entorno de desarrollo.
- Servidor con la versión mínima de PHP requerida por tus dependencias y tu plugin.
- Decidir si vas a incluir vendor/ en el paquete final (recomendado incluirlo para compatibilidad en entornos sin Composer).
- Escoger un namespace único para evitar colisiones con otros plugins.
Estructura recomendada del plugin
Ejemplo de estructura de carpetas que usaremos:
- mi-plugin/
- composer.json
- composer.lock
- vendor/
- src/
- Plugin.php
- Admin/OptionsPage.php
- mi-plugin.php (archivo principal del plugin con cabecera WP)
- README.md
- .gitignore
Paso 1 — Crear composer.json
Crea un composer.json en la raíz del plugin. Define el nombre, descripción, autoload PSR-4 y las dependencias necesarias.
{
name: tu-vendor/mi-plugin,
description: Un plugin de ejemplo que usa Composer para gestionar dependencias.,
type: wordpress-plugin,
license: GPL-2.0-or-later,
require: {
php: >=7.4,
monolog/monolog: ^2.0
},
autoload: {
psr-4: {
TuVendorMiPlugin: src/
}
},
extra: {
class: TuVendorMiPluginPlugin
}
}
Notas importantes sobre composer.json
- type: wordpress-plugin — no es obligatorio pero puede ayudar a algunos instaladores y herramientas.
- PSR-4 — define un namespace único para tu plugin. Esto reduce riesgo de colisiones.
- Dependencias externas — declara solo lo estrictamente necesario evita paquetes enormes si no son imprescindibles.
Paso 2 — Instalar dependencias
Desde la carpeta raíz del plugin, ejecuta:
composer install
O para añadir una dependencia nueva:
composer require vendor/package
Paso 3 — Conectar el autoload en el archivo principal del plugin
El archivo principal del plugin (por ejemplo mi-plugin.php) debe incluir el autoloader generado por Composer. Usa una ruta relativa segura con __DIR__.
Ejemplo de clase principal (PSR-4)
Autoload y mejores prácticas de namespacing
- Usa nombres de vendor únicos (p. ej. TuVendor) y evita nombres genéricos como Plugin.
- Organiza código en src/ y subnamespaces (Admin, Frontend, API).
- Evita declarar funciones globales no prefijadas usa métodos de clase o funciones estáticas si realmente necesitas funciones globales.
Optimización del autoload para producción
Para producir un autoload más rápido y precomputado usa:
composer dump-autoload -o
Opciones adicionales:
- --classmap-authoritative para forzar classmap como fuente de truth (útil si quieres máxima velocidad y control).
- Incluir en scripts de CI/CD para que el ZIP final contenga el autoload optimizado.
Control de versiones y .gitignore
Decide si vas a subir vendor/ a tu repositorio. Recomendado: en desarrollo ignorarlo y en lanzamientos empaquetarlo. Un .gitignore típico:
/vendor/ /composer.lock node_modules/ /dist/
Sin embargo, si vas a publicar en WordPress.org mediante SVN, debes incluir las dependencias en la carpeta del plugin que subas al repo SVN de lo contrario el plugin no tendrá las librerías en entornos donde Composer no se ejecuta.
Distribución: empaquetado y publicación en WordPress.org
- Si subes a WordPress.org (SVN), incluye el contenido de vendor/ en el paquete final.
- Si publicas en GitHub/Packagist, puedes optar por no incluir vendor/ y dejar que los usuarios instalen con Composer, pero muchos usuarios de WordPress no usan Composer, por lo tanto empaqueta un release con vendor replicado.
- Usa scripts de build (npm scripts, GitHub Actions, etc.) para generar el ZIP con dependencias y autoload optimizado.
Ejemplo de flujo de CI simple (concepto)
- Checkout del repo.
- composer install --no-dev --prefer-dist
- composer dump-autoload -o
- Empaquetar carpeta del plugin en ZIP (incluye vendor/).
- Subir ZIP a marketplace o al repositorio de WordPress.
Evitar conflictos con otros plugins
- Prefiere nombres de namespaces únicos para tus clases.
- Si dependes de paquetes comunes (p. ej. Monolog), ten en cuenta que otro plugin puede cargar otra versión Composer no resuelve esto a nivel de ejecución, solo a nivel de instalación. Para minimizar riesgos:
- Usa namespaces propios y no funciones globales del paquete.
- Si una biblioteca se usa ampliamente y puede causar colisión, considera scoping o prefijado (herramientas como php-scoper) para renombrar el vendor/namespace en el bundle final.
- Evita declarar constantes globales con nombres comunes.
Compartir dependencias entre plugins (opcional y avanzado)
En instalaciones donde controlas el servidor, puedes centralizar un vendor/ compartido y cargarlo desde un mu-plugin que requiera el autoload root. Esto no es estándar y puede causar problemas de mantenimiento úsalo solo si controlas el ecosistema. Alternativa segura: dejar cada plugin autoloadear sus propias dependencias o usar php-scoper para que no colisionen.
Seguridad y mantenimiento
- Mantén composer.lock versionado para reproducibilidad.
- Revisa vulnerabilidades con
composer audit
(Composer 2) o herramientas externas.
- Actualiza dependencias regularmente y prueba en un entorno staging.
Ejemplo práctico completo
Pasos resumidos y comandos concretos que seguirás en desarrollo:
- Inicializa Composer:
composer init - Agregar dependencias:
composer require monolog/monolog - Generar autoload optimizado antes del release:
composer install --no-dev --prefer-dist composer dump-autoload -o - Asegurarte de que en el archivo principal del plugin existe:
require_once __DIR__ . /vendor/autoload.php - Empaquetar y subir (o commitear vendor a la rama release para WordPress.org).
Uso de php-scoper para evitar colisiones (opcional)
Si tu plugin incluye librerías que podrían colisionar con otras, considera usar php-scoper durante el build para prefijar namespaces. Flujo típico:
- Instalar php-scoper como dependencia de desarrollo.
- Ejecutar php-scoper para generar una versión scoped del paquete en la carpeta de distribución.
- Empaquetar esa carpeta y subirla. Esto evita casi por completo conflictos de versiones compartidas.
Preguntas frecuentes rápidas
- ¿Debo incluir vendor en Git? En desarrollo no en el release final (WordPress.org o un ZIP) sí, para asegurar que el plugin funcione sin Composer en el servidor destino.
- ¿Qué pasa si otro plugin carga diferente versión de la misma librería? Puede producir errores si ambas librerías comparten el mismo namespace o funciones globales. El scope/prefix o php-scoper resuelve esto.
- ¿Composer hace el autoload más lento? No de forma perceptible si usas autoload optimizado (-o) y classmap donde sea apropiado.
Resumen y recomendaciones finales
- Usa Composer para manejar dependencias y PSR-4 para autoload.
- Incluye vendor en paquetes distribuidos si el entorno destino no ejecuta Composer.
- Prefiere namespaces únicos y considera herramientas como php-scoper para aislar dependencias en producción.
- Automatiza la generación del paquete con CI para incluir vendor y autoload optimizado.
- Mantén composer.lock en control de versiones y monitoriza vulnerabilidades.
Recursos útiles
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |