Filament File Manager Laravel Package

Getting Started

This is a Filament panel plugin for browsing and managing files/folders on Laravel storage disks. It is a pre-1.0 package (v0.8.3), so treat the public API as unstable and pin an exact version in composer.json rather than using a floating constraint.

Minimal steps:

1. Install into an existing Filament panel app:

   composer require unifilemanager/filament-file-manager
   

   Match the major version of filament/filament you already run — the plugin's own v0.8.x line tracks Filament v3/v4; check the README matrix before upgrading Filament.

2. Register the plugin on the panel you want the manager to appear in, in your PanelProvider:

   ->plugin(UniFileManager\FilamentFileManager\FilamentFileManagerPlugin::make())
   

3. Publish and read the config file first — it is the primary surface area of this package:

   php artisan vendor:publish --tag="filament-file-manager-config"
   

   The config drives which disks are exposed, the storage area labels and icons (new in v0.8.x), upload rules and navigation registration.

4. Run php artisan storage:link and confirm the disk you configured (config('filesystems.disks.public') or a custom disk) is actually writable by the web user.

First use case: drop the plugin into an admin panel as a lightweight media library — let editors upload assets into named "storage areas" and reuse them across resources, instead of bolting a custom FileUpload + SpatieMediaLibrary setup onto every resource.

Where to look first, in order: the published config file → the plugin class for navigation/authorization hooks → the GitHub issues list (#27 and #28 were both driven by user feedback, so the issue tracker is the de-facto changelog for behaviour decisions).

Implementation Patterns

Config over code. Almost everything day-to-day is configuration, not extension. Prefer adding a storage area in config over writing a custom page:

// config/filament-file-manager.php (shape is indicative — verify against your installed version)
'storage_areas' => [
    'public' => [
        'disk'      => 'public',
        'label'     => 'Website assets',   // v0.8.x
        'icon'      => 'heroicon-o-photo', // v0.8.x
    ],
    'private' => [
        'disk'      => 'local',
        'label'     => 'Internal documents',
        'icon'      => 'heroicon-o-lock-closed',
    ],
],

Since v0.8.0 you can label and icon each area, which is the cheapest way to stop editors from uploading marketing images into the folder holding signed contracts. Use it deliberately: one area per audience, not one per disk.

Multi-disk as the primary isolation mechanism. Give each tenant/department its own disk (or disk root) rather than relying on folder-level permissions inside a shared area. Storage::disk() semantics, path prefixes and visibility all come along for free, and it composes with per-tenant filesystem config.

Gate access with policies / panel authorization. The plugin registers panel pages; restrict them through Filament's usual mechanisms (canAccessPanel, role/permission checks) rather than hiding the nav item only. A hidden page is still routable.

Bulk operations are now safer by default. v0.8.3 adds two selection/deletion behaviours worth designing around:

• Improved "select page" vs "select all" semantics in the listing (#29). If you have custom bulk actions, verify they respect the current selection mode rather than assuming selectedRecords on the current page only.
• Safe folder deletion confirmations (#30). Folder deletes now prompt before destroying a tree. Do not disable this for non-technical users; instead, if you need programmatic/bulk cleanup, do it in an artisan command against the disk directly, outside the UI.

Pair with FileUpload / RichEditor. The common integration is: editors manage a shared asset library here, then Filament form components point at the same disk + path so the files they picked are reachable. Keep the disk name in a single config constant and reference it from both the plugin config and your form components — hardcoding 'public' in two places is the usual source of "the image 404s in production" bugs.

Rollout pattern for the pre-1.0 line. Because behaviour around selection and deletion changed inside a patch-level range (v0.8.0 → v0.8.3), treat each bump as potentially UI-affecting: install on staging, exercise upload / rename / move / bulk-delete / folder-delete, then promote. Pin with "unifilemanager/filament-file-manager": "0.8.3" and bump intentionally.

Gotchas and Tips

• Pre-1.0 churn is the biggest risk. Folder deletion and selection semantics both changed between v0.8.0 and v0.8.3. Any test suite or user documentation describing "delete removes it immediately" is now wrong. Budget for a UI walkthrough after every bump, not just after minor versions.
• Confirmations are new, so old habits are stale. Support tickets of the form "delete no longer works" after this release are almost certainly users not noticing the new confirm dialog (#30). Update internal docs and screenshots.
• Selection mode confusion. The page-vs-all improvement (#29) means a bulk action can now legitimately receive a much larger set than what's visible. Anything that fans out to per-file remote calls (S3, CDN purge, thumbnail regeneration) needs chunking and a queue — do not run it synchronously in the Livewire request.
• Disk misconfiguration looks like a package bug. Symptom: uploads appear to succeed, files are invisible or 404. Causes, in order of likelihood: no storage:link, disk visibility not public, APP_URL wrong behind a proxy, or the web user lacking write permission. Check Storage::disk($name)->put() from php artisan tinker before filing an issue.
• Path handling. Folder names with spaces, unicode or leading dots trip up naive path joins. Test with 2024 Q1 / Rapports, not test. Also confirm your disk root is not the app root — a misconfigured local disk can expose .env in the browser.
• Icons must be registered Filament icons. The new per-area icons (#26) resolve through Filament's icon system; a typo yields a silent blank rather than an error. Use the exact heroicon-o-* / heroicon-s-* names and eyeball the nav after changing them.
• Caching. Config and nav changes usually need php artisan config:clear and php artisan filament:cache-components (or optimize:clear) before they show up. Many "the icon/label didn't change" reports are stale caches.
• Extension points are thin — expect to override, not extend. At 0.8.x the safest customisation route is config first, then a subclassed page/resource registered on the panel, then a fork. Avoid patching vendor files; you will be upgrading often at this cadence.
• Debugging tip: the fastest triage split is "does the file exist on disk?" If yes, the problem is rendering/permissions in the plugin; if no, it's upload config or the disk. That single check resolves most reports before you read any source.