Laravel Health Check Laravel Package

Getting Started

• Check your Laravel version first. v4.0.0 supports Illuminate 11 and 12 and drops Illuminate 10. If your app is still on Laravel 10, stay on the 3.x line until you upgrade the framework.
• Install/update with an explicit constraint so Composer resolves the correct major:

  composer require vendor/package:^4.0
  

  Replace vendor/package with the actual package name. Laravel package auto-discovery should register the service provider automatically.
• Publish and review config if the package exposes configuration:

  php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
  

  Read the generated config/*.php and the package README for required environment variables.
• First use case: upgrade path. On Laravel 11, update the package to v4 to gain Laravel 12 readiness. On Laravel 12, v4 is the minimum supported release. Run the app’s test suite immediately after upgrading, then clear caches:

  php artisan config:clear && php artisan cache:clear
  

Implementation Patterns

• Upgrade workflow: create a branch, bump the package to ^4.0, run composer update vendor/package --with-dependencies, then run php artisan test. Keep the framework and package upgrade in the same PR when moving from Laravel 10 to 11/12.
• Service container usage: prefer constructor injection or the package’s facade where provided. Resolve bindings from the container rather than instantiating package classes manually.
• Config-driven behavior: keep package options in config/*.php and environment variables, not hard-coded values. This makes it easy to run different settings per environment.
• Publishable assets/migrations: if the package ships migrations or frontend assets, publish them only once and commit the published files. Re-publishing can overwrite local customizations.
• Testing integration: use Laravel’s testing helpers (RefreshDatabase, Event::fake(), Queue::fake()) around package calls. If the package provides test helpers, use them rather than mocking internals.
• Day-to-day usage: wrap package calls in your own service or action class when the API is used in multiple places. This isolates future package upgrades and keeps controllers/jobs clean.
• Laravel 12 readiness: treat v4 as the compatibility baseline. Pin ^4.0 in composer.json and avoid mixing v3 and v4 across environments.

Gotchas and Tips

• This is a breaking release for Laravel 10 users. v4.0.0 removes Illuminate 10 support. Composer will refuse to install it on a Laravel 10 app. Use composer why-not vendor/package 4.0 to confirm the blocker before debugging further.
• No new package features are listed. The changelog only covers Illuminate version support. Do not assume API changes beyond the framework constraint, but still review the package’s full 4.0.0 diff/README before upgrading production.
• Laravel 12 may raise platform requirements. Check composer.json for PHP and extension requirements. Laravel 12 typically expects a newer PHP baseline; ensure CI and production match.
• Auto-discovery can be disabled. If your app uses dont-discover, register the service provider manually in bootstrap/providers.php (Laravel 11+) or config/app.php.
• Config and route caching: after upgrading, run php artisan config:clear, php artisan route:clear, and php artisan optimize:clear. Stale caches are a common cause of “package not working” after a major upgrade.
• Migrations and data: if the package ships migrations, back up the database and test the upgrade in staging first. Major-version upgrades can include schema changes even when the changelog is short.
• Debugging checklist: composer show vendor/package, php artisan about, storage/logs/laravel.log, and the package’s GitHub issues for Laravel 12 compatibility reports.
• Extension points: use the package’s documented bindings, drivers, macros, or events rather than extending internals. Internal classes are more likely to change across major versions.
• Pin versions in CI: use composer install with a committed composer.lock so all environments resolve the same Laravel/package combination.