User Bundle Laravel Package

Getting Started

• Install with composer require vendor/package, then confirm the service provider is auto-discovered (php artisan package:discover). If the package ships a config file, publish it immediately: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" — read that config file before writing any code, it is the fastest way to understand the package's mental model.
• Skim three files in this order: README.md (usage), CHANGELOG.md/UPGRADE.md (anything you are inheriting), and the package's config/*.php. Skip the source until the config stops answering questions.
• Check for migrations (php artisan vendor:publish --tag=package-migrations) and run php artisan migrate before the first call, otherwise you get confusing "table not found" errors that look like package bugs.
• First use case: wire it into a single, low-risk path — one controller or one queued job — behind a feature flag or an env-gated config value. Verify with php artisan tinker before touching the UI.

Implementation Patterns

• Resolve from the container, not statically. Prefer constructor injection of the package's contract/manager over the facade. This keeps it mockable in tests and lets you swap the binding in a service provider for local/staging.
• Wrap it in your own thin service. Create App\Services\... that owns the package call plus your domain rules (retries, logging, DTO mapping). When the package changes or you outgrow it, you edit one class instead of 40 call sites.
• Configuration over code. Most Laravel packages expose drivers, timeouts, queues, and table names in config. Push environment-specific values into config/ + .env rather than branching in application code.
• Events and listeners for side effects. If the package dispatches events, hook those instead of editing the package flow. If it doesn't, dispatch your own from the wrapper service.
• Queue long work. Anything network-bound (API calls, syncs, exports) belongs in a job with $tries, $backoff, and $timeout set deliberately. This is the single most common production mistake with third-party integrations.
• Testing: use the package's fake/null-driver if it ships one; otherwise bind a mock of the contract in the container inside setUp(). Assert on your wrapper's behaviour, not the package's internals.

Gotchas and Tips

• Config caching bites first. After editing published config, run php artisan config:clear. A stale bootstrap/cache/config.php is the cause of most "my change did nothing" reports.
• Publishing overwrites. vendor:publish will clobber edited config/migrations. Keep published files in version control and diff them on upgrade rather than re-publishing blind.
• Octane and long-lived workers. Singletons holding request state leak between requests. Bind as scoped if the package is request-aware, and restart queue workers (queue:restart) after deploys so they pick up new code and config.
• Migrations are frozen. Never edit a published migration after it has run in production; add a new one. Also check whether the package's migrations collide with your table naming.
• Silent failures. Set a dedicated log channel or Telescope tag for the package's namespace, and log both the request payload and the raw response in your wrapper. Vendor SDK exceptions are often generic; the response body is where the truth is.
• Extension points to reach for before forking: container bindings and extend() on the manager, custom drivers via config, macros, published views, and the package's event/listener hooks. Fork only as a last resort — if you must, note it in the README so the next developer knows.
• Watch the version pin. Pin to a caret range you have actually tested ("^3.1"), read UPGRADE.md before minor bumps on packages that follow 0.x-style semantics, and add a smoke test that exercises the integration on every dependency update.