Gauge Laravel Package

Getting Started

• Install with composer require <vendor>/<package> and let Laravel's package auto-discovery register the service provider. If the package predates discovery or you need conditional registration, add it manually to bootstrap/providers.php (Laravel 11+) or config/app.php.
• Publish what you need before writing any code:

  php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
  php artisan vendor:publish --tag=package-config
  php artisan vendor:publish --tag=package-migrations
  

  Publish selectively — config and migrations almost always; views/assets only if you actually intend to override them.
• Read the published config file first, not the README. Config keys, defaults, and inline comments are the most accurate description of runtime behaviour, and they tell you which knobs are safe to touch.
• Open the service provider next. It shows you what is bound into the container, which singletons are shared, what is registered as a driver/manager, and which extension points exist. Five minutes there saves an hour of guessing.
• Check composer show <vendor>/<package> for the installed version against the changelog/UPGRADE notes so you know which doc section applies to you.
• First use case: take the shortest end-to-end path — configure credentials/connection in .env, resolve the package's main entry point from the container in php artisan tinker, call the single simplest method, and confirm the result. Once that round-trip works, wire it into one real code path (a controller action, a queued job, or a console command) and verify with a feature test. Do not scaffold broadly until that one path is green.

Implementation Patterns

• Resolve from the container, never new. app(Client::class), constructor injection, or the facade — whichever the package documents. Instantiating directly bypasses config, HTTP client customisation, and any shared state the provider sets up.
• Wrap it in your own thin adapter. Define an interface in your domain (e.g. App\Contracts\Geocoder) and a single implementation that delegates to the package. Everything else in your app type-hints the interface. This is the cheapest insurance against a future major version or a swap-out, and it makes faking in tests trivial.
• Bind the interface in a dedicated service provider, not in the package's config. Your app owns the seam; the package stays replaceable.
• Keep package calls out of Eloquent models and controllers. Push them into actions/services or queued jobs so the call site is testable in isolation and retryable on failure.
• Queue anything remote. Wrap outbound calls in a job with $tries, backoff(), and failed() handling. Use ShouldBeUnique where duplicate dispatch would cause double side effects.
• React to package events, don't poll. If the package dispatches events, register listeners in EventServiceProvider rather than scheduling a cron to check state.
• Config vs. runtime: put environment-varying values (credentials, endpoints, timeouts) in config/package.php reading from env(), and put per-tenant/per-request values in method arguments or a scoped instance. Never resolve config at class-construction time if it can change per request.
• Migrations belong in your repo once published. Treat published migrations as owned code: review them, add indexes you need, and commit them with the rest of the schema.
• Roll out behind a flag. Add a config toggle or Laravel Pennant feature so you can disable the integration in production without a deploy.
• Testing: Facade::swap() or $this->instance(Interface::class, $fake) in the container; Http::fake() if the package sits on the HTTP client; Queue::fake()/Event::fake() to assert dispatch rather than execution.

Gotchas and Tips

• env() outside config files returns null once config:cache runs. If the package reads env() directly, it will silently break in a cached production deploy but work locally. Audit the package for direct env() calls and mirror those values into your own config if needed.
• Config caching after install. Run php artisan config:clear after publishing config or editing .env; a stale cache is the single most common "the package ignores my settings" cause.
• Published files are copies, not symlinks. Upgrading the package does not update your published config, migrations, or views. Diff against vendor/<vendor>/<package>/config/... after every minor bump and merge deliberately.
• vendor:publish --force will overwrite your edits. Re-run with --force only when you have nothing local to lose, or publish to a versioned path and diff.
• Auto-discovery surprises. Two packages registering the same binding, or a package registering a facade alias that collides, produces confusing resolution errors. php artisan about and php artisan package:discover -v help you see what's actually registered.
• Singletons and long-running workers. In Octane or queue workers, a singleton holding request state leaks across requests/jobs. If the package binds a singleton, check whether it exposes a reset/scoped method, or prefer scoped() bindings in your own wrapper.
• Facade mocking leaks between tests. Facade::swap() persists for the process; reset in tearDown() or prefer container instance() bindings, which Laravel restores automatically.
• Debugging order: (1) php artisan config:clear, (2) php artisan tinker and resolve the class to confirm it's the real implementation and not a stub, (3) Log::debug() around the call site, (4) Http::fake()/Event::fake() in a test to isolate whether the failure is in the package or in your wiring.
• Extension points to look for before forking: custom drivers via the manager's extend(), container rebinding of an interface the package type-hints, Macroable traits, and publishable stub/contract classes. Most day-to-day customisation should be achievable through these rather than a fork.
• Pin the version ("^1.1" rather than "*") and re-run your integration test suite on every bump — especially across minors, where published-asset drift and config-key renames are the usual breakage.