Undraw Laravel Package

Getting Started

• Treat 4.2.0 as a platform-compatibility release: it adds Laravel 12 and PHP 8.4 support, and removes Laravel 10 and PHP 8.1. Confirm your app meets the new floor before upgrading.
• Check composer.json first: require php >=8.2 and laravel/framework ^11.0|^12.0 unless the package’s own constraints say otherwise. The release notes explicitly call out Laravel 12 and PHP 8.4, so verify Laravel 11 and PHP 8.2/8.3 are still allowed by the package constraint.
• Install or upgrade with composer require vendor/package:^4.2. For an existing app, update the constraint, run composer update vendor/package --with-dependencies, then run the full test suite before deploying.
• Look first at the package README’s installation section, config/<package>.php, the service provider, and the primary facade or service class. If the package publishes config, publish it with php artisan vendor:publish --tag=<package>-config and review the defaults.
• First use case: resolve the package service from the container in a feature test or php artisan tinker, make one read-only call, and verify configuration, credentials, and logging before wiring it into a real workflow.

Implementation Patterns

• Prefer constructor injection over app() or facades in application code. It keeps tests fast and makes dependencies explicit. Use the facade only in controllers, commands, or Blade where injection is awkward.
• Keep package configuration in config/<package>.php and environment-specific values in .env. Avoid reading env() directly outside config files, especially after php artisan config:cache.
• Wrap package calls that write to the database or external systems in transactions or idempotent jobs. For long-running work, dispatch a queued job and restart workers after deployment.
• Use package events/listeners to decouple side effects. If the package exposes events, listen and queue handlers rather than putting extra logic directly after the package call.
• Build a small integration test around your main use case. Use RefreshDatabase, fake external HTTP calls, and assert both the package result and your application-side side effects.
• Run CI against PHP 8.3/8.4 and Laravel 11/12. Dropping Laravel 10 and PHP 8.1 means your matrix should no longer advertise those combinations for 4.2.x.
• If you support multiple tenants or environments, bind tenant-specific package config in a service provider rather than mutating global config at runtime.
• For Laravel 12 applications, verify package auto-discovery and middleware registration in bootstrap/app.php. First-party and community packages that support Laravel 12 should not require manual provider edits unless documented.

Gotchas and Tips

• The Laravel 10 and PHP 8.1 removals are breaking for older applications. If you are still on either, stay on the latest 4.1.x release and pin the constraint; do not force 4.2 into an unsupported platform.
• Composer may update transitive dependencies when you bump the package. Review composer.lock, run the full suite, and test on a staging environment before production.
• PHP 8.4 introduces deprecations around implicit nullable parameters and other signatures. Run tests with E_ALL and deprecation reporting enabled to catch package or application warnings early.
• Clear cached config after changing .env or published package config: php artisan config:clear and, in production, php artisan config:cache.
• If the package registers a deferred service provider, do not assume its bindings are available before the provider loads. Use explicit bindings or resolve the service at the point of use.
• For Octane or long-running workers, check whether the package stores request state in singletons. Reset or flush package state in Octane listeners if needed, and always run php artisan queue:restart after deployment.
• Use the package’s debug flag, Laravel Telescope, and application logs to diagnose integration issues. Check php artisan about for environment, cache, and driver details before debugging deeper.
• Prefer extension points over vendor edits: publish config, bind custom implementations against package interfaces, and use documented macros/events. Keep a short upgrade note in your app’s changelog whenever you adopt a new package minor version.