Rating Bundle Laravel Package

Getting Started

• Install and pin. composer require vendor/package:^2.0. Because 2.0 is the first tagged release, treat the version constraint as provisional — pin to 2.0.* in composer.json until you have a green CI run, then relax it.
• Confirm discovery. Laravel's package auto-discovery should register the service provider and any facade. Run php artisan about (or php artisan package:discover) and check that the provider appears. If the package predates discovery conventions, add it manually to config/app.php under providers and aliases.
• Publish before you configure. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (add --tag=config, --tag=migrations once you know the tags). Commit the published config file so environment differences are explicit rather than implicit.
• Where to look first, in this order: README.md → CHANGELOG.md → src/*ServiceProvider.php (this tells you what is bound, what is tagged, and which config keys are actually read) → config/*.php → tests/ in the package repo. The service provider is the most reliable documentation of behaviour; the README is the most reliable documentation of intent.
• First use case. Pick the narrowest read-only path through the package — a single resolve-and-inspect call, e.g. app(PackageManager::class) in php artisan tinker, or a GET route that renders one package-provided value. Prove the wiring (config resolution, container binding, credentials) before wiring it into a write path, a queue job, or a model event.

Implementation Patterns

• Wrap it, don't sprinkle it. Bind the package behind your own interface in a small app/Services adapter and resolve that. Package APIs churn faster than your domain; a single seam means a composer update becomes a diff in one class instead of a grep across the codebase.
• Prefer constructor injection over the facade. Facades are convenient in controllers and Blade, but constructor injection keeps the class unit-testable without Facade::clearResolvedInstances() gymnastics.
• Configuration as environment. Keep package credentials in config/services.php (or a dedicated config/<package>.php) reading from env(), and never call env() outside config files — config:cache will silently return null otherwise.
• Feature-flag the rollout. For a first-release dependency, gate usage behind a config flag or Laravel Pennant feature so a bad interaction in production is a config flip, not a revert-and-deploy.
• Integrate at the edges. Favour listeners and jobs over inline calls in HTTP requests: dispatch a job on the relevant domain event, let the package do its work in a queued context with its own retry/timeout policy. This isolates third-party latency and makes failures observable.
• Test with fakes where offered. If the package ships a fake or an assert* helper, use it in feature tests and keep one or two integration tests that hit the real implementation — otherwise you are testing the fake.
• Multi-tenant / multi-connection setups. Resolve per-tenant configuration inside a scoped binding (app()->scoped(...)) rather than a singleton, and verify the package does not cache a connection or client internally across requests (relevant under Octane).
• Deployment checklist. composer install --no-dev --optimize-autoloader, php artisan config:cache, route:cache, view:cache, event:cache. Any of these can expose an eager env() call or a closure-based route registration in a package that worked fine in local dev.

Gotchas and Tips

• 2.0 as a first release is a semver statement, not a stability guarantee. There is no 1.x migration path to learn from, so undocumented breaking changes between 2.0.x patches are plausible. Read the diff of each patch release, or at minimum the CHANGELOG, before bumping.
• Auto-discovery is cached. Adding the package and seeing "class not found" usually means composer dump-autoload (and on Octane, a worker restart) is missing. php artisan package:discover alone does not refresh the classmap.
• Publishing is a copy, not a merge. Re-publishing config after an upgrade overwrites your edits. Diff before overwriting, and prefer keeping local overrides in a separate config file that merges over the package defaults.
• Config cache hides new keys. After config:cache, newly added package config keys are absent until you re-cache. Symptom: null where the package expects an array. Fix: php artisan optimize:clear.
• Migration ordering. If the package publishes migrations, they are timestamped at publish time and will run after existing ones. On an established schema this can violate foreign keys — check the filenames before migrate, and consider copying them into database/migrations with adjusted timestamps.
• Facade alias collisions. A generic alias (Cache, Client, Manager) registered by the package can shadow or be shadowed by an existing alias. Register your own explicit alias rather than relying on the package default.
• Debugging order of operations. 1) php artisan about for provider presence, 2) php artisan tinker to resolve the binding and inspect the config array, 3) Log::debug() around the call with config('package') dumped, 4) php artisan vendor:publish --force into a scratch branch to compare defaults against your file. Nine times out of ten it is a config key or a cached config.
• Extension points worth locating early: container tags the package uses ($this->app->tag([...], 'name')), any Manager-style driver resolver (so you can register a custom driver via extend()), published interfaces intended for binding, and dispatched events you can listen to instead of subclassing internals. Subclassing package classes is the extension point of last resort — it breaks silently on minor releases.
• Budget for an exit. For a first-release dependency in a critical path, keep the adapter thin enough that replacing the package is a day's work, and record why it was chosen in the repo (an ADR or a paragraph in the README) while the reasoning is still fresh.