Package Version Compatibility Management

Laravel releases a new major version every year, typically in February or March. For package authors, completing support for new versions quickly is a meaningful contribution to the ecosystem and a strong signal of package quality.

This page is a companion to Laravel Package Development. It assumes familiarity with package basics such as service providers and composer.json configuration.

Responding to a Laravel major version upgrade

Step-by-step process

Update the require constraint in composer.json

Add the new version to your dependency range. Use || to support multiple versions simultaneously.

"require": {
    "php": "^8.2",
    "illuminate/support": "^12.0||^13.0"
}

When you are ready to drop support for an older version, remove the old constraint.

"require": {
    "php": "^8.3",
    "illuminate/support": "^13.0||^14.0"
}

Depending on illuminate/support rather than illuminate/framework keeps the dependency tree small by pulling in only the Laravel components you actually need.

Run your tests against the new version

Update dependencies and run your test suite locally or in CI.

composer update
vendor/bin/pest

If tests pass, basic compatibility is confirmed. If not, check the official upgrade guide for removed or changed APIs and fix your package accordingly.

Add the new version to your GitHub Actions test matrix

Add the new Laravel version to your CI matrix so compatibility is verified continuously. See Test matrix configuration example below.

Release the update

Tag a new release containing the composer.json changes. Users will be able to install the package on the new Laravel version with a simple composer update.

Learn from official packages

When in doubt, check how official Laravel packages handle version constraints.

These packages are maintained by the Laravel team and are updated first. Their illuminate/* constraint syntax is the most reliable reference.

Updating PHP version requirements

A Laravel major version upgrade sometimes raises the minimum PHP requirement as well. Update the PHP constraint in your composer.json accordingly.

Laravel	Minimum PHP
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"
}

Raising the minimum PHP version to use new language features

If you want to use features introduced in PHP 8.3 or later (typed constants, new random functions, etc.), you need to raise the minimum PHP requirement. Because raising the minimum PHP version is a breaking change under semantic versioning, it is best done alongside a package major version bump.

"require": {
    "php": "^8.3",
    "illuminate/support": "^12.0||^13.0"
}

Raising the PHP minimum requirement prevents users on older PHP versions from updating the package. Announce the change clearly in your README and CHANGELOG well in advance.

Strategy for ending support for old versions

Maintaining old versions indefinitely increases maintenance costs over time. Defining a clear support policy and regularly dropping old versions leads to a healthier package.

When to drop support

A common approach is to align with Laravel’s support lifecycle. Laravel provides bug fix support for 18 months and security fix support for 2 years per release. Adopting the same policy gives users clear expectations.

Criterion	Description
Laravel’s official end of life	Drop support when Laravel itself stops receiving bug fixes
Usage statistics	Drop support when downloads for the old version drop significantly on Packagist
Feature development friction	Drop support when maintaining old compatibility makes adding new features significantly harder

Document your support policy in README

Include a compatibility table in your README.md so users know which versions are supported.

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

The cost of maintaining old versions

Continuing to support old versions introduces the following costs.

Duplicate bug fixes — the same bug must be fixed across multiple branches
Branching code complexity — version-specific implementation differences accumulate in conditional logic
Bloated test matrices — CI run times grow with every additional version combination
Backporting security patches — applying fixes safely to old branches requires additional care

Encouraging users to move to the latest Laravel version benefits the entire ecosystem and reduces the maintenance burden on package authors.

The benefits of acting early

When your package supports a new Laravel version on release day, users can upgrade immediately. This is a strong trust signal for the package.

Validate against the development version

Laravel does not publish beta or RC releases. Instead, you can install the next version in development using dev-master or the @dev constraint. Testing before the final release allows for zero-day compatibility.

# Install the next version using dev-master
composer require laravel/framework:dev-master --no-update
composer update
vendor/bin/pest

You can also use the @dev constraint.

composer require laravel/framework:^14.0@dev --no-update
composer update
vendor/bin/pest

Set minimum-stability to dev to resolve development version dependencies.

{
    "minimum-stability": "dev",
    "prefer-stable": true
}

With prefer-stable: true, Composer prefers stable releases when they are available. You can test against development versions without risking non-stable dependencies in production.

The first step is just a composer.json change

You do not need a fully verified implementation before releasing. Simply updating the version constraint in composer.json lets users install the package on the new Laravel version.

"illuminate/support": "^12.0||^13.0"

Small issues can be addressed in patch releases after the initial update. Prioritize making the package installable over delivering a perfect implementation.

Where to track release information

Source	Content
GitHub Watch	Enable “Watch → Custom → Releases” on the repository to receive email notifications. Set this up for framework and other key packages
Laravel official blog	Major release announcements and feature overviews
Laravel upgrade guide	Breaking changes summary
laravel/framework commit log	Track changes to the next version early by following commits directly

Test matrix configuration example

The following GitHub Actions workflow runs your test suite against multiple Laravel and PHP version combinations.

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

Why fail-fast: false matters

Setting fail-fast: false allows all matrix combinations to run even if one fails. You get a complete picture of which version combinations have problems in a single CI run.

Updating the matrix over time

Add new Laravel versions to the matrix when they are released. Remove old versions when you drop support.

# Add Laravel 14 when it is released
matrix:
  laravel: ["^13.0", "^14.0"]
  include:
    - laravel: "^14.0"
      testbench: "^11.0"
    - laravel: "^13.0"
      testbench: "^10.0"

Sample composer.json

A complete example of a composer.json configured for multi-version support.

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

Version upgrade checklist

Before a new Laravel release

Test against the development version (dev-master or @dev)
Review the official upgrade guide for breaking changes
Implement any required fixes in a development branch
Add the new version to your test matrix and verify CI passes

Initial response after release

Add the new version to the illuminate/* constraint in composer.json
Update the PHP requirement if needed
Update orchestra/testbench in require-dev to match
Tag a new release and verify it appears on Packagist
Update the version compatibility table in README

Dropping support for an old version

Announce end of support in the CHANGELOG and README
Remove the old constraint from composer.json
Remove the old version from the test matrix
Clean up any version-specific conditional code

Laravel Package Development

Learn the fundamentals of Laravel package development, including service providers and publishing resources.

Advanced Testing with Pest

Write expressive package tests using Pest’s Expectation API, datasets, and fakes.

Last modified on April 14, 2026

The InteractsWithData trait

Package CHANGELOG and Release Management

Documentation Index

​Responding to a Laravel major version upgrade

​Step-by-step process

​Learn from official packages

​Updating PHP version requirements

​Raising the minimum PHP version to use new language features

​Strategy for ending support for old versions

​When to drop support

​Document your support policy in README

​The cost of maintaining old versions

​The benefits of acting early

​Validate against the development version

​The first step is just a composer.json change

​Where to track release information

​Test matrix configuration example

​Why fail-fast: false matters

​Updating the matrix over time

​Sample composer.json

​Version upgrade checklist

​Related pages

Laravel Package Development

Advanced Testing with Pest

Responding to a Laravel major version upgrade

Step-by-step process

Learn from official packages

Updating PHP version requirements

Raising the minimum PHP version to use new language features

Strategy for ending support for old versions

When to drop support

Document your support policy in README

The cost of maintaining old versions

The benefits of acting early

Validate against the development version

The first step is just a composer.json change

Where to track release information

Test matrix configuration example

Why fail-fast: false matters

Updating the matrix over time

Sample composer.json

Version upgrade checklist

Related pages