Evaluating Laravel Package Updates Before Merging

When you update a Laravel package, Composer chooses package versions that meet your project’s requirements and records them in composer.lock. The lock file lets other developers and deployment environments install the same set of package versions. Before merging an update, check what the package changed, whether its supported Laravel and PHP versions match your project, and whether tests cover the behavior your code relies on.

Semantic Versioning, usually called SemVer, labels releases as major, minor, or patch versions. These labels describe the changes a maintainer intends to make, but they do not replace a review. A patch can still affect a critical workflow, and passing tests confirm only the conditions they exercised. A thorough review checks the release notes, the code diff (a comparison of the old and new code), Composer’s proposed package changes, and focused tests.

Read the changelog, release notes, and diff

First, read the notes for the exact package version you plan to install. A changelog records package changes over time, often in a file such as CHANGELOG.md; release notes summarize a particular release. Check that the notes cover the version you plan to install. Look for fixes and new features, along with deprecations or breaking changes. A chronological changelog helps you connect a change to the release that introduced it.

Use the release notes to find the relevant code, then review that code yourself. GitHub’s generated release notes can list changes and contributors and link to the full diff between releases. Open that link and review the files it lists. For a Laravel package, check changes to service providers, default settings, routes, middleware, database migrations, events, and public methods. Your code often connects to package behavior through these parts.

Compare the proposed release with the version listed in composer.lock. If the notes are sparse or generated automatically, the diff becomes especially useful. For example, if a brief “fix queue handling” note accompanies changes to job serialization or default settings in the diff, review those changes too. Confirm what the code changes, then identify which project behavior depends on it.

Check Composer’s proposed versions and compatibility

Check the package’s Composer requirements and the changes Composer proposes for your project. The package’s composer.json lists its requirements, including supported PHP and Laravel component versions. Check that your project meets them. Also check the version constraint in your project’s main composer.json. It sets the versions Composer is allowed to choose.

Composer constraints use operators such as ^ and ~ to define allowed version ranges. For example, ^1.2.3 allows compatible releases below 2.0.0, while ~1.2.3 allows releases below 1.3.0. Composer documents how version constraints work. A broad wildcard can allow versions beyond the range your project intends to support. A constraint that is too narrow can prevent a compatible update. The constraint defines which versions Composer can choose, and the lock file records the versions Composer selected.

Preview the update before changing the lock file:

composer update vendor/package --with-dependencies --dry-run

Replace vendor/package with the package’s Composer name. The dry run lists the package versions Composer would change while leaving the lock file untouched. Check whether Composer plans to upgrade or downgrade related packages, and whether the proposed versions meet your project’s constraints. After you approve the selected versions, run the update and commit the composer.lock change along with the package update. Committing the lock file keeps package versions consistent across local, CI, and deployment installs.

Evaluate the package and application tests

Check what the package tests cover, then run them with the command and environment its maintainers document. Look for tests of the changed code, and check the package’s continuous integration settings to see which PHP and Laravel versions it tests. Passing tests on one supported version does not confirm compatibility with every version your project uses.

Run your project’s tests as well. Test the workflows that use the package or depend on the changed behavior. A notification package, for instance, warrants checks of the notification paths your code relies on; a billing integration calls for tests around billing events and subscription changes. For external services, use a sandbox when one is available. If no sandbox is available, use mocks or recorded responses so tests do not rely on a live service.

Passing tests show that the code met the conditions those tests checked. They do not prove that every behavior is correct. Laravel upgrade guidance recommends protecting important user workflows rather than treating total test coverage as the goal. Compare the tests with the diff. If the update changes behavior your tests do not cover, add a focused regression test.

Decide what the version change requires

SemVer describes a patch release as a backward-compatible bug fix, a minor release as backward-compatible functionality, and a major release as an incompatible API change. Let the version number guide how closely you review the update, then check that the notes and diff match its label. SemVer’s rules also state that 0.y.z versions are for initial development, so their public APIs should not be treated as stable.

A package’s version label tells you what compatibility the maintainer intends. It does not guarantee compatibility with the way your project uses the package. Even for a patch release, review any integration point that your code customizes if the update changes it.

Keep updates moving without skipping review

Keep each package update small enough that you can identify what caused a problem. Update one package at a time so reviewers can connect a failure to a specific change. Group packages only when they need to be updated together. Include the lock file in the same change, preview the update with Composer, and have CI run the project tests that cover the package. This makes CI run the same checks for each update instead of relying on a reviewer to remember every command.

Protect the workflows with the highest impact first, such as login, billing, queues, notifications, reports, and external API calls. Before each dependency update, focus tests on the behavior that matters to your project; per-line tests are unnecessary. Before deployment, check that logs, error tracking, and queue-failure visibility will help you find problems automated tests missed. Laravel upgrade planning also recommends an explicit rollback strategy for live products.

If an update requires a wider Laravel or PHP upgrade, handle that separately from unrelated package changes. Before starting the larger upgrade, write down the current and target versions. Note which workflows it affects and how you would roll it back. Tools that make routine code edits can save time, but maintainers still need to check that the changed code follows the package’s documented behavior.

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