PHPackages                             mwguerra/filemanager - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. mwguerra/filemanager

ActiveLibrary[File & Storage](/categories/file-storage)

mwguerra/filemanager
====================

A full-featured file manager package for Laravel and Filament v5 with dual operating modes, drag-and-drop uploads, S3/MinIO support, and comprehensive security features.

v2.1.0(2mo ago)718.5k↑21.7%20[10 issues](https://github.com/mwguerra/filemanager/issues)[4 PRs](https://github.com/mwguerra/filemanager/pulls)1MITPHPPHP ^8.2

Since Dec 1Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/mwguerra/filemanager)[ Packagist](https://packagist.org/packages/mwguerra/filemanager)[ Docs](https://github.com/mwguerra/filemanager)[ RSS](/packages/mwguerra-filemanager/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (12)Versions (14)Used By (1)

MWGuerra FileManager
====================

[](#mwguerra-filemanager)

A full-featured file manager package for Laravel and Filament v5 with dual operating modes, S3/MinIO support, file previews, and drag-and-drop uploads.

Version Compatibility
---------------------

[](#version-compatibility)

VersionFilamentLaravelLivewirePHP2.x5.x12.x4.x8.2+1.x4.x11.x3.x8.2+[![File Manager - List View](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/File%20Manager%20-%20List%20View.png)](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/File%20Manager%20-%20List%20View.png)

Features
--------

[](#features)

- **Dual operating modes**: Database mode (tracked files with metadata) or Storage mode (direct filesystem browsing)
- **File browser**: Grid and list views, folder tree sidebar, breadcrumb navigation
- **File operations**: Upload, move, rename, delete with drag-and-drop support
- **Multi-selection**: Select multiple files with Ctrl/Cmd + click
- **File previews**: Built-in viewers for video, audio, images, PDF, and text files
- **Storage drivers**: Works with local, S3, MinIO, or any Laravel Storage driver
- **Security**: MIME validation, blocked extensions, filename sanitization, signed URLs
- **Authorization**: Configurable permissions with Laravel Policy support
- **Embeddable**: Use as standalone pages or embed in Filament forms
- **Dark mode**: Full dark mode support via Filament

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 12.x
- Filament 5.x
- Livewire 4.x

Installation
------------

[](#installation)

For **Filament 5 / Laravel 12** (latest):

```
composer require mwguerra/filemanager:"^2.0"
```

For **Filament 4 / Laravel 11** (legacy):

```
composer require mwguerra/filemanager:"^1.0"
```

### Upgrading from v1.x to v2.x

[](#upgrading-from-v1x-to-v2x)

v2.x targets Filament 5, Laravel 12, and Livewire 4. Key changes:

- **Filament 5**: Table `->actions()` renamed to `->recordActions()`, `->bulkActions()` renamed to `->toolbarActions()`
- **Livewire 4**: If you published views, replace any `@entangle('...')` directives with `$wire.entangle('...')`
- **Laravel 12**: Minimum Laravel version is now 12.x

Publish configuration:

```
php artisan vendor:publish --tag=filemanager-config
```

Run migrations:

```
php artisan migrate
```

Run the install command:

```
php artisan filemanager:install
```

Register the plugin in your Panel Provider:

```
use MWGuerra\FileManager\FileManagerPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FileManagerPlugin::make(),
        ]);
}
```

Plugin Configuration
--------------------

[](#plugin-configuration)

Register all components or select only the ones you need:

```
use MWGuerra\FileManager\FileManagerPlugin;
use MWGuerra\FileManager\Filament\Pages\FileManager;
use MWGuerra\FileManager\Filament\Pages\FileSystem;
use MWGuerra\FileManager\Filament\Pages\SchemaExample;
use MWGuerra\FileManager\Filament\Resources\FileSystemItemResource;

// Register all enabled components (default)
FileManagerPlugin::make()

// Register only specific components
FileManagerPlugin::make([
    FileManager::class,              // Database mode - full CRUD file manager
    FileSystem::class,               // Storage mode - read-only file browser
    FileSystemItemResource::class,   // Resource for direct database table editing
    SchemaExample::class,            // Demo page showing embed components usage
])

// Using the fluent API
FileManagerPlugin::make()
    ->only([
        FileManager::class,
        FileSystem::class,
    ])
```

ComponentURLDescription`FileManager::class``/admin/file-manager`Database mode with full CRUD operations`FileSystem::class``/admin/file-system`Storage mode for browsing files (read-only)`FileSystemItemResource::class``/admin/file-system-items`Direct database table management`SchemaExample::class``/admin/schema-example`Demo page for embedding components in formsQuick Start
-----------

[](#quick-start)

After installation, access the file manager at:

PageURLDescriptionFile Manager`/admin/file-manager`Database mode with full CRUD operationsFile System`/admin/file-system`Storage mode for browsing files (read-only)### File Manager (Database Mode)

[](#file-manager-database-mode)

Full CRUD file management with metadata tracking, thumbnails, and folder organization.

[![File Manager - Database Mode](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/File%20Manager%20Page%20-%20List%20View.png)](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/File%20Manager%20Page%20-%20List%20View.png)

### File System (Storage Mode: Read-only)

[](#file-system-storage-mode-read-only)

Read-only file browser for direct filesystem access with S3/MinIO support.

[![File System - Storage Mode](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/File%20System%20Page%20%28Storage%20Mode%29.png)](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/File%20System%20Page%20%28Storage%20Mode%29.png)

### FileSystemItems Resource

[](#filesystemitems-resource)

Direct database table management for file system items with Filament's standard resource interface.

[![FileSystemItems Resource Page](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/FileSystemItems%20Resource%20Page.png)](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/FileSystemItems%20Resource%20Page.png)

File Previews
-------------

[](#file-previews)

Built-in viewers for common file types with modal preview support.

### Image Preview

[](#image-preview)

[![Image Preview](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/Schema%20Example%20Page%20-%20Image%20Preview.png)](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/Schema%20Example%20Page%20-%20Image%20Preview.png)

### Video Preview

[](#video-preview)

[![Video Preview](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/Schema%20Example%20Page%20-%20Video%20Preview.png)](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/Schema%20Example%20Page%20-%20Video%20Preview.png)

Embedding in Forms
------------------

[](#embedding-in-forms)

The package provides two embeddable schema components that can be added to any Filament form. Use `FileManagerEmbed` for full CRUD operations with database-tracked files, or `FileSystemEmbed` for a read-only storage browser. Both components are fully customizable with options for height, disk, target directory, and initial folder.

[![File System Embed - Storage Mode](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/File%20System%20%28Storage%20Mode%29%20-%20Minio%20Disk.png)](https://raw.githubusercontent.com/mwguerra/filemanager/main/docs/images/File%20System%20%28Storage%20Mode%29%20-%20Minio%20Disk.png)

```
use MWGuerra\FileManager\Schemas\Components\FileManagerEmbed;
use MWGuerra\FileManager\Schemas\Components\FileSystemEmbed;

// Database mode (full CRUD)
FileManagerEmbed::make()
    ->height('400px')
    ->disk('s3')
    ->target('uploads'),

// Storage mode (read-only browser)
FileSystemEmbed::make()
    ->height('400px')
    ->disk('public')
    ->target('media'),
```

### Embed Component Configuration

[](#embed-component-configuration)

Both embed components support fluent configuration for customizing their appearance:

```
use MWGuerra\FileManager\Schemas\Components\FileManagerEmbed;
use MWGuerra\FileManager\Schemas\Components\FileSystemEmbed;

FileManagerEmbed::make()
    // Layout options
    ->height('500px')
    ->defaultViewMode('grid')  // 'grid' or 'list'

    // Storage options
    ->disk('s3')
    ->target('uploads')
    ->initialFolder('documents')

    // Sidebar configuration
    ->showSidebar()  // or ->hideSidebar()
    ->sidebarRootLabel('My Files')
    ->sidebarHeading('Folders')
    // Or use the combined method:
    ->sidebar(show: true, rootLabel: 'My Files', heading: 'Folders')

    // Breadcrumbs configuration
    ->breadcrumbsRootLabel('Home')

    // Header configuration
    ->showHeader()  // or ->hideHeader()

    // Compact mode (no header, no sidebar)
    ->compact(),

// All options also work with FileSystemEmbed
FileSystemEmbed::make()
    ->height('400px')
    ->disk('public')
    ->sidebarRootLabel('Storage')
    ->breadcrumbsRootLabel('Root')
    ->hideSidebar(),
```

MethodDescription`height(string)`Set component height (default: '500px')`defaultViewMode(string)`Set initial view mode: 'grid' or 'list'`disk(?string)`Storage disk to use`target(?string)`Target directory within the disk`initialFolder(?string)`Initial folder to navigate to on load`showSidebar()` / `hideSidebar()`Show or hide the folder tree sidebar`sidebarRootLabel(string)`Label for root folder in sidebar (default: 'Root')`sidebarHeading(string)`Heading text for sidebar (default: 'Folders')`sidebar(bool, ?string, ?string)`Configure all sidebar options at once`breadcrumbsRootLabel(string)`Label for root in breadcrumbs (default: 'Root')`showHeader()` / `hideHeader()`Show or hide header with controls`compact()`Enable compact mode (no header, no sidebar)All configuration methods support `Closure` values for dynamic configuration:

```
FileManagerEmbed::make()
    ->sidebarRootLabel(fn () => auth()->user()->name . "'s Files")
    ->breadcrumbsRootLabel(fn () => __('file-manager.home')),
```

Fluent Configuration API
------------------------

[](#fluent-configuration-api)

The plugin provides a fluent API for configuring all aspects of the file manager directly in your Panel Provider. This approach is preferred over config file settings as it keeps your panel configuration in one place.

### Panel Sidebar

[](#panel-sidebar)

Add a folder tree sidebar to your Filament panel navigation:

```
use Filament\View\PanelsRenderHook;

FileManagerPlugin::make()
    // Enable panel sidebar (appears in Filament navigation)
    ->panelSidebar()
    ->panelSidebarRootLabel('My Files')
    ->panelSidebarHeading('Folders')

    // Or use the short alias
    ->sidebar()

    // Customize render hook location
    ->panelSidebar(
        enabled: true,
        renderHook: PanelsRenderHook::SIDEBAR_NAV_END,
        scopes: ['admin']
    )

    // Disable panel sidebar
    ->withoutPanelSidebar()
```

### File Manager Page Configuration

[](#file-manager-page-configuration)

Configure the database mode File Manager page:

```
FileManagerPlugin::make()
    // Enable/disable the page
    ->fileManager(true)
    ->withoutFileManager()  // Disable

    // Configure page sidebar (folder tree on the page itself)
    ->fileManagerPageSidebar(true)
    ->fileManagerSidebarRootLabel('Root')
    ->fileManagerSidebarHeading('Folders')

    // Configure navigation
    ->fileManagerNavigation(
        icon: 'heroicon-o-folder',
        label: 'File Manager',
        sort: 1,
        group: 'Content'
    )
```

### File System Page Configuration

[](#file-system-page-configuration)

Configure the storage mode File System page (read-only):

```
FileManagerPlugin::make()
    // Enable/disable the page
    ->fileSystem(true)
    ->withoutFileSystem()  // Disable

    // Configure page sidebar
    ->fileSystemPageSidebar(true)
    ->fileSystemSidebarRootLabel('Root')
    ->fileSystemSidebarHeading('Storage')

    // Configure navigation
    ->fileSystemNavigation(
        icon: 'heroicon-o-server-stack',
        label: 'File System',
        sort: 2,
        group: 'Content'
    )
```

### Schema Example Page

[](#schema-example-page)

Enable/disable the demo page for testing embedded components:

```
FileManagerPlugin::make()
    ->schemaExample(true)
    ->withoutSchemaExample()  // Disable
```

### Complete Configuration Example

[](#complete-configuration-example)

```
use MWGuerra\FileManager\FileManagerPlugin;
use Filament\View\PanelsRenderHook;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FileManagerPlugin::make()
                // Panel sidebar (in Filament navigation)
                ->panelSidebar()
                ->panelSidebarRootLabel('All Files')
                ->panelSidebarHeading('Folders')

                // File Manager page (database mode)
                ->fileManager()
                ->fileManagerPageSidebar(true)
                ->fileManagerSidebarRootLabel('Root')
                ->fileManagerSidebarHeading('Folders')
                ->fileManagerNavigation(
                    icon: 'heroicon-o-folder',
                    label: 'Files',
                    sort: 1,
                    group: 'Content'
                )

                // File System page (storage mode, read-only)
                ->fileSystem()
                ->fileSystemPageSidebar(true)
                ->fileSystemSidebarRootLabel('Storage Root')
                ->fileSystemSidebarHeading('Directories')
                ->fileSystemNavigation(
                    icon: 'heroicon-o-server-stack',
                    label: 'Storage',
                    sort: 2,
                    group: 'Content'
                )

                // Disable demo page
                ->withoutSchemaExample(),
        ]);
}
```

### Configuration Precedence

[](#configuration-precedence)

Configuration values follow this precedence (highest to lowest):

1. **Fluent API** - Values set via the plugin methods
2. **Config file** - Values from `config/filemanager.php`
3. **Defaults** - Built-in default values

For sidebar labels, page-specific settings fall back to panel sidebar settings:

```
FileManagerPlugin::make()
    ->panelSidebarRootLabel('Root')  // Default for all sidebars
    ->fileManagerSidebarRootLabel('Files Root')  // Override for File Manager only
```

### Icon Customization

[](#icon-customization)

The file manager uses heroicons by default, but includes fallback SVGs that work without the `blade-icons/blade-heroicons` package. You can customize icons through the plugin configuration.

**Override specific icons:**

```
use MWGuerra\FileManager\FileManagerPlugin;
use MWGuerra\FileManager\Enums\FileManagerIcon;

FileManagerPlugin::make()
    // Override multiple icons at once
    ->icons([
        'folder' => 'phosphor-folder',  // Use a different icon set
        'document' => '...',  // Raw SVG
    ])

    // Or override a single icon
    ->icon(FileManagerIcon::Folder, 'tabler-folder')
    ->icon('trash', 'heroicon-s-trash')  // String keys also work
```

**Disable all icons:**

```
FileManagerPlugin::make()
    ->noIcons()  // Icons will not render (returns empty string)
```

**Re-enable icons:**

```
FileManagerPlugin::make()
    ->withIcons()  // Explicitly enable (default)
```

**Available icons:**

IconDefaultDescription`folder``heroicon-o-folder`Folder icon`folder-open``heroicon-o-folder-open`Open folder icon`folder-plus``heroicon-m-folder-plus`Add folder icon`document``heroicon-o-document`Generic file icon`document-text``heroicon-o-document-text`Text file icon`chevron-right``heroicon-m-chevron-right`Expand chevron`chevron-down``heroicon-m-chevron-down`Collapse chevron`musical-note``heroicon-o-musical-note`Audio file icon`video-camera``heroicon-o-video-camera`Video file icon`photo``heroicon-o-photo`Image file icon`trash``heroicon-o-trash`Delete action`pencil``heroicon-m-pencil`Edit action`cloud-arrow-up``heroicon-o-cloud-arrow-up`Upload icon`arrow-down-tray``heroicon-o-arrow-down-tray`Download iconAll icons have bundled SVG fallbacks, so the file manager works even without `blade-icons` installed.

**Using icons in your own code:**

```
use MWGuerra\FileManager\Enums\FileManagerIcon;

// In Blade templates
{!! FileManagerIcon::Folder->render('w-5 h-5 text-primary-500') !!}

// Using the helper function
{!! fmicon('folder', 'w-5 h-5') !!}
{!! fmicon(FileManagerIcon::Document, 'w-4 h-4 text-gray-500') !!}
```

Artisan Commands
----------------

[](#artisan-commands)

### filemanager:install

[](#filemanagerinstall)

Install FileManager with all required assets and configuration:

```
php artisan filemanager:install [options]
```

OptionDescription`--skip-assets`Skip publishing Filament assets`--skip-config`Skip publishing configuration`--skip-migrations`Skip running migrations`--with-css`Also configure your app.css for style customization`--css-path=`Path to CSS file (default: resources/css/app.css)`--force`Overwrite existing configurations**Note:** The `--with-css` option is only needed if you want to customize FileManager styles in your project's CSS. The plugin includes pre-compiled CSS with all necessary Tailwind classes.

### filesystem:list

[](#filesystemlist)

List files directly from a storage disk (recursive by default):

```
php artisan filesystem:list [path] [options]
```

OptionDescription`path`Folder path to list (default: root)`--disk=`Storage disk (default: from config/env)`--type=`Filter: `folder`, `file`, or `all``--no-recursive`Disable recursive listing`--format=`Output: `table`, `json`, or `csv``--show-hidden`Include hidden files (starting with .)### filemanager:list

[](#filemanagerlist)

List files with database or storage mode support:

```
php artisan filemanager:list [path] [options]
```

OptionDescription`path`Folder path or ID to list (default: root)`--disk=`Storage disk (default: from config/env)`--mode=`Mode: `database` or `storage` (default: database)`--target=`Target directory within disk`--type=`Filter: `folder`, `file`, or `all``--recursive`Enable recursive listing`--format=`Output: `table`, `json`, or `csv``--show-hidden`Include hidden files### filemanager:rebuild

[](#filemanagerrebuild)

Rebuild database from filesystem (clears existing records):

```
php artisan filemanager:rebuild [options]
```

OptionDescription`--disk=`Storage disk to scan (default: from config/env)`--root=`Root directory to scan`--force`Skip confirmation prompt### filemanager:upload

[](#filemanagerupload)

Upload a local folder to storage:

```
php artisan filemanager:upload  [options]
```

OptionDescription`path`Local folder path to upload (required)`--disk=`Target storage disk (default: from config/env)`--target=`Target directory within disk`--no-database`Skip creating database records`--force`Skip confirmation promptPublishable Assets
------------------

[](#publishable-assets)

TagDescription`filemanager-config`Configuration file`filemanager-migrations`Database migrations`filemanager-views`Blade view templates`filemanager-model`Customizable model`filemanager-stubs`Config stubs (filesystems, env)`filemanager-upload-config`Upload configurationIssues and Contributing
-----------------------

[](#issues-and-contributing)

Found a bug or have a feature request? Please open an issue on [GitHub Issues](https://github.com/mwguerra/filemanager/issues).

We welcome contributions! Please read our [Contributing Guide](https://github.com/mwguerra/filemanager/blob/main/CONTRIBUTING.md) before submitting a pull request.

License
-------

[](#license)

File Manager is open-sourced software licensed under the [MIT License](https://github.com/mwguerra/filemanager/blob/main/LICENSE).

Author
------

[](#author)

### **Marcelo W. Guerra**

[](#marcelo-w-guerra)

- Website: [mwguerra.com](https://mwguerra.com/)
- Github: [mwguerra](https://github.com/mwguerra/)
- Linkedin: [marcelowguerra](https://www.linkedin.com/in/marcelowguerra/)

Contributors
------------

[](#contributors)

- [Claudio Pereira](https://github.com/cpereiraweb)
- [Fernando dos Santos Souza](https://github.com/nandinhos)

###  Health Score

53

—

FairBetter than 97% of packages

Maintenance87

Actively maintained with recent releases

Popularity42

Moderate usage in the ecosystem

Community14

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~9 days

Recently: every ~25 days

Total

13

Last Release

61d ago

Major Versions

v0.1.8 → 1.x-dev2026-01-24

v1.0.0 → v2.0.02026-02-26

### Community

Maintainers

![](https://www.gravatar.com/avatar/e5272bc4d88e75a3a196a9b1e4bcfe8e7287045a62e3f1aa995bf94950d2ac2d?d=identicon)[MWGuerra](/maintainers/MWGuerra)

---

Top Contributors

[![mwguerra](https://avatars.githubusercontent.com/u/27717982?v=4)](https://github.com/mwguerra "mwguerra (44 commits)")

---

Tags

laravels3storageuploadfile managermedia libraryfilamentminio

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/mwguerra-filemanager/health.svg)

```
[![Health](https://phpackages.com/badges/mwguerra-filemanager/health.svg)](https://phpackages.com/packages/mwguerra-filemanager)
```

###  Alternatives

[guava/filament-modal-relation-managers

Allows you to embed relation managers inside filament modals.

7565.0k4](/packages/guava-filament-modal-relation-managers)[tapp/filament-webhook-client

Add a Filament resource and a policy for Spatie Webhook client

1120.2k](/packages/tapp-filament-webhook-client)[webplusm/gallery-json-media

a filament media storing in a Json field

196.0k](/packages/webplusm-gallery-json-media)[a2insights/filament-saas

Filament Saas for A2Insights

161.1k](/packages/a2insights-filament-saas)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)