Laravel Db Ready Laravel Package

Getting Started

v4.0.0 is a compatibility-breaking major, not a feature release. Before writing any application code, establish your runtime window:

Steps, in order:

1. Read the package's own composer.json first — the release notes say "drop PHP 7.3", which sets a floor of 7.4, but the actual constraint may be ^7.4|^8.0 or ^8.0. That distinction decides whether your 7.4 CI runners can install it at all. Then read UPGRADE.md / the diff between v3.x and v4.0.0 tags — the notes list only platform changes, and a major bump very often ships silent API changes.
2. Check your lockfile and CI matrix before touching the app:

   php -v
   composer why-not vendor/package ^4.0
   

   composer why-not names the exact constraint blocking you (usually laravel/framework or a transitive package pinning the old major).
3. First use case: install on a scratch branch of your smallest Laravel 9 app, publish config, and hit the package's primary entry point once from tinker or a throwaway feature test. Resolve via the container rather than a facade first — that surfaces binding/alias changes immediately:

   composer require vendor/package:^4.0
   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   php artisan tinker
   >>> app(\Vendor\Package\Contracts\Client::class);
   

4. Only after that does it belong on a real branch. Treat the upgrade as a migration task, not a composer update.

Implementation Patterns

Pin the major, float the minor. Declare "vendor/package": "^4.0" in composer.json — never * or a commit hash. This release is precisely why: the v3→v4 boundary is invisible in composer update until it explodes on an unsupported Laravel version.

One upgrade branch per app, one compatibility branch per package. If you maintain several apps on mixed Laravel versions, keep the Laravel 6/7 apps on a 3.x maintenance branch and upgrade the rest. Do not attempt to shim Laravel 6 back into v4 with illuminate/support aliasing — the dropped majors are dropped because of real API removals in the framework, and a shim will fail in production rather than in CI.

Prefer dependency injection over facades in new code. This is the single cheapest insurance against a future major. If v4 renamed or re-scoped the facade, constructor injection against the contract keeps your call sites compiling:

public function __construct(private \Vendor\Package\Contracts\Client $client) {}

Reserve the facade (Package::doThing()) for Blade views and one-off artisan commands where DI is awkward.

Isolate the package behind one adapter class. Wrap first-party calls in a thin application-level service (e.g. App\Support\PackageGateway). When v5 lands you change one file, not forty controllers. This also gives you a single place to add retry/timeout/caching policy that the package itself may not offer.

Configure through config/ and .env, never inline. Publish the config file, commit it, and reference config('package.key'). Cache-bust awareness: after editing .env in a cached-config environment, run php artisan config:clear.

Test the integration surface, not the package. You should not unit-test the vendor's internals. You should have one feature test per integration point (a fake/Http::fake() if the package talks over HTTP), so a future composer bump fails loudly in CI.

Make the upgrade a single CI job. Add a matrix entry for the target combo (PHP 8.1 + Laravel 9 + package ^4.0) so the constraint floor and ceiling are both exercised.

Gotchas and Tips

• "Added Laravel 9" does not mean "only Laravel 9." v4 supports Laravel 8 and 9. Don't couple your own composer.json to Laravel 9 solely because of this package.
• platform config lies to you. A config.platform.php = "7.3" in composer.json (common in Dockerized projects) will make Composer resolve v3.x silently while your production image runs 8.x. Audit it as part of the upgrade:

  composer config platform.php
  

• Silent major-version API changes are the real risk here. The release notes are entirely about support windows. Before merging, diff the public surface: changed method signatures, removed/renamed config keys, altered default values, and any facade accessor rename. git diff v3.x..v4.0.0 -- src/ config/ is faster than waiting for a runtime BadMethodCallException.
• Config drift is the classic post-upgrade failure. Published config files are not updated by vendor:publish, so new keys added in v4 arrive as null. After upgrading, diff your published config/package.php against the package's version and merge new keys manually.
• Cached artifacts mask the upgrade. Run php artisan optimize:clear (config, route, view, event caches) after the bump; stale cached service providers are a frequent source of "it works locally, not in staging."
• Debugging tip: when a service fails to resolve, dump the container's binding rather than guessing:

  dd(app()->getBindings()[ \Vendor\Package\Contracts\Client::class ] ?? 'unbound');
  

  Auto-discovery is disabled in some environments (composer install --no-scripts on deploy hosts) — confirm the provider appears in bootstrap/cache/packages.php.
• Extension points to lean on: the published config file, the contract/interface bindings (rebind in a service provider to swap implementations), and any events the package dispatches. Prefer these over subclassing vendor classes — subclasses are the first thing to break on a major bump.
• Document the floor in your README. Future-you needs to know the project requires PHP ≥ 7.4 and Laravel ≥ 8 because of this package, otherwise someone will try to "modernize" downward and hit an unresolvable constraint.

Bottom line: adopt v4.0.0 for Laravel 9 projects and for Laravel 8 projects already on PHP 7.4+; defer it for any app still on Laravel 6/7 or PHP 7.3, which must stay on the 3.x line until those platforms are retired.