Nova Locale Switcher Laravel Package

Getting Started

The 1.0.0 notes only confirm an initial release, so treat the repository itself as the documentation until a README with usage details lands.

1. Install and confirm discovery. composer require <vendor>/<package> and then check that Laravel auto-discovered the service provider:

   php artisan package:discover --ansi
   

   If the package isn't listed, open its composer.json and look for the extra.laravel.providers / extra.laravel.aliases block — a missing or malformed block is the usual cause, and you'll need to register the provider manually in bootstrap/providers.php (Laravel 11+) or config/app.php.
2. Read four files first. In order: composer.json (PHP/Laravel constraints and discovery metadata), src/*ServiceProvider.php (what it binds, publishes, and registers), config/*.php (the actual knobs), and README.md + CHANGELOG.md. The provider tells you more about real behaviour than the release notes do.
3. Publish config before writing any code.

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   

   Run it with no tag first to see which tags exist, then re-run scoped (--tag=config, --tag=migrations).
4. First use case: a smoke test, not a feature. Resolve the package's main class out of the container and assert it boots. One test in tests/Feature/ that calls app(YourPackageClass::class) catches ~80% of install problems (missing extension, bad credentials, unresolvable constructor dependency) before you build anything on top.

Implementation Patterns

Resolve through the container, never new. Bindings are where the package does its configuration work. app(Foo::class) or the injected interface respects whatever the provider registered; new Foo() bypasses it and will silently ignore config.

Wrap it in a thin adapter of your own. Even a five-line App\Services\YourWrapper that composes the package class pays off the moment you upgrade or swap implementations. Call sites depend on your class, not the vendor's namespace.

final class ShippingRates
{
    public function __construct(private \Vendor\Package\Client $client) {}

    public function forOrder(Order $order): array
    {
        return $this->client->rates($order->toPayload());
    }
}

Config over code. Anything the package exposes in config/<package>.php should be set there and driven by env() in your .env, not passed as arguments scattered through the codebase. Add the keys to your .env.example in the same commit — it's the single most common cause of "works locally, breaks in CI."

Keep long-running work out of the request cycle. Anything that calls an external service belongs in a queued job or console command. Resolve the package inside handle(), not in the job's constructor — constructor injection is serialised with the job and can capture stale config.

Testing. If the package ships fakes or a testing trait, use them; check src/Testing/ or a Fakes namespace. If not, bind a mock in the container in your setUp():

$this->mock(\Vendor\Package\Client::class, fn ($m) => $m->shouldReceive('rates')->andReturn([]));

Integration edges. Check whether the provider registers its own migrations, routes, commands, or scheduled tasks — published migrations change your migrate output, and auto-registered commands show up in artisan list. Confirm both deliberately rather than discovering them in production.

Gotchas and Tips

• 1.0.0 is a starting line, not a stability guarantee. Semver says a 1.x line won't break you, but new packages churn hard in the first few minors. Pin "^1.0" and actually read CHANGELOG.md before bumping — pre-2.0 packages frequently ship behaviour changes in patch releases.
• Publishing is a copy, not a link. Once you've run vendor:publish, upstream config changes will never reach you. Diff the package's config/ against yours after every upgrade. Same for published views and migrations.
• --force overwrites your edits. Use it only when you've reviewed the diff, and never against published migrations you've already run.
• Cache invalidation after install/upgrade. php artisan config:clear && php artisan package:discover fixes most "provider not found" and "config ignored" reports. In production, your deploy script must re-run package:discover (usually via composer install) and config:cache.
• Verify the support matrix yourself. composer.json require is authoritative on PHP and illuminate/* versions. A package that declares ^10.0 only will resolve oddly on Laravel 11 — check before you plan around it.
• Debugging resolution failures. Wrap the container call in a try/catch and dd($e) the binding chain, or check php artisan about and the provider's register() for an early return guarded by a config value you haven't set.
• Extension points, in order of stability: container bindings and interfaces (safest — rebind the interface to your own implementation), published config, published views, then facade extend()/macros. Avoid subclassing concrete vendor classes; that's the seam most likely to break in a minor release.
• Missing docs are a finding, not a blocker. With release notes this terse, open issues or a PR against the README once you've reverse-engineered the happy path — you'll need those notes again at upgrade time, and so will the next developer on the project.