Gestión de la compatibilidad de versiones de paquetes

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. 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

Actualiza require en composer.json

Añade la nueva versión al rango de dependencias. Si sigues dando soporte a las anteriores, concaténalas con ||.

"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.

"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.

Ejecuta los tests contra la nueva versión

En local o en el entorno CI, ejecuta los tests con la nueva versión de Laravel.

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 a la matriz de tests de GitHub Actions

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.

Publica la versión con soporte a la nueva Laravel

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.

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

"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.

"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.

## 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».

# 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.

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.

{
    "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.

"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	Anuncios de releases mayores y descripción de nuevas funciones.
Guía oficial de actualización	Lista de cambios rompedores.
Log de commits de laravel/framework	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.

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.

# 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.

{
    "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

Antes de la nueva release de Laravel

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.

Reacción inmediata tras la release

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.

Al retirar soporte a versiones antiguas

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

Fundamentos del desarrollo de paquetes

Cómo desarrollar paquetes Laravel centrados en los service providers.

Pruebas avanzadas con Pest

Cómo escribir pruebas para paquetes con la Expectation API y los datasets de Pest.

Última modificación el 20 de julio de 2026

Temas relacionados

CHANGELOG y gestión de releases de paquetes Uso de la capa de compatibilidad con el SDK oficial Nuevo ecosistema de análisis de código de Laravel — surveyor / ranger / roster Laravel Boost Custom Agent for GitHub Copilot CLI Eventos del ciclo de vida de sesión

Service providers diferidos

Pinning y seguridad en GitHub Actions

Desarrollo con IA

Patrones de diseño

Desarrollo de paquetes

Estructura de la aplicación

Novedades de Laravel 13

Profundizando en Eloquent

Extensión de validación

Extensión de autenticación

Seguridad

Pruebas

テスト

Gestión de la compatibilidad de versiones de paquetes

Adaptarse a las nuevas versiones mayores de Laravel

Flujo de la migración

Toma como referencia los paquetes oficiales

Actualización del requisito de PHP

Si quieres usar las nuevas funciones de PHP

Estrategia para retirar el soporte a versiones antiguas

Cuándo retirar el soporte

Declara la política de soporte en el README

El coste de mantener versiones antiguas

Ventajas de reaccionar pronto

Prueba previa con la versión de desarrollo

El primer paso puede ser solo cambiar composer.json

Cómo seguir la información de releases

Ejemplo de configuración de la matriz de tests

Importancia de `fail-fast: false`

Actualización gradual de la matriz

Ejemplo de composer.json

Checklist para adaptarte a nuevas versiones

Páginas relacionadas

Fundamentos del desarrollo de paquetes

Pruebas avanzadas con Pest

​Adaptarse a las nuevas versiones mayores de Laravel

​Flujo de la migración

​Toma como referencia los paquetes oficiales

​Actualización del requisito de PHP

​Si quieres usar las nuevas funciones de PHP

​Estrategia para retirar el soporte a versiones antiguas

​Cuándo retirar el soporte

​Declara la política de soporte en el README

​El coste de mantener versiones antiguas

​Ventajas de reaccionar pronto

​Prueba previa con la versión de desarrollo

​El primer paso puede ser solo cambiar composer.json

​Cómo seguir la información de releases

​Ejemplo de configuración de la matriz de tests

​Importancia de fail-fast: false

​Actualización gradual de la matriz

​Ejemplo de composer.json

​Checklist para adaptarte a nuevas versiones

​Páginas relacionadas

Fundamentos del desarrollo de paquetes

Pruebas avanzadas con Pest

Adaptarse a las nuevas versiones mayores de Laravel

Flujo de la migración

Toma como referencia los paquetes oficiales

Actualización del requisito de PHP

Si quieres usar las nuevas funciones de PHP

Estrategia para retirar el soporte a versiones antiguas

Cuándo retirar el soporte

Declara la política de soporte en el README

El coste de mantener versiones antiguas

Ventajas de reaccionar pronto

Prueba previa con la versión de desarrollo

El primer paso puede ser solo cambiar composer.json

Cómo seguir la información de releases

Ejemplo de configuración de la matriz de tests

Importancia de `fail-fast: false`

Actualización gradual de la matriz

Ejemplo de composer.json

Checklist para adaptarte a nuevas versiones

Páginas relacionadas