Avatar Laravel Package

Getting Started

• Install the package with Composer (composer require <vendor>/<package>) and let Laravel's package discovery register the service provider. No manual provider entry is needed unless discovery is disabled in your app.
• Publish the config file first:

  php artisan vendor:publish --tag=sb-config
  

  As of v1.0.1 the published file is config/sb-<package>.php (note the sb- prefix). If you have an older un-prefixed config lingering from a pre-1.0.1 install, confirm which file the provider actually reads before editing — see Gotchas.
• Populate the environment variables referenced inside the config (typically API keys, driver selection, and queue toggles). Keep secrets in .env, not in the committed config.
• Run php artisan config:clear (and config:cache in deployed environments) so the new file is picked up.
• First use case: resolve the package's main class from the container and make a single call in a tinker session or a throwaway route before wiring it into application code:

  app(\Vendor\Package\Client::class)->ping();
  

  This validates credentials, endpoint configuration, and the config file resolve path in one step.

Implementation Patterns

• Resolve from the container, don't new. Use constructor injection or app(...) so tests can swap fakes and so any singleton bindings (HTTP client, cache store) are shared.
• Config as the single source of truth. Drive drivers, timeouts, and feature toggles from config('sb-<package>.*') rather than hardcoding values. Read config at call time, not in the service provider's register(), otherwise config:cache and per-test overrides won't take effect.
• Config overrides in tests. Use config()->set('sb-<package>.driver', 'fake') in setUp() and restore afterwards, or lean on the package's fake/swap helper if one is exposed.
• Queue long-running work. Wrap outbound calls in a job when the underlying operation is slow or rate-limited; respect the package's retry/timeout config keys rather than re-implementing backoff.
• Feature-flag rollouts. Since the whole surface is config-driven, you can dark-launch by setting the relevant sb-<package> keys from a per-environment config overlay (config/sb-<package>.php in env()-aware form) instead of branching in application code.
• Integrate at the boundary. Keep package calls inside a thin application service/repository so the rest of the codebase isn't coupled to the package's DTOs — this makes the eventual upgrade path (and any future config renames) a one-file change.

Gotchas and Tips

• The v1.0.1 config rename is the big one. The published config file gained the sb- prefix. If you previously published the un-prefixed file, it will not be overwritten by a normal vendor:publish (which skips existing files), and a stale un-prefixed config can sit next to the new one causing confusion. Delete the old file, re-publish with --force, and diff your customisations back in. Do not blanket --force in production without a backup.
• Stale config cache is the #1 "it's not reading my config" cause. After any config edit or upgrade, run php artisan config:clear. In production, rebuild with php artisan config:cache as part of deploy.
• Check the publish tag. Config publishing is tag-based (sb-config); vendor:publish without a tag may publish assets/migrations you don't want, or nothing at all if tags aren't registered.
• Watch provider boot order. If you reference the package's config inside another provider's boot(), ensure ordering or defer the read until after all providers have registered.
• Debugging config resolution: php artisan tinker → config('sb-<package>') dumps the effective merged config (package defaults + your overrides), which is the fastest way to confirm the prefixed file is the one loaded.
• Extension points: prefer the package's published config and container bindings over subclassing internals. Anything you override in a subclass won't receive upstream fixes and may break silently across minor releases like this one.
• Lockstep docs: if your team has internal runbooks referencing the old un-prefixed config path, update them alongside the upgrade — this rename is small but easy to miss in onboarding docs.