> ## Documentation Index > Fetch the complete documentation index at: https://kawax.biz/llms.txt > Use this file to discover all available pages before exploring further. # Gestión de la compatibilidad de versiones de paquetes > Explica la estrategia de mantenimiento de paquetes ante grandes actualizaciones de Laravel y PHP: desde la actualización de composer.json hasta la configuración de la matriz de tests en GitHub Actions. Laravel publica una nueva versión mayor cada año, en torno a febrero o marzo. Para el desarrollador de un paquete, atender rápido las nuevas versiones es una contribución al ecosistema y un factor clave que refuerza la fiabilidad del propio paquete. Esta página es hermana de [Fundamentos del desarrollo de paquetes](/es/advanced/package-development). Se asume conocimiento básico del desarrollo de paquetes (service providers, estructura de `composer.json`, etc.). ## Adaptarse a las nuevas versiones mayores de Laravel ### Flujo de la migración Añade la nueva versión al rango de dependencias. Si sigues dando soporte a las anteriores, concaténalas con `||`. ```json theme={null} "require": { "php": "^8.2", "illuminate/support": "^12.0||^13.0" } ``` Cuando finalices la adaptación y quites el soporte a las versiones antiguas, elimina las restricciones que ya no correspondan. ```json theme={null} "require": { "php": "^8.3", "illuminate/support": "^13.0||^14.0" } ``` Dependiendo solo de los componentes necesarios (`illuminate/support`, etc.) en vez de `illuminate/framework` completo, mantienes el árbol de dependencias pequeño. En local o en el entorno CI, ejecuta los tests con la nueva versión de Laravel. ```shell theme={null} composer update vendor/bin/pest ``` Si los tests pasan, has confirmado la compatibilidad básica. Si no, corrige las APIs modificadas o los métodos eliminados. Añade la nueva versión de Laravel a la matriz de CI para vigilar de forma continua la compatibilidad. Consulta el [ejemplo de matriz de tests](#ejemplo-de-configuracion-de-la-matriz-de-tests). Etiqueta y publica una nueva versión que incluya el cambio de `composer.json`. Con solo un `composer update`, los usuarios ya podrán instalarla en la nueva Laravel. ### Toma como referencia los paquetes oficiales Cuando dudes sobre cómo adaptarte, lo más fiable es revisar el `composer.json` de los paquetes oficiales de Laravel. * [laravel/socialite](https://github.com/laravel/socialite) * [laravel/horizon](https://github.com/laravel/horizon) * [laravel/telescope](https://github.com/laravel/telescope) Estos paquetes los mantiene el equipo de Laravel, así que se adaptan muy rápido a las nuevas versiones y son un buen ejemplo de cómo escribir las restricciones de `illuminate/*`. ## Actualización del requisito de PHP Al subir de versión, Laravel también suele elevar el requisito mínimo de PHP. Ajusta el requisito de PHP en el `composer.json` de tu paquete. | Laravel | PHP mínimo | | ---------- | ---------- | | Laravel 11 | PHP 8.2 | | Laravel 12 | PHP 8.2 | | Laravel 13 | PHP 8.3 | | Laravel 14 | PHP 8.4 | ```json theme={null} "require": { "php": "^8.2", "illuminate/support": "^11.0||^12.0||^13.0" } ``` ### Si quieres usar las nuevas funciones de PHP Para utilizar funciones a partir de PHP 8.3 (constantes tipadas, nuevas funciones de aleatoriedad, etc.), tendrás que subir el requisito mínimo. Elevar el requisito mínimo es, según el versionado semántico, un cambio rompedor, por lo que es más adecuado hacerlo en una nueva versión mayor de tu paquete. ```json theme={null} "require": { "php": "^8.3", "illuminate/support": "^12.0||^13.0" } ``` Al elevar el requisito mínimo de PHP, los usuarios con PHP más antiguo no podrán actualizar el paquete. Es importante avisarles previamente en el README y el CHANGELOG. ## Estrategia para retirar el soporte a versiones antiguas Mantener versiones antiguas indefinidamente eleva mucho el coste de mantenimiento a largo plazo. Establecer una política de soporte clara y retirar versiones antiguas de forma periódica es lo que sostiene un paquete saludable. ### Cuándo retirar el soporte Un enfoque habitual es **alinearse con el ciclo de soporte de Laravel**. Laravel ofrece 18 meses de correcciones de bugs y 2 años de correcciones de seguridad por versión. Si tu paquete adopta una política parecida, será más fácil de entender para los usuarios. | Criterio | Descripción | | --------------------------------- | ---------------------------------------------------------------------------------------------------- | | Fin de soporte oficial de Laravel | Retira la compatibilidad cuando termina el soporte oficial de esa versión de Laravel. | | Uso real | Cuando los datos de descarga de Packagist muestran que los usuarios de la versión antigua son pocos. | | Coste de añadir funcionalidad | Cuando dar soporte a la versión antigua complica implementar nuevas funcionalidades. | ### Declara la política de soporte en el README Para que los usuarios tengan expectativas realistas, incluye la política de soporte en `README.md`. ```markdown theme={null} ## Version Compatibility | Package | Laravel | PHP | |---------|---------|------| | 3.x | 13.x | ^8.2 | | 2.x | 11.x, 12.x | ^8.2 | | 1.x | 10.x | ^8.1 | Only the latest major version receives new features. Security fixes are backported to the previous major version for 12 months. ``` ### El coste de mantener versiones antiguas Mantener el soporte a versiones antiguas conlleva estos costes: * **Doble corrección de bugs** — hay que arreglar el mismo bug en varias ramas. * **Aumento del código condicional** — complejidad para absorber en condicionales las diferencias entre versiones. * **Matriz de tests inflada** — el tiempo de CI crece. * **Complicación de los parches de seguridad** — hay que hacer backport seguro también a las versiones antiguas. En un ecosistema que va subiendo de versión, retirar a tiempo el soporte de las versiones antiguas también anima a los usuarios a migrar a entornos actuales. ## Ventajas de reaccionar pronto Si tienes la adaptación lista a la vez que sale la nueva Laravel, los usuarios podrán migrar de inmediato. Es una señal importante de la fiabilidad de tu paquete. ### Prueba previa con la versión de desarrollo Laravel no publica beta/RC, pero puedes instalar la próxima versión con `dev-master` o `@dev`. Al confirmar el comportamiento antes de la release mayor, puedes conseguir compatibilidad «día cero». ```shell theme={null} # Instala la próxima versión con dev-master composer require laravel/framework:dev-master --no-update composer update vendor/bin/pest ``` También puedes instalarla con la restricción `@dev`. ```shell theme={null} composer require laravel/framework:^14.0@dev --no-update composer update vendor/bin/pest ``` Ajustando `minimum-stability` a `dev`, puedes resolver las dependencias con la versión de desarrollo. ```json theme={null} { "minimum-stability": "dev", "prefer-stable": true } ``` Con `prefer-stable: true`, cuando existe una versión estable, se elige la estable. Te permite probar con las versiones de desarrollo garantizando el paso automático a estables cuando corresponda. ### El primer paso puede ser solo cambiar composer.json Aun antes de tener la compatibilidad totalmente verificada, con solo actualizar el rango de dependencias en `composer.json` y publicar la nueva versión, los usuarios ya pueden instalar tu paquete. ```json theme={null} "illuminate/support": "^12.0||^13.0" ``` Los defectos menores se pueden corregir después con una versión de patch. Prioriza que el paquete sea instalable en lugar de esperar a la perfección. ### Cómo seguir la información de releases Métodos para enterarte a tiempo de las nuevas versiones: | Fuente | Contenido | | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Watch de GitHub | Actívalo en el repositorio: «Watch → Custom → Releases» para recibir notificaciones por correo. Registra también los paquetes principales aparte del framework. | | [Blog oficial de Laravel](https://laravel.com/blog) | Anuncios de releases mayores y descripción de nuevas funciones. | | [Guía oficial de actualización](https://laravel.com/docs/upgrade) | Lista de cambios rompedores. | | [Log de commits de laravel/framework](https://github.com/laravel/framework/commits/master) | Para adelantarte a la próxima versión, sigue directamente los commits. | ## Ejemplo de configuración de la matriz de tests Ejemplo de workflow de GitHub Actions que ejecuta tests automáticamente contra varias combinaciones de Laravel y PHP. ```yaml theme={null} name: Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest strategy: fail-fast: false matrix: php: [8.2, 8.3, 8.4] laravel: ["^12.0", "^13.0"] include: - laravel: "^13.0" testbench: "^10.0" - laravel: "^12.0" testbench: "^9.0" name: PHP ${{ matrix.php }} - Laravel ${{ matrix.laravel }} steps: - uses: actions/checkout@v4 - name: Setup PHP uses: shivammathur/setup-php@v2 with: php-version: ${{ matrix.php }} extensions: dom, curl, libxml, mbstring, zip coverage: none - name: Install dependencies run: | composer require "laravel/framework:${{ matrix.laravel }}" \ "orchestra/testbench:${{ matrix.testbench }}" \ --no-interaction --no-update composer update --prefer-dist --no-interaction - name: Run tests run: vendor/bin/pest ``` ### Importancia de `fail-fast: false` Con `fail-fast: false`, aunque una combinación falle, las demás siguen ejecutándose. Así puedes ver en una sola ejecución de CI qué combinaciones concretas fallan. ### Actualización gradual de la matriz Cuando sale una nueva versión de Laravel, añádela a la matriz. Cuando retires una versión antigua, elimínala. ```yaml theme={null} # Cuando salga Laravel 14, se añade matrix: laravel: ["^13.0", "^14.0"] include: - laravel: "^14.0" testbench: "^11.0" - laravel: "^13.0" testbench: "^10.0" ``` ## Ejemplo de composer.json Ejemplo completo de un `composer.json` con soporte a varias versiones. ```json theme={null} { "name": "acme/courier", "description": "A Laravel courier package", "type": "library", "license": "MIT", "require": { "php": "^8.2", "illuminate/support": "^12.0||^13.0" }, "require-dev": { "orchestra/testbench": "^9.0||^10.0", "pestphp/pest": "^3.0", "pestphp/pest-plugin-laravel": "^3.0" }, "autoload": { "psr-4": { "Acme\\Courier\\": "src/" } }, "autoload-dev": { "psr-4": { "Acme\\Courier\\Tests\\": "tests/" } }, "extra": { "laravel": { "providers": [ "Acme\\Courier\\CourierServiceProvider" ] } }, "minimum-stability": "stable", "prefer-stable": true } ``` ## Checklist para adaptarte a nuevas versiones * [ ] Verifica el comportamiento con la versión de desarrollo (`dev-master` / `@dev`). * [ ] Revisa los cambios rompedores en la guía oficial de actualización. * [ ] Implementa la adaptación a la nueva versión en un entorno de tests. * [ ] Añade la nueva versión a la matriz de tests y verifícala en CI. * [ ] Añade la nueva versión al requisito de `illuminate/*` en `composer.json`. * [ ] Ajusta el requisito de PHP si es necesario. * [ ] Actualiza también `orchestra/testbench` en `require-dev` a la versión compatible. * [ ] Publica la nueva versión con un tag para que aparezca en Packagist. * [ ] Actualiza la tabla de compatibilidad del README. * [ ] Declara el fin de soporte en CHANGELOG/README. * [ ] Elimina las restricciones de la versión antigua del `composer.json`. * [ ] Elimina la versión antigua de la matriz de tests. * [ ] Limpia el código condicional específico para la versión antigua. ## Páginas relacionadas Cómo desarrollar paquetes Laravel centrados en los service providers. Cómo escribir pruebas para paquetes con la Expectation API y los datasets de Pest. ## Related topics - [CHANGELOG y gestión de releases de paquetes](/es/advanced/package-changelog.md) - [Uso de la capa de compatibilidad con el SDK oficial](/es/packages/laravel-copilot-sdk/bare-usage.md) - [Nuevo ecosistema de análisis de código de Laravel — surveyor / ranger / roster](/es/blog/laravel-ecosystem-analysis.md) - [Laravel Boost Custom Agent for GitHub Copilot CLI](/es/packages/laravel-boost-copilot-cli.md) - [Eventos del ciclo de vida de sesión](/es/packages/laravel-copilot-sdk/session-lifecycle-event.md)