Filament Userback Plugin Laravel Package

Getting Started

This package is a Filament plugin/integration. Release 1.1.0 adds support for Filament PHP v5, which is the headline change — everything else about the package's surface area appears unchanged, so existing v1.0.x usage patterns carry over.

Minimal setup:

composer require <vendor>/<package>:^1.1

Before installing, confirm your version matrix lines up. The package now supports Filament v5, but your app and any other Filament plugins must also be on v5 — Composer will refuse to resolve otherwise (see Gotchas).

php artisan vendor:publish --tag="<package>-config"

Then register the plugin on the panel(s) that should use it, in the relevant PanelProvider:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(<Package>::make());
}

Where to look first, in order:

1. README.md — registration snippet and any required publish tags.
2. src/<Package>ServiceProvider.php — shows what is registered, what is publishable, and whether config/view/lang publishes exist.
3. config/<package>.php (after publishing) — the real behavioural surface.
4. CHANGELOG.md / upgrade guide — for the 1.0 → 1.1 Filament major jump.

First use case: install it on a single existing panel, run php artisan filament:upgrade (or filament:assets if assets changed), clear caches, and load the panel. Verification is visual — if the panel boots and your new resource/page/widget renders, registration is correct. Do not start by wiring it into every panel; get one panel green first.

Implementation Patterns

Pin to the Filament major you actually run. The practical pattern for a package tracking multiple Filament majors is a constraint such as ^1.1 alongside filament/filament:^5.0 in composer.json, letting Composer's solver pick the compatible combination. If you are staying on Filament v3/v4, stay on the last 1.0.x release and lock it; 1.1.0 is not a drop-in for those.

Panel-scoped registration over global. Register the plugin in plugins([]) on the specific PanelProvider rather than reaching for a global service provider binding. This keeps multi-panel apps (admin / customer / vendor panels) from leaking the plugin's resources, widgets, or navigation entries into panels that shouldn't have them. If the package ships resources or pages, they inherit the panel they're registered against — this is usually exactly what you want.

Config-first, then fork. Publish the config file and treat it as the tuning surface for navigation groups, labels, feature flags, and default behaviour. Only after publishing and hitting a genuine limitation should you extend the underlying classes or override views via ->viteTheme() / custom view namespaces — otherwise you're carrying upgrade debt for a one-line config change.

Compose with existing Filament surfaces. Treat the plugin as additive: reuse your existing form/table schema components, apply your ModelPolicy via canAccess() / canViewAny() rather than the package's own permission toggles where possible, and keep authorization in one place. If the package exposes schema macros or render hooks, prefer those over subclassing, since hooks survive minor upgrades better.

Test it at the panel level. Filament features are hard to unit-test in isolation; use Livewire::test() against the generated resource/page classes and assert on rendered output plus authorization behaviour. Add a smoke test that boots each panel ($this->get('/admin')->assertOk()) — that catches 90% of plugin registration and asset problems before deploy.

Keep config and assets in the deploy pipeline. Any published config should be committed; published assets should be regenerated as part of deploy (php artisan filament:assets), not committed. If you use config:cache, make sure the package's config is cache-safe and that you re-run php artisan optimize:clear after bumping the package.

Upgrade path pattern. For the 1.0 → 1.1 jump, do it on a branch: bump filament/filament to ^5.0 and this package to ^1.1 in the same commit, re-publish config/views and diff them against your committed versions, then run the panel smoke test. Never split the Filament major bump and the plugin bump across separate deploys — you'll be debugging a broken panel with two moving variables.

Gotchas and Tips

Peer dependency deadlock is the most likely failure. Adding Filament v5 support means the package's composer.json now constrains filament/filament. If a second plugin in your stack still requires v4, resolution fails or silently downgrades. Run composer why-not filament/filament ^5.0 to find the blocker, and use composer update "vendor/*" -W rather than a bare composer update when deliberately moving the whole Filament ecosystem forward.

A minor version bump can be a breaking change for your app. 1.1.0 is semver-minor for the package, but it drops you onto a new Filament major. Treat the Filament side as the breaking change: read Filament's own v5 upgrade notes, not just this changelog. Anything in your app that touches Filament internals, custom themes, or overridden views needs re-verification.

register() vs boot() mistakes surface as silent no-ops. If the plugin appears registered but nothing renders, check whether the package's service provider defers work to boot() and whether your panel resolves before that. Also confirm plugin ordering inside plugins([...]) — plugins that modify navigation or schema can produce different results depending on order.

Stale caches after upgrading. config:cache, route:cache, view:cache, and Filament's own asset manifest are all common causes of "I upgraded and nothing changed." The reliable sequence is php artisan optimize:clear && php artisan filament:upgrade (or filament:assets), then hard-reload the browser.

Published files drift silently. If you published config or views on 1.0.x, the 1.1.0 versions may have new keys or markup. Diff the published file against vendor/<vendor>/<package>/config/... after upgrading — a missing config key usually manifests as a null or default behaviour rather than a loud error.

Pinning and reproducibility. Commit composer.lock. In CI, run the test matrix against the exact lock file and add a separate job that resolves ^1.1 fresh to catch upstream drift early. For libraries or apps with long release cycles, consider composer require <vendor>/<package>:1.1.* to avoid surprise minor bumps.

Debugging a panel that won't boot. Temporarily remove other plugins from plugins([]) to isolate whether this package is the cause, and check storage/logs/laravel.log for container resolution errors — Filament plugin failures frequently present as an unresolvable class in the panel's dependency graph rather than a descriptive exception.

Extension points worth knowing before you fork. Look for: config keys, make() named constructors/fluent setters on the plugin class, schema macros, render hooks, and custom view namespaces. If the package exposes any of these, prefer them — but note they are the least stable surface across a Filament major bump, so keep usage shallow and covered by a smoke test.