Filament Model States Laravel Package

Getting Started

This is the package's first tagged release (1.0), so there is no migration path to plan for — you are adopting from zero, which is the cheapest time to evaluate it.

Minimal steps

1. composer require <vendor>/<package> — check the require block first. If it pins illuminate/support to a narrow range, confirm it matches your Laravel version before installing; a 1.0 package often supports only the latest one or two majors.
2. Confirm package discovery worked: php artisan about and look for the provider, or run php artisan package:discover (Composer's post-autoload hook usually handles it). If the package ships a provider without extra.laravel.providers, you must register it in bootstrap/providers.php (Laravel 11+) or config/app.php.
3. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (or --tag=<package>-config). Read the published config file end to end — for a 1.0 release this is often the most complete documentation available.
4. Check for migrations: php artisan vendor:publish --tag=<package>-migrations then php artisan migrate. On a fresh package, verify whether migrations are publishable or loadable, and whether they are idempotent.

Where to look first

• README.md install section, then CHANGELOG.md (it will be a single entry) and UPGRADING.md (if present, that signals the maintainer intends semver discipline).
• src/*ServiceProvider.php — the register() and boot() methods tell you more about the real API surface than the README: what is bound in the container, which singletons are aliased, what config keys are merged, and which extension points exist.
• The facade's @method docblock, if there is one. That is your de facto API index.

First use case

Pick one narrow, reversible integration — a single model, one queue, one command — and wire it end to end before touching anything else. For a 1.0, the goal of the first hour is to learn the failure modes (what happens with a missing config key, an empty table, a queued job that retries), not to cover the feature matrix.

Implementation Patterns

Wrap it, don't sprinkle it. Resolve the package through the container and bind it behind your own thin interface or a single application-level service class. This is the highest-value habit with a 1.0 dependency: when the API shifts at 1.1, you edit one adapter instead of forty call sites.

// app/Services/Billing.php
final class Billing
{
    public function __construct(private \Vendor\Package\Client $client) {}

    public function charge(Order $order): Result
    {
        return $this->client->create([...]);
    }
}

Configure via environment, not the published file. The published config is a template — commit it so keys are discoverable, but drive values from env() and keep secrets in .env/your secret store. Never edit vendor/. Add every new key the package introduces to your own config on upgrade rather than re-publishing and clobbering.

Test seam. In phpunit.xml, set the package's config to a fake/driver mode if one exists, and use Http::fake() / Queue::fake() / Event::fake() around it. If the package ships its own testing helpers or a fake (e.g. Package::fake()), prefer them over hand-rolled mocks — they track the real interface and survive upgrades better.

Integration tips

• If the package fires events, listen to them rather than polling its state. Events are usually the most stable part of a young API.
• If it offers queued jobs, set an explicit $queue and $timeout in your own config; do not rely on defaults from a package that has not yet been battle-tested under your workload.
• Register tenant/context bootstrapping (Octane, queue worker restarts, AppServiceProvider::boot()) explicitly. Long-lived workers + a package holding per-request state is the single most common 1.0 bug class.
• Wrap calls that cross a network or write state in rescue()/try-catch at the boundary if the package does not define exception types clearly, and log with a package-specific channel so you can isolate its noise.

Gotchas and Tips

Pitfalls

• 1.0.0 means "first stable tag", not "battle-tested". Treat the surface as frozen-ish but the internals as unknown. Pin exactly ("vendor/package": "1.0.*") and let Renovate/Dependabot open PRs you review, rather than floating ^1.0 on production without a changelog habit.
• Config cache. php artisan config:cache in deploy means a missing published config or a stray env() call inside the package's config file silently resolves to null. Test the deploy path with the cache enabled, not just php artisan serve.
• Merged config wins silently. mergeConfigFrom() fills gaps but never overrides your published file — so a key added in 1.1 will be absent from your published copy and quietly fall back to the package default. Diff the package's config/*.php against yours on every upgrade.
• Auto-discovery and provider order. If the package depends on another provider being registered first (routes, auth guards, DB connections), an occasionally-ordered boot() will look like a random bug. Bind in register(), use in boot().
• Migrations in a 1.0. Check whether the migration uses ->nullable() defaults sensibly and whether rollback is real. On a large existing table, add the index/backfill yourself rather than trusting a package migration.
• Facade aliasing. An unaliased facade (\Vendor\Package\Facades\Thing::) inside tests resolves the real object; a fake registered via swap() or instance() only works if the facade's accessor matches — verify the binding name, not the class name.

Debugging

• Start with php artisan tinker and resolve the core binding directly (app(\Vendor\Package\Client::class)) — that isolates "package broken" from "my wiring broken".
• php artisan vendor:publish --list / php artisan about to confirm what the package actually registered on this install.
• Ray / dump() inside the provider's boot() temporarily (in a throwaway branch) to confirm registration order.

Extension points to prefer

Prefer, in order: events and listeners → published config → public interfaces bound in the container → facades. Avoid extending concrete classes or overriding vendor stubs; both will break at the first minor release. Where the package lets you extend() a driver or swap() a binding, that is the sanctioned seam — use it and note it in your adapter so the next upgrade has an obvious place to look.

Verdict for 1.0. Adopt behind an adapter on one integration, pin the version, and keep a short note in your repo of every package touchpoint (provider, config keys published, migrations run, events listened to). That inventory is what makes the 1.1 upgrade a thirty-minute task instead of an archaeology project.