Laravel Perpage Resolver Laravel Package

Getting Started

The 2.0.0 notes are strictly a compatibility announcement — they tell you whether you can install it, not what it does. Treat the upgrade as a dependency-and-environment task before it is a code task.

1. Check your runtime first. 2.x requires PHP 8.0 exactly (8.0.*, not >=8.0) and Laravel ^8 or ^9. If you are on PHP 8.1+ or Laravel 10+, this release is not installable for you — see Gotchas.
2. Read the diff, not the release notes. The notes only enumerate the constraint changes. The breaking API changes in 2.0.0 are undocumented here, so diff the src/ tree between the 1.* tag you run and 2.0.0, and check the repo's UPGRADE.md/CHANGELOG.md if present.
3. Pin before you probe. Install 2.0.0 on a throwaway branch, run composer why-not if resolution fails, and let your existing test suite tell you what broke.
4. First real use case: take one existing 1.x integration — a controller or job that calls the package — and get it green under 2.0.0. That single vertical slice surfaces 90% of the BC breaks (renamed methods, changed config keys, altered service-provider bindings) faster than reading the diff top-to-bottom.

Where to look first in the codebase: the service provider (what it binds and publishes), the config file (keys are the most common silent BC break), and any migration/table the package owns.

Implementation Patterns

Isolate the package behind your own boundary. Because 2.0.0 is a hard BC break with no published migration guide, wrap the package's public surface in a thin application-level class or interface. When 3.x lands, or when you need to fork it for a newer Laravel, you change one class instead of grepping call sites. This is the single highest-value pattern for a package with this maintenance posture.

Constraint pinning in composer.json. Do not use ^2.0 loosely in a project you plan to keep on Laravel 8/9. Pin "vendor/package": "2.0.*" and commit composer.lock. The notes say the illuminate/database bump was for a security reason, which implies the maintainer ships narrow, security-driven patches — you want those, but you do not want surprise minors.

Config-driven setup. In a Laravel package upgrade the usual break points are: published config file keys, service-provider aliases, facade accessors, and default connection/table names. After upgrading, php artisan vendor:publish --force into a scratch directory and diff the new config against your published copy rather than overwriting it.

Composer-level compatibility check before code changes. composer update vendor/package --with-all-dependencies --dry-run is your fastest signal. If it reports a conflict on illuminate/database, the package's own constraints are inconsistent (see Gotchas) and you should stop and evaluate rather than force it with --ignore-platform-reqs.

Test against the constraint boundary, not your local machine. Your local PHP may be 8.2 while CI needs 8.0. Add a matrix entry for php: 8.0 and laravel: 8.*, 9.* so the package's supported envelope is actually exercised. Anything you rely on that only works because your environment is newer is a latent CI failure.

Upgrade in one PR, with the lock file and the code change together. Splitting "bump composer constraint" from "fix broken calls" produces a red main branch between the two commits and makes git bisect useless when something regresses.

Gotchas and Tips

• PHP 8.0 is end-of-life (security support ended November 2023), and Laravel 8/9 are likewise past their security-support windows. A package that pins both is telling you its maintenance horizon has passed. That is not automatically a reason to avoid it, but it is a reason to encapsulate it and to budget for a fork or replacement. Factor this into any new adoption decision, not just upgrades.
• The illuminate/database ^8 + Laravel ^9 combination looks internally inconsistent. Laravel 9 ships illuminate/database ^9; a hard ^8 requirement cannot be satisfied alongside it unless the package uses an || constraint, a separate branch, or relies on replace/alias behaviour. Verify with composer why-not illuminate/database 9.* before assuming 2.0.0 actually installs on Laravel 9. This is exactly the kind of thing release notes get wrong.
• "Breaks backwards compatibility" with no detail is the whole risk. Do not infer a migration path from the version number alone. Grep your codebase for the package's namespace and facades to enumerate every touch point before you touch composer.json.
• Silent config drift. If 2.0.0 added or renamed a config key, a stale published config usually won't error — it will fall back to a package default and behave subtly differently. After upgrading, compare config/your-package.php against the vendor copy.
• Debugging dependency hell: composer why vendor/package, composer why-not vendor/package 2.0.0, and composer show --tree will explain a failed resolution in seconds. --ignore-platform-reqs hides PHP/Laravel mismatches and converts an install-time error into a runtime one — avoid it.
• Extension points that survive a major bump: Laravel packages almost always let you rebind the service provider's registrations, override the facade accessor, or swap a driver via config. If 2.0.0 broke a method you call directly, check whether there is a binding you can override in a service provider instead of patching vendor code.
• Forking is a legitimate option here. With illuminate/database pinned at ^8 for a security fix and no support for Laravel 10+, a maintained fork that widens the constraints is often cheaper than staying pinned — especially if the package is load-bearing rather than peripheral.