Supporting Older Laravel Package Versions with Composer Constraints

A Laravel package maintainer may release a newer package line while still supporting customers who use older Laravel framework versions. Composer constraints limit which dependency versions Composer installs. Maintainers use branches to keep an older line’s code and release tags to publish fixes for it. Constraints, branches, and tags do not prove that the package works with those dependencies. Maintainers need tests for the Laravel and PHP versions the package claims to support.

Here, an “older line” means an earlier series of package versions, such as 1.x, that remains available alongside a newer series and may support older Laravel releases. Package versions and Laravel framework versions have separate version ranges. A clear policy identifies the Laravel and PHP versions each package line supports and the fixes it receives. It also tells users which releases to install.

Write constraints that match tested compatibility

Composer constraints limit which dependency versions Composer can select. For example, a Laravel package that relies on illuminate/support could declare:

{
  "require": {
    "illuminate/support": "^11.0 || ^12.0"
  }
}

The caret constraint ^11.0 accepts compatible releases starting at 11.0 and below 12.0. The || means Composer accepts either the 11.x or 12.x range. This declaration tells Composer what it may install; it does not show that the package works across every release in those ranges. Maintainers should include a Laravel major only when their code and tests support it. Composer documents how version constraints work.

Set the lower bound to the earliest dependency version that includes the features your package uses. If the bound is too low, Composer can install a version without those features. If it is too high, Composer excludes users whose projects use older, compatible dependency releases. Composer recommends testing lower bounds with composer update --prefer-lowest, which tells Composer to select the lowest allowed dependency versions.

Bound future major versions when compatibility is unknown. A constraint such as >=x.y has no upper limit, so Composer can select a later major release that introduces incompatible changes. Once a package release is tagged, maintainers cannot change the constraints in that tag; they need to publish a new release to adjust the range. Composer explains the risk of unbounded version constraints.

Declare PHP requirements alongside Laravel dependencies. The package’s PHP range should match the language features its code uses and the PHP versions its tests cover. Also declare each dependency the package uses directly instead of relying on another package to install it indirectly. Laravel’s package development documentation covers Composer installation and Laravel integration, including package discovery.

Keep the older line on a release path

Maintainers can use a versioned branch, such as 1.x, to keep the older line’s code and dependency limits while developing a newer line elsewhere. When a fix applies to both lines, maintainers can add it to both branches and publish a patch tag for each line. A stable tag gives users a fixed release to install; a branch points to code that can continue to change.

Composer also recognizes version-like branches and branch aliases, which let development branches participate in dependency resolution as dev versions. These features help during development, but they do not replace tested stable releases for users who need a fixed version. See Composer’s documentation on branches, tags, and aliases.

Choose branches based on the work needed to support each Laravel version. One package line can support multiple Laravel major versions when the same code works with each and CI tests every claimed combination. Use separate maintenance branches when older Laravel support needs different dependency limits or code. Each branch adds work to apply fixes, run tests, and publish releases.

Keep the package’s version policy distinct from Laravel’s framework lifecycle. Laravel publishes its own support dates, but those dates do not define how long an independent package must support a Laravel version. The package maintainer needs to state that commitment separately. Laravel’s release notes and support policy provide framework-level dates, not a maintenance promise for third-party packages.

Test the combinations the package claims to support

Run CI tests with the lowest and highest dependency versions allowed by each constraint. A normal composer update tests the latest versions Composer can select. The composer update --prefer-lowest command checks whether the lowest allowed versions work. Include the PHP versions the package claims to support, and test each Laravel major named in the package’s policy.

For Laravel-specific integration, package authors can use Orchestral Testbench to exercise a package in an environment resembling a Laravel application. A support matrix makes the results and commitments easy to compare:

A library’s composer.lock helps maintainers use the same dependency versions in their development work and CI tests. It does not pin dependency versions for people installing the library. Composer explains this distinction in its guidance for libraries and lock files.

Maintain and document the older line

Maintainers keep an older branch secure by continuing to review and update its dependencies and code. State whether maintainers will provide security fixes, ordinary bug fixes, or no further updates for the line. Review dependency alerts for that branch, test proposed updates against its supported combinations, and publish a patched tag when a fix is ready. GitHub’s Dependabot security updates can open a pull request to update a dependency when an alert has an available patch. Maintainers still need to review and test each change. Automation does not guarantee that a compatible fix exists for an older line.

Publish the support policy where users can find it, such as in the README. State the package lines, Laravel and PHP ranges, maintenance status, and recommended upgrade path. Release notes should identify which line received each fix. GitHub releases associate a release with a tag and let maintainers select the branch containing its target, which helps users find releases across maintained lines; see managing repository releases.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com