Filament Resource Customizer Laravel Package

Getting Started

Before you install, check three things. This package is small (3 stars), MIT-licensed, and thinly documented — the README/release notes tell you what it does, not how. Budget a 1–2 hour spike where you read src/ before you write any application code against it.

1. Confirm the Filament major version it targets. The release metadata only pins PHP (8.3–8.5) and Laravel (12–13). Filament v3 vs v4 schema APIs differ (Forms\Form, Schemas\Schema, ->schema() vs ->form()), so open composer.json and check the filament/filament constraint first. This is the single most likely reason the package won't fit your app.
2. Install on a disposable Laravel 12 / PHP 8.4 app, not in your main repo:

   composer require rolland97/filament-resource-customizer
   php artisan vendor:publish --provider="Rolland97\FilamentResourceCustomizer\...ServiceProvider"
   

   Package discovery should register the provider automatically; if vendor:publish reports nothing, the provider name is wrong — run php artisan about or grep bootstrap/cache/packages.php to get the real FQCN.
3. Find the entry points. Two things to locate immediately:
   • src/ — the base customizer class/contract you extend, and any registry the panel uses to discover customizers.
   • src/Console/ — the permissions generator command. Run php artisan list | grep -i -E 'permission|customiz' to get its exact signature.

First use case: the permissions generator, on one resource. Pick a resource you already have (e.g. UserResource). Run the generator for it, read the output diff, and check whether the generated permission names match what your policies/can() calls expect. Do not run it panel-wide on the first attempt — the blast radius of a bulk permission generator is every policy in the app.

Second use case: extract one customization. Take a single messy method out of a resource (a ->modifyQueryUsing(), a table action, a form section) and move it into a customizer. If that feels natural, the package fits; if you're fighting indirection for a one-line change, keep the code in the resource and only use the permissions half.

Implementation Patterns

One customizer per resource, registered explicitly. The whole value proposition is pulling form/table/behavior tweaks out of resource classes. Keep that contract strict:

app/Filament/Customizers/
  UserResourceCustomizer.php
  OrderResourceCustomizer.php

Each customizer should do one of three things — adjust the form schema, adjust the table schema, or adjust query/behavior. If a customizer starts containing business logic or authorization, stop; that belongs in a service or a policy.

Prefer composition over deep inheritance. If the package ships a base customizer, extend it once with your own AppCustomizer (house helpers, shared field factories, tenant scoping), then extend that from every resource customizer. When the package cuts a minor release, you patch one file instead of twelve.

Reuse patterns across resources, not code by copy-paste. The description explicitly calls out "reuse customization patterns." Concretely: a HasAuditColumns trait or a small CommonFields::timestampsAndAuthor() helper that each customizer calls. This is where the package earns its keep on a panel with 20+ resources — the resource classes stay near-stock Filament, so upstream Filament upgrades and code generation don't collide with your tweaks.

Permissions generator workflow. Treat generated output as source you own, not as build artifacts:

1. Run the generator against one resource.
2. Review the naming convention before committing — view_any_user vs viewAny User vs users.view matters enormously for consistency with existing policies.
3. Seed/refresh your permission table, then clear the permission cache (Spatie or otherwise) — stale cache is the #1 "it generated but doesn't work" cause.
4. Wire generated permissions into Filament's authorization: canViewAny(), canCreate(), etc., or your policy layer.
5. Only then run it across the whole panel, and commit the diff so reviewers can see every permission that appeared.

Make the generator idempotent in your workflow: run it on every new resource as a checklist step, and keep a git diff review gate so renames don't silently orphan permissions.

Config-gate the package. Put the registration behind config/env so you can disable it in one place:

// config/filament-resource-customizer.php (or your panel provider)
'enabled' => env('FILAMENT_RESOURCE_CUSTOMIZER', true),

This gives you a feature-flag rollback that doesn't require a revert commit — important when a customization layer sits in the admin request path.

Test the customizer output, not the package. In a Filament test:

it('applies tenant scoping in the order customizer', function () {
    $this->actingAs($tenantUser);
    livewire(ListOrders::class)
        ->assertCanSeeTableRecords($tenantUser->orders)
        ->assertCanNotSeeTableRecords(Order::factory()->for($otherTenant)->createMany(2));
});

If the customizer breaks, your test tells you which behavior broke. The package's own CI (PHP 8.3–8.5, Laravel 12–13, Linux + Windows) tells you nothing about your schemas.

Gotchas and Tips

Documentation is the biggest risk, not the code. There is no published usage guide in the sources provided — the release notes are CI-only and the description is marketing-level. Everything you need is in src/, and it's small enough to read in under an hour. Do that before you build 15 customizers on top of guessed API names.

Version-pin harder than usual. "rolland97/filament-resource-customizer": "^2.1" is fine, but with 3 stars and a single apparent maintainer, a minor release can change shape with no downstream warning. Commit composer.lock, and read the diff of any 2.x bump that touches src/ before merging.

The permissions generator is the sharp edge. Generated permissions and generated code are different animals:

• Generated files may be overwritten on re-run. Check whether the command writes stubs or patches existing files — if it overwrites, move generated output into your own namespace immediately and never re-run blindly.
• Permission names are effectively a public API once seeded in production. Rename them early or not at all.
• Verify which permission backend it assumes (Spatie laravel-permission? Filament Shield? raw gates?). Running it against the wrong backend produces permissions nothing reads.
• Always bust the permission cache after generation, and again after any role assignment batch.

Customizer ordering and precedence. If both a resource and a customizer touch the same form field, the winner depends on the package's registration order. When a field "won't change," add a temporary dd($schema) (or ray()) at the end of the customizer's method to confirm it actually runs. Silent non-execution — customizer not discovered, provider not registered, config disabled — is the most common failure and looks identical to "my override has no effect."

Watch for Laravel 13. It appears in the CI matrix, but that doesn't mean it's stable or that your other packages support it. Stay on Laravel 12 + PHP 8.4 for evaluation; treat the 8.5/13 rows as a forward-compatibility signal only.

Windows CI is a weak signal. It's nice that it passes, but unless you deploy or develop on Windows, it tells you nothing about your runtime. Don't factor it into the decision.

Extension points to check before forking. In rough order of preference: publishable config → publishable stubs → a base class you can subclass → service container binding. If the package offers none of these and you need behavior it doesn't support, fork it under MIT — it's small, and a vendored fork in packages/ with a path repository is lower risk than monkey-patching a 3-star dependency in vendor/.

Keep a fallback plan on paper. The "customization layer" pattern is ~200 lines of your own code if the package disappears: a ResourceCustomizer interface, a registry keyed by resource class, and calls from form()/table(). Write down that migration in your integration note so package abandonment is a known, bounded cost rather than an incident.