Monorepositorio con PHP: organización del código para proyectos grandes

Monorepositorio con PHP: organización del código para proyectos escalables

En el desarrollo moderno de PHP, la gestión del código se vuelve críticamente importante a medida que el proyecto crece. El enfoque tradicional con múltiples repositorios separados (polirepositorio) a menudo conduce a problemas de sincronización, duplicación de dependencias y dificultades durante la refactorización. La alternativa es el monorepositorio (Monorepo), donde todo el código, incluyendo bibliotecas, utilidades y aplicaciones, se almacena en un único repositorio Git. En este artículo, analizaremos cómo organizar un monorepositorio en PHP utilizando Composer, Git y herramientas modernas.

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

Un monorepositorio es un repositorio único que contiene múltiples proyectos, paquetes o módulos que pueden estar lógicamente relacionados. Para un desarrollador de PHP, esto significa que el núcleo del framework, el servicio API, el panel de administración y las bibliotecas comunes se encuentran en una misma carpeta.

Ventajas del monorepositorio:

• Versión única: Todos los cambios se confirman atómicamente: una corrección en una biblioteca se acompaña inmediatamente de la actualización del código que la utiliza.
• Simplificación de la refactorización: Puede cambiar la interfaz de un paquete y actualizar inmediatamente todas las dependencias dentro de un mismo pull request.
• Estandarización de herramientas: Un único archivo composer.json para la raíz, reglas unificadas de linting y pruebas.
• Reducción de duplicación: El código común (por ejemplo, DTO, helpers) no necesita publicarse en Packagist; está disponible directamente.

Sin embargo, el monorepositorio requiere disciplina: sin una estructura clara, se convierte en un «vertedero». La clave del éxito es una organización adecuada utilizando Composer autoload y submódulos de Git o herramientas especializadas como monorepo-builder.

Estructura de un monorepositorio en PHP

Consideremos una estructura típica para un proyecto PHP que tiene varias bibliotecas y una aplicación. El directorio raíz se ve así:

my-monorepo/├── packages/│   ├── core/                  # Biblioteca base (núcleo)│   │   ├── src/│   │   │   └── CoreClass.php│   │   └── composer.json│   ├── logger/                # Logging│   │   ├── src/│   │   └── composer.json│   └── api/                   # Paquete API (puede ser una aplicación separada)│       ├── src/│       │   └── Controllers/│       └── composer.json├── apps/│   └── web/                   # Aplicación web (Laravel/Symfony)│       ├── public/│       ├── src/│       └── composer.json├── composer.json              # composer.json raíz (meta-paquete)├── phpunit.xml.dist└── .gitignore

Principios de organización:

• Todos los paquetes se encuentran en packages/. Cada paquete tiene su propio composer.json con un nombre único (por ejemplo, mycompany/core).
• Las aplicaciones (frontend, panel de administración, API) están en apps/. Pueden usar los paquetes de packages/ como dependencias locales.
• El composer.json raíz sirve para la configuración global (autoload, scripts).

Configuración de Composer para trabajar con un monorepositorio

Para que la autocarga de PHP funcione sin publicar paquetes en Packagist, utilizamos repositorios path. Agregue el siguiente bloque al composer.json raíz:

{    "name": "mycompany/monorepo",    "require": {        "mycompany/core": "*",        "mycompany/logger": "*"    },    "repositories": [        {            "type": "path",            "url": "packages/*"        }    ],    "autoload": {        "psr-4": {            "MyCompany\\\\": "packages/"        }    },    "scripts": {        "test": "phpunit"    }}

Ahora, al ejecutar composer install, Comp