Download the PHP package unifilemanager/filament-file-manager without Composer

UniFileManager

File management for Laravel Filament.

UniFileManager adds a full file-library experience to Filament. It includes a File Manager page for working with files and folders, plus UniFilePicker for selecting files from Filament forms. Files always remain within configured storage-area roots, whether you use private application files or public website media.

Contents

• Version compatibility
• Features
• Requirements
• Installation
• Quick start
• Storage areas
• S3, R2, and MinIO
• UniFilePicker
• Spatie Media Library collections
• Uploads, previews, and thumbnails
• Configuration
• Translations
• Styling and assets
• Access control and storage
• Screenshots
• Development

Version compatibility

The GitHub Actions workflow verifies every Laravel and Filament combination in this table.

Features

• File Manager page — browse folders, upload files, move or rename items, download files, and delete one or many selected items.
• UniFilePicker — choose one or many files from a focused library modal or upload them directly from a Filament form.
• Private and public media — keep application files and public website media in separate, server-defined storage areas.
• File previews — view images, PDFs, and text files. Image previews include useful file properties and public files can expose a copyable URL.
• Image thumbnails — create lightweight thumbnails for supported images, with a generic fallback when a thumbnail is unavailable.
• Organised browsing — breadcrumbs, search, sorting, optional folders-first layout, and pagination for large libraries.
• Field-level limits — restrict picker MIME types, target a directory, set file limits, and choose compact or image-card multiple-file views.
• Media-library collections — optionally sync picker selections into Spatie Media Library collections without deleting the underlying file-manager objects.
• Theme-aware UI — controls inherit the active Filament panel primary colour without requiring a custom theme or Node build.

Requirements

• PHP 8.2 or later
• Laravel 11, 12, or 13
• Filament 4 or 5
• Livewire 3 or 4
• PHP GD is optional, but required for generated image thumbnails

Installation

Install the package and publish its configuration:

When updating from an older version, allow Composer to update related package dependencies as well:

Register the plugin in your Filament panel provider:

You may customize the File Manager navigation item from the plugin:

For deeper page customization, register your own page class that extends the package File Manager page:

Publish the package's registered Filament assets after installing or updating:

Quick start

The File Manager uses Laravel's manageFileManager ability by default. Define that ability in your application, for example in AppServiceProvider::boot():

Replace the example condition with your own permission system. If your user model does not have an is_admin attribute, use an existing role or permission check instead. Users granted the ability can open the File Manager page from your Filament navigation.

For tenant-specific access, implement the core FileManagerAuthorizer and a request-aware StorageAreaResolver. See the multi-tenancy guide for a working pattern.

Storage areas

UniFileManager uses named storage areas. The browser can choose an enabled area, but never supplies its disk, root, or visibility settings.

Private storage is enabled by default. Enable public media only when you have a public disk or CDN configured deliberately:

S3-compatible disks work through Laravel's filesystem configuration. See the S3, R2, and MinIO guide for production examples.

When more than one area is enabled, File Manager displays a storage-area switcher. The user's last selection is remembered for their current session. Items from different areas are never mixed in one directory listing.

For multi-tenant applications, replace the static storage-area configuration with a trusted request-aware resolver. Do not derive a disk or root from browser input. See the multi-tenancy guide.

Private files and public media

Use the private area for documents, invoices, and customer uploads. Use the public area for assets that visitors may access directly, such as course images or blog thumbnails.

File Manager administration still requires permission in either area. A public asset URL, however, does not require access to the File Manager page.

S3, R2, and MinIO

UniFileManager supports private and public storage areas on Laravel disks backed by Amazon S3, Cloudflare R2, MinIO, or another S3-compatible service. Configure the disk in config/filesystems.php, then point a storage area at that server defined disk and root. Do not accept disk, bucket, endpoint, or root values from the browser.

Read the full S3-compatible storage guide for environment examples, private/public area configuration, MinIO endpoint notes, and integration-test coverage.

UniFilePicker

UniFilePicker stores relative paths below the selected storage-area root. It is the preferred form component; FilePicker remains available as a backward-compatible alias.

Single-file fields

After a file is selected, the drop area becomes a responsive file card. Hover the card to remove the selection. Use Filament's normal ->helperText(...) method to add guidance beneath the drop area.

Change the placement-box copy when the default wording does not suit the field:

Multiple-file fields

Multiple fields use a compact list with small thumbnails by default. Use larger cards for image galleries:

The upload area remains visible while there is room for another file. It hides at the configured limit and returns when a file is removed. Multiple selections can be cleared together with the Clear selection action.

File type, directory, and duplicate rules

By default, a picker accepts JPEG, PNG, WebP, GIF, PDF, plain text, DOC, and DOCX files. Use allowedMimeTypes() to narrow the types accepted by one field:

The directory applies to browsing, uploads, file selection, and parent-folder navigation. It must be below the selected storage-area root. Stored values remain relative to that root, for example courses/thumbnails/cover.jpg.

Duplicate selections are blocked by default. Enable them only where the same library file may be intentionally selected more than once:

Each duplicate counts toward maxFiles() and can be removed independently.

Library behaviour

The embedded file library is enabled by default. It provides folder navigation, search, sorting, item-layout controls, pagination, previews, and automatic uploads. It deliberately omits File Manager administration actions such as renaming and deletion.

Disable the library for a field with ->library(false), or disable it for every field with file_picker_library in the package configuration.

If only one storage area is enabled, the picker uses it automatically. When both areas are enabled, configure file_picker_default_area or choose the intended area explicitly with ->privateMedia(), ->publicMedia(), or ->storageArea('area-name') for a custom server-defined storage area.

Spatie Media Library collections

UniFilePicker can sync selected files into a spatie/laravel-medialibrary collection instead of dehydrating a path into a model column:

The model must implement Spatie's HasMedia contract. The field stores media rows that point at files already managed by UniFileManager, so removing a selection unlinks the media row and does not delete the underlying file.

Install spatie/laravel-medialibrary before calling collection(). When your storage area uses a root prefix, configure your media-library path generator to honour the external_dir custom property written by this field; otherwise Spatie will resolve those media rows to its default id-based paths instead of the existing file-manager objects.

Uploads, previews, and thumbnails

Uploaded files keep their safe client filename. Existing files are never overwritten: a collision becomes filename (2).ext, then filename (3).ext. Normal filename characters such as spaces, Unicode, +, parentheses, underscores, and hyphens are retained. Cross-platform-unsafe characters are normalised during upload.

Files selected through File Manager or UniFilePicker upload immediately. Set the package-wide upload count with max_upload_files (default: 10). The package also respects PHP's max_file_uploads limit.

Image, PDF, and plain-text previews are available through the package preview route. Image previews show the file type, size, modified date, and relative path. Public-media images also include a copyable public URL.

Image thumbnails are generated with PHP GD and stored in an internal .thumbnails directory. If GD is unavailable, or an image exceeds thumbnails.max_source_pixels (default: 8,000,000), the package uses a lightweight generic image tile instead. Thumbnail generation is synchronous and does not need Laravel queue configuration.

Configuration

Publish the config file first, then change only the values your application needs:

The File Manager and File Picker Explorer show all items together by default. Set show_item_layout to true when users should be able to choose Folders first. Their choice is remembered for the current session.

file_picker_manager_url is retained only for legacy integrations. It is null by default because panel URLs vary by application. A field can override it with ->managerUrl('/custom-file-manager'); this does not open a new tab.

Translations

UniFileManager uses Laravel's namespaced translations for File Manager and UniFilePicker labels, dialogs, upload feedback, and notifications. English is included by default. Publish the file before adding another locale:

For example, add French translations in lang/vendor/filament-file-manager/fr/file-manager.php. Laravel selects the package strings using your application's active locale.

Styling and assets

The package ships with its own scoped stylesheet. It does not require a custom Filament theme, Tailwind configuration, or Node.js build in the consuming application. Buttons, links, focus states, upload states, pagination, and picker selection indicators inherit the active panel primary colour.

Run this command during deployment after installing or updating the package:

The stylesheet is loaded in Filament's document head to avoid an unstyled flash when opening File Manager.

Access control and storage

• The default area uses Laravel's private local disk. It refuses the standard public disk and local roots below public/ or storage/app/public when an area is configured as private.
• S3-compatible private areas are supported when the Laravel disk is private and the storage-area root is server-defined. Public S3-compatible areas should use a dedicated public bucket/prefix or CDN URL. See the S3-compatible storage guide.
• Replace the default manageFileManager check with application-specific core FileManagerAuthorizer and StorageAreaResolver classes when access depends on tenants or paths. Read the multi-tenancy guide before enabling the package in a tenant application.
• Keep the package MIME and extension lists narrow for your use case. The picker can apply a narrower list with allowedMimeTypes().
• The configured root cannot be renamed, moved, or deleted. A folder cannot be moved into itself or one of its descendants.
• Preview and thumbnail responses require authentication, are rate-limited per user or guest IP address, and send private no-store and nosniff headers.
• Add malware scanning in your application before making new uploads available to other users.

If you are upgrading from an earlier public-disk configuration, follow the upgrade notes before deployment.

Screenshots

Development

Run the formatting check and package tests before opening a pull request:

Use composer format to apply the package's PSR-12 formatting rules.

Project documents

• Changelog
• Upgrade notes
• Multi-tenancy guide
• S3-compatible storage guide
• Spatie Media Library guide
• Release policy
• MIT License

Maintainer

UniFileManager is maintained by Sampath Arachchige.