Filament Web3 Auth Laravel Package

Getting Started

This release (v1.2.0) is a compatibility release: it adds Filament V5 support. There are no documented breaking changes or new end‑user features, so the practical takeaway is that you can now use the package on a V5 panel — and that version alignment is the single most important thing to get right on day one.

Minimal steps:

1. Confirm your Filament major version first. Run composer show filament/filament and check whether you're on V4 or V5. The package version you can install depends on it — installing v1.2.0 into a V4 panel, or an older package tag into a V5 panel, is the most likely source of a confusing failure.
2. Require the package with a constraint that matches your Filament line, then clear caches:

composer require <vendor>/<package>:"^1.2"
php artisan filament:upgrade
php artisan optimize:clear

3. Publish and review config/assets if the package ships them. php artisan vendor:publish --tag=<package>-config (and any -assets/-views tags listed by php artisan vendor:publish with no arguments). Diff the published config against the package's own file — a new major compatibility release often changes defaults or adds keys.
4. Register the plugin in your panel provider — this is where to look first if nothing appears:

use Vendor\Package\PackagePlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            PackagePlugin::make(),
        ]);
}

5. First use case: open the panel and exercise the package's primary surface once — the resource/page/widget it contributes — plus one write action. If both render and persist, your wiring is correct and you can move on to configuration.

If the package has a changelog or upgrade guide beyond the release title, read the v1.2.0 entry before touching production; a one-line release note usually understates constraint and API changes.

Implementation Patterns

Pin the Filament major in your root composer.json. The package now supports V5, but that doesn't mean it drops V4 in the same tag. Add an explicit constraint so a future composer update can't silently move you across a Filament major:

"require": {
    "filament/filament": "^5.0",
    "<vendor>/<package>": "^1.2"
}

Register the plugin per panel, not globally. Filament panels are independent; if you run an admin panel and a customer-facing panel, register the package only where it belongs. This is also the cleanest way to give the package different config per panel.

Keep configuration in config/<package>.php, not in the panel provider. Panel providers get noisy fast. Publish the config once, commit it, and reference it from a thin plugin instance:

PackagePlugin::make()
    ->usingConfig(config('package.presets.admin'))

Wrap the package's surface in your own policy/authorisation layer. Filament plugins typically contribute resources, actions, and widgets that assume a broad viewAny gate. If your app has tenancy or role-based access, add the policy before you expose the resource — retrofitting authorisation after users have bookmarks is painful.

Version-gate in CI. Add a job that resolves dependencies against both Filament V4 and V5 if the package's constraint allows it, or at minimum a composer update --dry-run check. Compatibility releases are exactly where transitive constraint conflicts surface, and catching them in CI beats catching them in a deploy.

Treat the package's views as overridable, not forkable. If it publishes Blade views, override them in resources/views/vendor/<package>/ rather than editing vendor/. That's your extension point for styling and copy changes that survive composer update.

Test the upgrade path on a branch with the panel's own test suite. Filament's testing helpers (livewire(), callAction(), assertCanSeeTableRecords()) make it cheap to assert that the package's resource still renders and that its actions still execute after the bump.

Gotchas and Tips

• "V5 compatible" ≠ "V5 required". Check the actual composer.json constraint before assuming you must upgrade Filament. Conversely, don't assume v1.2.0 still supports V4 — if the tag bumped the minimum, staying on V4 means staying on v1.1.x.
• Filament's upgrade step is not optional. After changing Filament or plugin versions, run php artisan filament:upgrade and republish public assets. Stale published assets are the classic cause of "the plugin renders but looks broken".
• Clear the right caches. optimize:clear covers most cases, but if you have config:cache enabled in local dev, published config edits appear to do nothing. Check bootstrap/cache/config.php exists before debugging the package itself.
• Panel provider ordering matters. Plugins registered after ->resources() or ->discoverResources() can behave differently than before; if a resource vanishes, move the plugin registration earlier in the chain and retest.
• Version conflicts hide behind Composer's solver. If composer require fails with a constraint wall, run composer why-not filament/filament and composer show <vendor>/<package> --all to see which tag pairs with which Filament line. Reading the solver's output is faster than guessing at constraints.
• Multi-panel and tenancy are the usual regressions. Compatibility releases rarely touch tenancy logic, so if a scoped resource suddenly leaks across tenants, suspect your own panel config or a changed default rather than a deliberate new feature.
• Debugging checklist, in order: (1) is the plugin registered on this panel, (2) is config cached, (3) are assets republished, (4) does composer show confirm the expected package and Filament versions, (5) does the package's issue tracker already list the symptom against this tag.
• Extension points worth knowing: plugin instance methods for runtime config, published config file, published/overridable views, and any registered Filament hooks or render hooks the package exposes. Prefer these over subclassing the package's resources, which breaks on minor releases.