Filemanager Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require mwguerra/filemanager
   

2. Publish configuration:

   php artisan vendor:publish --provider="MWGuerra\FileManager\FileManagerServiceProvider" --tag="filemanager-config"
   

3. Add to Filament:

   // In your Filament app service provider (AppServiceProvider)
   FileManager::register();
   

4. First use case: Embed in a Filament page:

   use MWGuerra\FileManager\Components\FileManager;
   
   public function getPages(): array
   {
       return [
           FileManager::make('files')
               ->disk('public')
               ->mode('database') // or 'storage'
               ->title('File Manager'),
       ];
   }
   

Key Configuration

• Storage mode: Direct filesystem browsing (no DB tracking).
• Database mode: Track files with metadata (recommended for most use cases).
• Default disk: Configure in config/filemanager.php under default_disk.

Implementation Patterns

Common Workflows

1. Embedding in Filament Forms

use MWGuerra\FileManager\Components\FileManagerField;

public static function form(Form $form): Form
{
    return $form
        ->schema([
            FileManagerField::make('document')
                ->disk('s3')
                ->mode('database')
                ->required()
                ->label('Upload Document'),
        ]);
}

2. Customizing File Operations

Override default behaviors via policies:

// app/Policies/FileManagerPolicy.php
public function before($user, $ability)
{
    if ($user->isAdmin()) {
        return true;
    }
}

// Register in FileManagerServiceProvider
FileManager::policy(FileManagerPolicy::class);

3. Handling Uploads Programmatically

use MWGuerra\FileManager\Facades\FileManager;

public function uploadFile(Request $request)
{
    $file = $request->file('file');
    $path = FileManager::upload($file, 'public', [
        'folder' => 'uploads',
        'metadata' => ['user_id' => auth()->id()],
    ]);
    return response()->json(['path' => $path]);
}

4. Integration with Filament Tables

Display files in a table:

use MWGuerra\FileManager\Components\FileManagerColumn;

public static function table(Table $table): Table
{
    return $table
        ->columns([
            FileManagerColumn::make('document')
                ->disk('public')
                ->mode('database')
                ->label('Attached File'),
        ]);
}

5. Multi-Storage Setups

Configure multiple disks in config/filemanager.php:

'disks' => [
    'local' => 'local',
    's3' => [
        'driver' => 's3',
        'bucket' => 'my-bucket',
        'url' => env('AWS_URL'),
    ],
],

Integration Tips

Laravel Policies

Leverage Laravel’s built-in policies for fine-grained control:

// app/Policies/FileManagerPolicy.php
public function delete($user, File $file)
{
    return $user->can('delete-files') && $file->user_id === $user->id;
}

Signed URLs for Private Files

Generate time-limited URLs:

$url = FileManager::temporaryUrl($file, now()->addMinutes(30));

Custom File Previews

Extend preview handlers in app/Providers/FileManagerServiceProvider.php:

FileManager::extendPreview('csv', function ($path) {
    return view('filemanager::previews.csv', ['path' => $path]);
});

Bulk Operations

Use the FileManager::bulk() helper for batch actions:

FileManager::bulk()->delete($fileIds);

Gotchas and Tips

Pitfalls

1. Disk Configuration Mismatch

   • Ensure config/filesystems.php matches the disks referenced in config/filemanager.php.
   • Fix: Run php artisan storage:link for local disks and verify S3/MinIO credentials.

2. Permission Denied Errors

   • Common in Storage mode when Laravel’s filesystem permissions don’t align with the package’s expectations.
   • Fix: Set storage_mode_permissions in config/filemanager.php:

     'storage_mode_permissions' => [
         'folder' => 0755,
         'file' => 0644,
     ],
     

3. Database Mode Without Migrations

   • If using database mode, run:

     php artisan migrate
     

   • The package publishes migrations for the files table.

4. CORS Issues with S3/MinIO

   • Ensure your storage bucket’s CORS policy allows requests from your domain.
   • Fix: Add to config/filemanager.php:

     's3_cors' => [
         'AllowedHeaders' => ['*'],
         'AllowedMethods' => ['GET', 'HEAD', 'PUT', 'POST', 'DELETE'],
         'AllowedOrigins' => [env('APP_URL')],
     ],
     

5. Livewire Component Conflicts

   • If using multiple Livewire components, ensure unique IDs:

     FileManager::make('unique-id')
         ->wireModel('file_manager_unique_id')
     

Debugging Tips

1. Log File Operations Enable debug mode in config/filemanager.php:

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

   Logs will appear in storage/logs/laravel.log.

2. Check File Existence Use the FileManager::exists() helper to verify files:

   if (FileManager::exists('public/path/to/file.txt')) {
       // File exists
   }
   

3. Validate MIME Types Customize allowed MIME types in config/filemanager.php:

   'allowed_mime_types' => [
       'image' => ['jpg', 'png', 'gif', 'webp'],
       'document' => ['pdf', 'docx', 'xlsx'],
   ],
   

4. Clear Cached Views If previews render incorrectly:

   php artisan view:clear
   

Extension Points

1. Custom File Metadata Extend the File model:

   // app/Models/File.php
   public function scopeCustomScope($query, $value)
   {
       return $query->where('custom_field', $value);
   }
   

2. Override Default Views Publish and modify views:

   php artisan vendor:publish --provider="MWGuerra\FileManager\FileManagerServiceProvider" --tag="filemanager-views"
   

   Edit files in resources/views/vendor/filemanager/.

3. Add Custom Actions Register via the service provider:

   FileManager::extendAction('custom_action', function ($file) {
       // Logic for custom action
       return view('filemanager::actions.custom', ['file' => $file]);
   });
   

4. Hook into Events Listen for file operations:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'MWGuerra\FileManager\Events\FileUploaded' => [
           'App\Listeners\LogFileUpload',
       ],
   ];
   

5. Localization Publish translations:

   php artisan vendor:publish --provider="MWGuerra\FileManager\FileManagerServiceProvider" --tag="filemanager-translations"
   

   Edit files in resources/lang/.