Monorepositorio con PHP: organización del código y mejores prácticas

Monorepositorio con PHP: organización del código y mejores prácticas

En el desarrollo moderno de PHP, cada vez surge más la pregunta sobre la organización eficiente del código. El enfoque tradicional con múltiples repositorios separados (multirrepositorio) tiene sus desventajas: complejidad en la sincronización de versiones, duplicación de configuraciones y problemas con la refactorización. Como alternativa se presenta el monorepositorio (monorepo) — una estrategia donde todos los proyectos, paquetes y bibliotecas relacionados se almacenan en un único repositorio. En este artículo, analizaremos cómo organizar un monorepositorio con PHP, qué herramientas utilizar y qué obstáculos considerar.

¿Qué es un monorepositorio y por qué es necesario para proyectos PHP?

Un monorepositorio es un almacén de código único que contiene varios proyectos o paquetes. En el mundo de PHP, un ejemplo clásico es Laravel, que incluye el framework, paquetes para autenticación, colas, correo y otros componentes en un solo repositorio.

Principales ventajas para proyectos PHP:

• Simplificación de la refactorización — los cambios en un paquete son visibles inmediatamente para todos los componentes dependientes, sin necesidad de publicar y actualizar versiones de cada paquete por separado.
• Integridad de versiones — todos los paquetes utilizan la misma versión de dependencias, lo que elimina conflictos de tipos.
• CI/CD unificado — un único pipeline de compilación para todos los componentes, simplificando las pruebas de cambios entre paquetes.
• Mejora del trabajo colaborativo — los desarrolladores ven todo el código del proyecto, facilitando las revisiones de código y el mantenimiento de estándares de codificación uniformes.

Sin embargo, el monorepositorio no es adecuado para todos. Si tus proyectos están débilmente acoplados o tienen ciclos de lanzamiento diferentes, el multirrepositorio puede ser más conveniente. Para proyectos PHP medianos y grandes con integración estrecha de componentes, el monorepositorio suele ser la opción óptima.

Estructura de un monorepositorio en PHP

Una estructura correcta es la base de un monorepositorio exitoso. Consideremos una organización típica usando un ejemplo de proyecto con un núcleo (core), varios módulos y pruebas.

my-php-monorepo/├── packages/│   ├── core/│   │   ├── src/│   │   │   └── CoreService.php│   │   ├── tests/│   │   └── composer.json│   ├── module-auth/│   │   ├── src/│   │   ├── tests/│   │   └── composer.json│   └── module-payment/│       ├── src/│       ├── tests/│       └── composer.json├── apps/│   ├── api/│   │   ├── public/│   │   ├── src/│   │   └── composer.json│   └── console/│       ├── src/│       └── composer.json├── tests/│   └── IntegrationTest.php├── composer.json (raíz)├── phpunit.xml.dist├── .gitignore└── README.md

Principios clave de organización:

• Separación en paquetes (packages) — cada paquete tiene su propio composer.json con nombre, autocarga y dependencias.
• Aplicaciones (apps) — puntos de entrada (API, comandos de consola) que integran los paquetes.
• composer.json raíz — contiene la metaconfiguración para trabajar con el monorepositorio.

Configuración del composer.json raíz

Para que el monorepositorio funcione, es necesario configurar el composer.json raíz de modo que los paquetes estén disponibles localmente, sin necesidad de publicarlos en Packagist.

{    "name": "my-company/my-monorepo",    "type": "project",    "require": {        "php": "^8.1",        "my-company/core": "*",        "my-company/module-auth": "*",        "my-company/module-payment": "*"    },    "autoload": {        "psr-4": {            "MyCompany\\\\": "packages/"        }    },    "repositories": [        {            "type": "path",            "url": "packages/*",            "options": {                "symlink": true            }        }    ],    "scripts": {        "
```