Building a Laravel Package Upgrade Checklist

When you maintain a Laravel package, an upgrade checklist helps you verify that a new release supports the Laravel and PHP versions you claim to support, preserves the package’s public behavior, and installs cleanly for consumers. A compatibility constraint is the version range you declare in composer.json; it tells Composer which framework and PHP versions can use your package.

Use changelogs, dependency resolution, and tests as evidence for your release decision. Publish only when the package’s declared support matches the combinations you checked.

Set the support range before changing code

Decide which Laravel and PHP versions the next package release will support. Record those versions before editing dependencies so the release’s goal stays clear. If you drop a previously supported version, treat that as a compatibility change and explain it in the release notes.

Check your package’s composer.json requirements against that decision. Some packages depend on laravel/framework; others depend on individual illuminate/* components. Review each requirement your package uses, along with the PHP requirement and any third-party packages.

A package’s compatibility range is a promise to its consumers. A Packagist listing, for example, publishes PHP and Laravel requirements that users can inspect before installing a package. Keep your own constraints at least as narrow as the versions you have tested. If you have not verified a combination, do not imply support for it.

Read changelogs for the framework and dependencies

Read the Laravel release notes or upgrade guide for the target framework version, then review the changelogs for dependencies your package uses. Also check your package’s own changelog so you can identify the changes consumers must account for.

For each relevant change, check how it affects your package. Look for renamed or removed methods, changed defaults, changes to middleware or authentication behavior, database or migration changes, and dependency requirements that rule out versions in your declared range. Use Laravel’s upgrade guidance to find code paths your package relies on and inspect them. Then test your package, since the guidance does not replace package tests. The Laravel upgrade guidance also highlights the need to account for deprecated functionality during framework upgrades.

Use semantic versioning to decide how to describe changes in your own release. A major version marks an incompatible API change. A minor version adds backward-compatible functionality, while a patch version fixes bugs without breaking compatibility. The semantic versioning overview summarizes those categories. For a package, consider the public surface consumers use. That includes PHP classes and method signatures, plus published configuration. Routes, commands, events, and migration behavior are part of it too.

Set Composer constraints to match tested support

Composer constraints define which dependency versions Composer may select. A caret constraint such as ^1.2 allows compatible releases below the next major version, while the consumer’s composer.lock records the specific versions Composer resolved for that project. Your package declares the allowed version range. Each project that uses it records the specific dependency versions Composer selected.

Avoid narrowing a package’s runtime constraint merely to freeze the version used during development. Instead, declare the Laravel and dependency version range your code supports, then test the range in continuous integration. Pin a dependency only when a known incompatibility requires it, and document the reason and the condition for widening the constraint again.

Before changing a constraint, use Composer to find which dependency blocks the target version. The official Composer command reference documents useful checks, including composer outdated, composer why-not, composer audit, and composer check-platform-reqs. For example, run composer why-not laravel/framework TARGET_VERSION to identify requirements that prevent Composer from installing the target framework version. Run the audit and platform checks as part of the same review so security advisories and PHP requirement mismatches do not go unnoticed.

Test every supported Laravel and PHP combination

Run the package’s tests against the Laravel and PHP combinations in its declared support range. A CI matrix runs the same checks against several combinations, making coverage repeatable and helping catch mismatches between the package’s Composer constraints and its behavior.

Laravel package maintainers commonly use Orchestra Testbench, a testing harness that boots Laravel components for package tests. Use Testbench to test the parts of your package that depend on Laravel, such as service-provider registration, configuration, routes, commands, middleware, events, or database migrations. Include unit tests for isolated package logic and integration tests for behavior that depends on Laravel or a database.

Test the oldest combination you claim to support and each newer combination you plan to add. When you change dependency constraints, have CI resolve dependencies separately for each matrix entry. Do not rely on one local composer.lock for every combination. Laravel CI examples show how a pipeline can install Composer dependencies and run tests and static analysis; GitHub Actions testing guidance provides one example of that pattern.

Check behavior that tests might miss

Review the code paths affected by the framework or dependency changes, then add tests for any behavior your existing suite does not cover. For example, a package that registers middleware should verify that the expected middleware runs; a package that publishes migrations should verify that the migrations work against the database behavior it supports.

Run static analysis if your package already uses it, and compare the results before and after the upgrade. Static analysis tools inspect code for problems such as type mismatches that tests might not exercise. If an upgrade changes code that builds or runs database queries, review queries that affect performance. Passing tests do not measure every production workload.

Run composer audit in CI or during release review to check for security issues. Composer reports known security advisories that affect installed dependencies, as described in its command documentation. Resolve or document any finding before publishing so consumers can distinguish a package issue from an unrelated dependency advisory.

Use the same release gate each time

Before publishing, confirm each item below:

• The target Laravel and PHP support range is written down and matches composer.json.
• You reviewed the relevant framework, dependency, and package changelogs for breaking changes and deprecations.
• Composer resolves the intended versions, and you understand any blocker reported by why-not.
• CI passes for the Laravel and PHP combinations the package claims to support.
• Tests cover the package behavior affected by the upgrade, and security and platform checks have run.
• The changelog describes consumer-visible changes, including dropped support or required code changes.

After the checks pass, publish a release with a version number that communicates the compatibility impact. Update the package documentation and installation guidance when consumers need to change configuration, code, or supported framework versions.

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