Filament Gallery Laravel Package

Getting Started

1. Install the package with Composer:

   composer require cwsps154/my-gallery
   

2. Run the installer — this is the step that sets up everything the gallery needs (migrations, assets, and defaults):

   php artisan my-gallery:install
   

   Follow it with php artisan migrate if the command doesn't run migrations itself.
3. Register the plugin in your Filament PanelProvider::panel():

   use CWSPS154\MyGallery\MyGalleryPlugin;
   
   $panel->plugins([MyGalleryPlugin::make()]);
   

4. Optional: publish the config if you need to override the settings page class:

   php artisan vendor:publish --tag=my-gallery-config
   

Where to look first: the plugin registration in your PanelProvider is the single entry point — it controls both resource visibility and authorization. Start there, then check the published config/my-gallery.php for the settings-page class binding.

First use case: drop MyGalleryPlugin::make() into a panel and you immediately get a gallery resource with list/create/edit screens wired into Filament's navigation. Verify the four screenshots' flows (list, two-step create) work end-to-end on a staging panel before adding access rules.

Implementation Patterns

Closure-based authorization (default path). Use the fluent can* methods with closures when you want bespoke rules that don't depend on a permissions package:

MyGalleryPlugin::make()
    ->canViewAny(fn () => auth()->user()?->isStaff() ?? false)
    ->canCreate(fn () => auth()->user()?->hasQuota() ?? false)
    ->canEdit(fn (Gallery $gallery) => $gallery->owner_id === auth()->id())
    ->canDelete(fn () => auth()->user()?->isAdmin() ?? false);

Always return a real boolean rather than the true placeholders in the docs — the examples hardcode true, which is effectively "everyone can do everything."

Permission-string authorization (with cwsps154/filament-users-roles-permissions). When that plugin is installed, swap each closure for (method, permission) arguments:

MyGalleryPlugin::make()
    ->canViewAny('have-access', 'view-gallery')
    ->canCreate('have-access', 'create-gallery')
    ->canEdit('have-access', 'edit-gallery')
    ->canDelete('have-access', 'delete-gallery');

Pair this with seeding the four permission names (view-gallery, create-gallery, edit-gallery, delete-gallery) in your roles/permissions seeder so they're assignable to roles.

Panel-scoped configuration. The plugin is registered per panel, so multi-panel apps can grant gallery access only to an admin panel while leaving the customer-facing panel clean:

// AdminPanelProvider
$panel->plugins([MyGalleryPlugin::make()->canDelete(fn () => true)]);

// StaffPanelProvider
$panel->plugins([MyGalleryPlugin::make()->canDelete(fn () => false)]);

Settings page integration. The published config exposes settings-page, which defaults to \CWSPS154\AppSettings\Page\AppSettings::class. If you're already using the AppSettings package, leave it as-is so gallery configuration surfaces there; if you don't use it, override the key with your own Filament page class (or remove the binding) — otherwise the reference may dangle.

Feature-by-feature rollout. Because each can* is independent, stage authorization gradually: enable canViewAny first, then canCreate, then canEdit/canDelete. This lets you validate the gallery UX before locking it down.

Gotchas and Tips

• The documentation examples return true unconditionally. Treat every can* snippet as a placeholder — ship real logic, or the gallery is wide open to any authenticated panel user.
• Two authorization modes are mutually exclusive per call. canViewAny('have-access', 'view-gallery') requires the cwsps154/filament-users-roles-permissions plugin. If it isn't installed, don't pass strings — the check won't resolve. Use closures instead.
• Config cache. After publishing my-gallery.php or changing settings-page, run php artisan config:clear (and config:cache in production) or your old binding persists.
• settings-page cross-package dependency. The default value points at an AppSettings page class. If you don't have cwsps154/app-settings installed, verify the class resolves — a missing class here surfaces as an obscure container error, not a friendly message.
• Install command isn't idempotent by contract. If my-gallery:install publishes migrations or files, re-running it can overwrite your changes. Commit after the first run and prefer vendor:publish --tag=my-gallery-config --force only when you intend to reset the config.
• Debugging permission denials. When a user "can't see the gallery," check in this order: (1) plugin registered on that panel, (2) the relevant can* method called with correct args, (3) permission string seeded and assigned to the role, (4) config cache cleared.
• Filament version compatibility. The $panel->plugins([...]) API is Filament v3+. If you're on v2, the registration and Plugin contract differ — pin compatible versions in composer.json.
• canEdit/canDelete scope. If your closures depend on the record (e.g., ownership), ensure the same rule applies to bulk actions — a closure that only checks the authenticated user will allow mass actions across records the user shouldn't touch.
• Extension points. The plugin's fluent can* setters and the settings-page config key are the two documented hooks. For anything deeper (custom fields on gallery items), expect to extend the underlying resource rather than the plugin — check the package's resource classes for overridable methods.