Laravel Configurable Laravel Package

Getting Started

• Install with composer require <vendor>/<package>:^1.5 and confirm your app is on PHP 8.0+ if you want the new support — v1.5.0 is the first release advertising PHP 8 compatibility, so older pins may resolve to a version that blocks the upgrade.
• Sanity-check the constraint before debugging anything else: composer why-not <vendor>/<package> 1.5.0 and composer show <vendor>/<package> will immediately tell you whether you're fighting the package or your platform (composer.lock, CI image, Docker base image, or config.platform.php).
• Look first at composer.json (autoload, extra.laravel.providers / aliases for package discovery), then the service provider in src/, then the config file. Those three tell you almost everything about how the package expects to be wired.
• Publish and inspect config before writing code: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag=config. Reading the config keys is faster than reading the README.
• First use case: resolve the package's main entry point from the container in php artisan tinker and make one real call end-to-end. This confirms discovery, config merge, and credentials in one shot before you build anything on top of it.

Implementation Patterns

• Prefer constructor injection over facades in application code. Resolve the package's contract/class in the constructor of your service, job, or controller so it's swappable in tests and obvious in the dependency graph. Use the facade only for one-liners in controllers, Artisan commands, and Blade.
• Bind and configure, don't hardcode. If the package exposes an interface, bind your preferred implementation in a dedicated service provider rather than scattering new calls. Keep package credentials in config/services.php or the package's own config file, fed by .env.
• Wrap third-party calls in your own thin adapter. Even a 20-line wrapper class means an upgrade to v2 (or a swap to another package) touches one file instead of fifty. This matters most for anything that makes network calls or writes to storage.
• Fake it in tests. Most Laravel packages ship a fake or a mockable contract — use it in feature tests, and keep one small integration test that hits the real path so you find out when an upgrade changes behaviour.
• Pin to ^1.5 and let CI prove the PHP 8 path. If you run a matrix, add 8.0/8.1/8.2 explicitly; the release note claims support, but only your test suite confirms it against your usage.
• Defer expensive work to the queue. If the package does I/O, wrap it in a job with retries and a timeout rather than calling it inline in a request. This is a common day-to-day pattern and the package's own events/listeners usually give you a hook for it.
• Use the package's events if it fires them. Listening to a ...WasCreated / ...Failed event is far more upgrade-stable than subclassing internals.

Gotchas and Tips

• "PHP 8 support" is a claim about the constraint, not your app. Check that composer.json now allows ^8.0 and that the code actually runs — deprecations like required-after-optional parameters, removed curly-brace array access, and changed default behaviour of internal functions are the usual suspects. Run your suite with E_ALL and watch the deprecation log.
• Lock file vs. platform mismatch. composer update <vendor>/<package> -W is usually needed because transitive dependencies may also need bumping. If CI runs a different PHP than your laptop, set config.platform.php so resolution is deterministic.
• Config caching is the #1 false alarm. After changing package config or .env, run php artisan config:clear. A cached config silently ignores new keys added in v1.5.0.
• Package discovery hides provider problems. If things resolve locally but not in production, check bootstrap/cache/packages.php is regenerated (composer dump-autoload, php artisan package:discover).
• Facade aliases are global. A short alias can collide with another package or your own class — alias it explicitly in config/app.php if you hit a conflict.
• Don't subclass to customise. Prefer the documented extension points (container bindings, config, published views/migrations, events) — internal classes are the first thing to change in a minor release.
• Debugging checklist: composer show for the resolved version, php artisan about for the environment, config('package.key') in tinker for the merged config, and the package's own log channel for swallowed exceptions.
• Add static analysis. Larastan/PHPStan at a moderate level catches most of the signature and type churn that minor releases introduce, and it's cheap insurance if you plan to track this package forward.