Filament Guard Laravel Package

Getting Started

Start by pinning the release and reading the source, not just the README — at 0.x the public surface is still moving, and the authoritative contract is the service provider plus any facade/interface it binds.

composer require <vendor>/<package>:^0.3
php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"

Then confirm three things before writing feature code:

1. What the provider registers — singleton vs. scoped binding, deferred or not. If it is deferred, resolve it once in tinker so you learn the concrete class behind the interface.
2. What config keys exist — config/<package>.php is the cheapest place to discover defaults, driver choices, and queue/connection settings.
3. What it publishes — migrations, config, views, or stubs. Publish everything into a throwaway branch first so you can see the full footprint before committing.

First use case: the smallest end-to-end path through the package in a single test, not in a controller. A feature test that resolves the binding from the container, exercises one happy path, and asserts one observable side effect (a DB row, a dispatched job, an HTTP call) tells you more about ergonomics in ten minutes than an hour of reading. Build that test first; it becomes your regression harness when 0.4 lands.

Look first at the package's own tests/ directory and CHANGELOG.md. Upstream tests encode the intended usage pattern and the assumptions the maintainer makes about your app's container, config, and queue setup.

Implementation Patterns

Wrap the package, don't sprinkle it. Bind it behind your own thin interface or a small application service, and inject that. Direct facade calls scattered across controllers make a 0.x → 1.0 upgrade a grep-and-pray exercise. One adapter class is cheap insurance.

final class InvoiceSync
{
    public function __construct(private readonly <PackageClient> $client) {}

    public function push(Invoice $invoice): void
    {
        $this->client->send($invoice->toPayload());
    }
}

Prefer container resolution over new. Any class the package exposes should come out of the container so its dependencies, config, and HTTP client are the ones your app actually configured — including fakes in tests.

Push side effects onto the queue. Anything that touches a third party belongs in a job with $tries, $backoff, and failed() handling. If the package ships its own job or listener, use it — but set the queue connection and timeout explicitly in your own config rather than trusting the default.

Drive it from events where it fits. If the package listens to model events or emits its own, wire it through Laravel's event system so you can Event::fake() in tests and toggle integration per environment.

Feature-flag the integration. Config-gate the adapter so local and CI environments can run against a fake or a no-op driver. This is the difference between a package you can develop against daily and one that blocks your test suite.

Test with fakes at the boundary. Http::fake(), Queue::fake(), Event::fake() — assert your adapter dispatched the right thing, not the package's internals. Combined with RefreshDatabase if it publishes migrations.

Keep an upgrade lane. Record the resolved version in composer.lock, read the diff between tags when bumping minor versions at 0.x, and keep your adapter's test suite green as the gate.

Gotchas and Tips

• 0.x has no semver guarantee. A 0.2 → 0.3 bump can break you. Constrain to ^0.3 and read the release diff before every bump; do not use * or dev-main in anything shared.
• Config cache surprises. After editing the published config, run php artisan config:clear in local and remember config:cache in deploy — closures in config files will fatal at cache time.
• Silent container failures. "Target [X] is not instantiable" usually means the provider is not registered (check bootstrap/providers.php on Laravel 11+) or the package is deferred and you resolved it before boot.
• Publish-then-edit is one-way. Once you edit published migrations or config, package updates won't touch them. Prefer overriding via your own config/environment variables and leaving published files close to stock.
• Queued work hides errors. A package job failing silently on a queue nobody watches is the classic day-two bug. Give it a real failed() handler or a monitored queue.
• HTTP client leakage. If the package builds its own Guzzle client instead of using Laravel's Http factory, Http::fake() won't intercept it. Check before you write tests that assume otherwise.
• Timeouts and retries are your responsibility unless the package documents them. Set them in config; defaults are often "wait forever."
• Debugging entry point: php artisan tinker → app()->make(<Interface>::class) and dd() the resolved instance. Then php artisan about to confirm providers and config are actually loaded.
• Extension points to look for: contracts/interfaces you can rebind in your own provider, events you can listen to, and macros. Rebinding in a test-only or local provider is the cleanest way to swap behaviour without forking.
• Upgrade checklist: read the changelog diff, run your adapter's tests, check for removed config keys and renamed contracts, then re-publish only the files you never edited.