Webservice Bundle Laravel Package

Getting Started

• composer require vendor/package — Laravel's package auto-discovery should register the service provider and any facades via extra.laravel in the package's composer.json. Verify with php artisan about or by checking bootstrap/providers.php (Laravel 11+) — if it's not listed, register it manually.
• Publish what the package ships: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider". Look for tagged publishes (--tag=config, --tag=migrations, --tag=views) — publishing by tag is safer than a blanket publish because it won't dump assets you don't need.
• Read in this order: README quick-start → the published config/package.php → src/PackageServiceProvider.php. The config file is the fastest map of what the package can actually do; the service provider tells you what it binds, what it registers, and which extension points exist.
• Confirm the install before writing app code: run php artisan migrate if migrations were published, then resolve the class once in php artisan tinker (app(Vendor\Package\Client::class)) to prove the container binding and credentials work.
• First real use case: take the smallest happy path from the README — one call, one record created, one API round-trip — and put it behind a feature test. That test becomes your regression net for every future upgrade.

Implementation Patterns

• Resolve, don't instantiate. Always pull the package's client/service from the container (app(...), constructor injection, or the facade). Constructing with new bypasses config, HTTP client customisation, and any test doubles the package registers.
• Wrap it in a thin adapter. Put your own App\Services\... class in front of the package and inject that everywhere. The facade is convenient but it's a global; an adapter gives you one place to change when the package renames methods or you swap it out.
• Publish config, never edit vendor. Keep environment-specific values in .env and have the published config read them via env(). Everything else belongs in the config file, which is version-controlled and diffable.
• Push slow work to the queue. If the package exposes a client that makes network calls or does heavy writes, call it from a job rather than in the request cycle; use its events (if any) to decouple side effects from the call site.
• Register custom behaviour at boot. Drivers, macros, custom resolvers, and model/observer hooks usually go in a dedicated AppServiceProvider method or a small package-specific provider — not in AppServiceProvider::boot() mixed in with unrelated code.
• Test with the package's own fakes first. Many Laravel packages ship Package::fake() or an interface you can bind a stub to in the container. Prefer that over Http::fake() unless the package is a thin HTTP wrapper; fakes survive internal refactors better.
• Pin the major version in composer.json ("^1.0") and let patch/minor float. Given this is the 1.0.0 cut, treat the public API as now-stable and lean on semver for upgrade decisions rather than reading the changelog on every composer update.

Gotchas and Tips

• env() returns null after config:cache. Only call env() inside config files. If the package calls env() at runtime, you'll see it work locally and silently break in production — check for this first when "it works on my machine."
• Re-publishing overwrites your edits. vendor:publish --force will clobber a customised config. On upgrade, publish to a temp path or diff the package's config/package.php against yours rather than force-publishing.
• Double migrations. If the package calls loadMigrationsFrom(), do not also publish its migrations — you'll get duplicate-table errors. Pick one: published (editable, yours to own) for app-specific schema, loadMigrationsFrom for package-internal tables.
• Long-running processes cache resolved instances. Under Octane, Horizon, or a queue worker, a singleton resolved on boot may hold stale config or a dead connection. If you see "works after restart, breaks after a few jobs," that's the symptom — register as scoped or resolve per job.
• Auto-discovery is not universal. Packages installed with --no-scripts, or apps with a custom provider list, won't auto-register. Symptom: Target class [...] does not exist or a facade throwing "root not set."
• Debugging moves that pay off: php artisan about (providers/config status), php artisan tinker to poke the resolved instance, Log::debug() inside your adapter to confirm what you're passing in, and php artisan config:clear before assuming the package is broken.
• Useful extension points, roughly in order of stability: container bindings for interfaces, published config, package events/listeners, custom driver registration, then facades/macros. Prefer the earliest that solves the problem — the later ones are more likely to churn.
• Upgrade ritual: read UPGRADE.md/CHANGELOG.md for the target version, bump, run the full suite, then grep your code for any renamed or deprecated methods. Keep the adapter from the patterns section thin and this stays a 15-minute job.