Filament File Manager Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mmes-design/filament-file-manager
   

   Register the plugin in your PanelServiceProvider:

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

2. Publish Config

   php artisan vendor:publish --provider="MmesDesign\FilamentFileManager\FilamentFileManagerServiceProvider"
   

   Configure storage paths, permissions, and allowed extensions in config/filament-file-manager.php.

3. First Use Case Access the file manager via /admin/file-manager (default route). Upload a test file (e.g., test.txt) to verify basic functionality.

Implementation Patterns

Core Workflows

1. File Uploads in Forms Use the FilePicker component in Filament resources:

   use MmesDesign\FilamentFileManager\Forms\Components\FilePicker;
   
   FilePicker::make('image')
       ->directory('images')
       ->multiple()
       ->required(),
   

2. Rich Editor Integration Embed files directly in RichEditor or MarkdownEditor:

   RichEditor::make('content')
       ->fileManagerEnabled()
       ->toolbarButtons([
           // Include 'insertFile' button
       ]),
   

3. Bulk Operations Select multiple files/folders (Ctrl+A) and perform actions like:

   • Delete (via context menu or shortcut Delete)
   • Move (drag-and-drop or bulk move via "Move" button)

4. Custom File Manager Page Extend the default page for domain-specific needs:

   FileManagerPlugin::make()
       ->defaultView('grid') // or 'list'
       ->allowedExtensions(['jpg', 'png', 'pdf'])
       ->maxFileSize(10) // in MB
       ->maxUploadCount(5),
   

Integration Tips

• Storage Adapters: Configure custom storage (e.g., S3) via storage config:

  'storage' => [
      'disk' => 's3',
      'path' => 'public/files',
  ],
  

• Permissions: Restrict actions per role using Filament’s built-in policies:

  FileManagerPlugin::make()
      ->permissions([
          'access' => fn (User $user) => $user->can('manage-files'),
          'upload' => fn (User $user) => $user->can('upload-files'),
      ]),
  

• Event Listeners: Hook into file operations (e.g., post-upload):

  FileManagerPlugin::make()
      ->listenForUploads(fn (UploadedFile $file) => Log::info('File uploaded:', ['file' => $file->getClientOriginalName()]));
  

Gotchas and Tips

Pitfalls

1. Path Sanitization

   • The package sanitizes paths to prevent directory traversal. If files disappear after upload, check:
     • config/filament-file-manager.php for allowed characters.
     • Custom storage adapters (e.g., S3) may need path adjustments.

2. Permission Denied Errors

   • Ensure the storage directory has write permissions:

     chmod -R 755 storage/app/public
     

   • Verify Filament’s user roles have the correct permissions (e.g., manage-files).

3. Large File Uploads

   • Increase PHP limits in .env if needed:

     UPLOAD_MAX_FILESIZE=20M
     POST_MAX_SIZE=20M
     

   • Batch uploads may fail silently; check browser console for errors.

4. Thumbnail Generation

   • Thumbnails fail for unsupported formats (e.g., SVG). Exclude these via:

     ->thumbnailGenerators([
         \MmesDesign\FilamentFileManager\ThumbnailGenerators\ImageThumbnailGenerator::class,
     ]),
     

Debugging

• Logs: Enable debug mode in config/filament-file-manager.php:

  'debug' => env('FFM_DEBUG', false),
  

  Check storage/logs/laravel.log for upload/move errors.

• Route Conflicts: Ensure /admin/file-manager doesn’t clash with existing routes. Override the route:

  FileManagerPlugin::make()
      ->route('custom-file-manager'),
  

Extension Points

1. Custom Views Override the default grid/list views by publishing assets:

   php artisan vendor:publish --tag=filament-file-manager-views
   

   Modify resources/views/vendor/filament-file-manager/....

2. File Preview Handlers Add support for custom file types (e.g., .docx):

   FileManagerPlugin::make()
       ->previewHandlers([
           \App\PreviewHandlers\DocxPreviewHandler::class,
       ]),
   

3. API Endpoints Extend the underlying API for custom logic:

   FileManagerPlugin::make()
       ->apiRoute('custom-file-manager-api')
       ->apiMiddleware([\App\Http\Middleware\CheckFilePermissions::class]),
   

Pro Tips

• Soft Deletes: Enable soft deletes for files/folders:

  FileManagerPlugin::make()
      ->softDeletes()
      ->softDeleteQuery(fn (Builder $query) => $query->whereNull('deleted_at')),
  

• Keyboard Shortcuts: Train users on shortcuts (e.g., F2 to rename, Esc to cancel).
• Localization: Add translations for non-English panels:

  FileManagerPlugin::make()
      ->translations([
          'it' => [
              'messages' => [
                  'upload_success' => 'Caricamento completato!',
              ],
          ],
      ]),