Filament Gravatar Provider Laravel Package

Getting Started

This package's headline capability is Filament integration, and v1.0.2 adds Filament v5 support. That makes it a panel-level dependency rather than a standalone library — the fastest path to value is standing it up inside an existing Filament panel and seeing it render before you wire any business logic.

Minimal steps:

1. Check the version matrix first. Confirm your laravel/framework, filament/filament, and livewire/livewire versions against the package's composer.json. Filament v5 support generally implies a newer Laravel and Livewire baseline; if you are still on Filament v4, pin the package to the release line that matches rather than assuming forward compatibility.
2. Install with composer require and then run php artisan vendor:publish --tag=<package>-config (also publish migrations and assets if the install docs list them). Publish before migrating — Filament packages frequently ship settings or media tables.
3. Register the plugin on your panel in the relevant PanelProvider::panel() chain. This is the single most common "it installed but nothing happened" cause: the service provider auto-discovery handles bindings, but Filament panels require explicit plugin registration in v4/v5.
4. Look here first, in order: README.md install section → config/<package>.php → the package's src/*ServiceProvider.php (to see what is auto-registered and what is conditional) → any src/Filament/ directory (to see which resources, pages, widgets, and plugins are exposed).
5. First use case: render the package's Filament resource or page for one model, with a single field and no custom actions. If it lists and edits records, the integration is sound and you can layer on actions, widgets, and policies.

If the package exposes both a Filament surface and a plain Laravel API, start with the Filament surface — it is the advertised path and the one the release notes are actively maintained against.

Implementation Patterns

Panel-scoped plugin registration. Register the plugin per panel rather than globally. This keeps admin and tenant panels independently configurable and matches how Filament v5 expects plugin state to be resolved:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(YourPackagePlugin::make()
            ->navigationGroup('Settings')
            ->authorizeUsing(fn () => auth()->user()->isAdmin()));
}

Multi-panel and tenancy. If you run more than one panel, decide deliberately whether the package's resources appear in each. Filament v5 tightened tenancy and panel-resolution behaviour, so verify resource scoping against Filament::getTenant() rather than relying on global query scopes alone.

Wrap the package behind your own layer. For anything beyond a trivial install, create a thin local subclass or adapter around the package's resource/page classes. Filament resource classes are large and the package's internals may shift between minor releases; inheriting once in app/Filament/Resources/ gives you a single place to absorb changes and to override getNavigationLabel(), getEloquentQuery(), form schema, and table configuration without forking.

Authorization belongs in policies. Filament resources delegate to Laravel policies. Rather than overriding canViewAny() in the package's class, register policies on the underlying models so both the Filament UI and your non-Filament code paths share one source of truth. This is also the cleanest way to make the package tenant-aware.

Queue long-running work. Filament actions and bulk operations run in the request lifecycle. Any import, sync, or notification the package offers should be pushed onto a queue with a visible progress/notification pattern, otherwise the panel will time out on realistic data volumes.

Test with Filament's own helpers. Use Livewire::test() against the package's page/resource classes and Filament's testing utilities for tables and actions. Cover three things explicitly: that the plugin registers on the panel, that the resource lists records for an authorized user, and that it is hidden from an unauthorized one. That trio catches most integration regressions on upgrade.

Pin and stage upgrades. Because v1.0.2 broadens the supported Filament range rather than changing behaviour, treat Filament major upgrades as a separate, deliberate change. Bump filament/filament and this package together in one PR, run php artisan filament:upgrade (or the v5 equivalent) and re-publish assets, then diff rendered panel output.

Gotchas and Tips

"Support Filament v5" is a compatibility claim, not a migration. A patch-level release that widens a dependency constraint rarely carries breaking changes of its own, but it can pull you across a Filament major boundary. Read the package's constraint as ^1.0.2 with an explicit Filament range, and confirm your lockfile resolves to the versions you expect after composer update.

Plugin not appearing. Nearly always one of: plugin not registered on the panel, panel not the one you're viewing, resource hidden by policy, or cached Filament components. Run php artisan filament:clear-cached-components and php artisan optimize:clear before debugging code.

Stale assets after upgrade. Filament publishes CSS/JS. After any package or Filament bump, re-publish and rebuild: php artisan vendor:publish --tag=filament-assets --force (or filament:assets) followed by your frontend build. Half-broken styling after an upgrade is almost always this.

Config and route caching in production. A config value added in a new release will not appear until php artisan config:clear. If a new option "doesn't work" in staging but works locally, this is the first thing to check. Similarly, route:cache can mask newly registered Filament pages.

Publish-then-migrate ordering. Publish migrations, review them for existing-table collisions, then migrate. On shared or multi-tenant databases, check whether the package's migrations are tenant-scoped or global before running them in production.

Override by extension, not by editing vendor. Everything in vendor/ is ephemeral. Use Filament's documented extension points — resource/page subclassing, ->configureUsing(), form/table component macros, and view overrides published to resources/views/vendor/ — so upgrades stay painless.

Watch the query layer. Filament tables default to Eloquent queries you don't see. If a resource is slow, inspect getEloquentQuery() for missing eager loads and check whether the package applies global scopes. Add ->modifyQueryUsing() in your local subclass rather than patching vendor code.

Debugging integration issues. php artisan about confirms package discovery; php artisan package:discover re-runs it if a provider is missing. For authorisation surprises, Gate::forUser($user)->inspect('viewAny', $model) gives a readable answer faster than clicking around the panel.

Composer conflicts. If the install fails on Filament or Livewire constraints, do not reach for --ignore-platform-reqs or -W blindly — a Filament major mismatch will install and then fail at runtime with confusing container or Livewire errors. Resolve the constraint graph instead, and check whether an older package release targets your Filament version.