Laravel Eloquent Uuid Laravel Package

Getting Started

• Confirm your runtime before installing ^1.5: the package now supports PHP 8.1 and Laravel 9, while PHP 7.3 and Laravel 6/7 are no longer supported. Practical floor for Laravel 9 apps is PHP 8.0.2+ (Laravel 9's own minimum), so target PHP 8.0.2–8.1.
• If you are still on Laravel 6/7 or PHP 7.3, stay on the previous 1.4.x line and plan the framework/runtime upgrade before taking 1.5.
• Install/upgrade with:

  composer require vendor/package:^1.5 --with-dependencies
  composer why-not vendor/package 1.5.0
  

  Use why-not first if resolution fails — it identifies which dependency is pinning PHP or Laravel below the new floor.
• Look first at the package's service provider registration (normally auto-discovered), any publishable config, and any migrations. Then exercise one representative read/write path in php artisan tinker or a single feature test before wiring it through the app.
• First use case: put the package behind one small application service/adapter class and call that from a controller or job. This gives you an isolation point for future major-version bumps and for Laravel 9 integration changes.

Implementation Patterns

• Upgrade-first workflow: create a branch, bump the constraint to ^1.5, run your test suite on a matrix of PHP 8.0/8.1 and Laravel 8/9, then merge. Do not combine this with unrelated framework upgrades.
• CI matrix: test PHP 8.0 and 8.1 against Laravel 8 and 9, with both lowest and stable dependency sets (--prefer-lowest and default). This catches accidental reliance on transitive versions.
• Adapter/service wrapper: inject the package's client/manager/repository into a thin app-level class. Controllers, jobs, and commands depend on your wrapper rather than package classes directly; this keeps Laravel 9 upgrades and future package majors localized.
• Laravel 9 integration checks: if the package touches mail, filesystem, HTTP client, or queue APIs, verify those paths specifically — Laravel 9 replaced several underlying components (Symfony Mailer, Flysystem 3, HTTP client behavior). Test the package's integration points, not just its isolated unit behavior.
• Feature tests over internals: assert observable behavior (records written, jobs dispatched, responses returned) instead of package internals. Use RefreshDatabase for DB-backed features, and Queue::fake()/Bus::fake() for dispatch assertions.
• Downstream packages: if you publish a package that depends on this one, widen the constraint to ^1.4|^1.5 during the transition so consumers on Laravel 7 are not forced forward.

Gotchas and Tips

• This is effectively a breaking release for older stacks. Dropping PHP 7.3 and Laravel 6/7 will fail dependency resolution, not just emit warnings. Audit composer.lock, Docker base images, and CI runner PHP versions before upgrading.
• Watch the PHP floor mismatch. Laravel 9 requires PHP 8.0.2, but the release note only says PHP 8.1 support was added. Set config.platform.php in composer.json to your real deployment version (e.g. 8.0.2 or 8.1.x) so local resolution matches production.
• Debug resolution failures with composer why-not vendor/package 1.5.0. Common blockers are another package pinning laravel/framework to ^7.0 or a transitive dependency requiring php: ^7.3.
• Clear caches after upgrading: php artisan config:clear, php artisan cache:clear, and php artisan optimize:clear. Stale cached config or compiled service manifests produce confusing class-not-found or stale-binding errors that look like package bugs.
• Diff published assets before republishing. If the package ships config or migrations, compare new defaults against your published copies; only use --force after reviewing the diff. Run php artisan migrate in staging first.
• Prefer container bindings/your own service provider for overrides rather than editing vendor files. Re-verify those bindings after the upgrade, since constructor signatures or interfaces may have shifted between supported framework versions.
• Enable deprecation logging on PHP 8.1 in staging. PHP 8.1 deprecations (implicit nullable parameters, return-type warnings) often surface in less-travelled package code paths; catch them before production traffic does.
• Re-run the package's own tests if it is a dev dependency against your Laravel 8/9 combination; passing upstream CI does not guarantee compatibility with your app's service provider and configuration mix.