Saltar al contenido principal
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

1

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

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

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

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.
LaravelPHP mínimo
Laravel 11PHP 8.2
Laravel 12PHP 8.2
Laravel 13PHP 8.3
Laravel 14PHP 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.
CriterioDescripción
Fin de soporte oficial de LaravelRetira la compatibilidad cuando termina el soporte oficial de esa versión de Laravel.
Uso realCuando los datos de descarga de Packagist muestran que los usuarios de la versión antigua son pocos.
Coste de añadir funcionalidadCuando 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:
FuenteContenido
Watch de GitHubActívalo en el repositorio: «Watch → Custom → Releases» para recibir notificaciones por correo. Registra también los paquetes principales aparte del framework.
Blog oficial de LaravelAnuncios de releases mayores y descripción de nuevas funciones.
Guía oficial de actualizaciónLista de cambios rompedores.
Log de commits de laravel/frameworkPara 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

  • 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

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 13 de julio de 2026

Temas relacionados

CHANGELOG y gestión de releases de paquetesUso de la capa de compatibilidad con el SDK oficialNuevo ecosistema de análisis de código de Laravel — surveyor / ranger / rosterLaravel Boost Custom Agent for GitHub Copilot CLIEventos del ciclo de vida de sesión