Getting Started

Minimal Setup

Installation:

composer require slimani/filament-media-manager

Publish the package assets and config:

php artisan vendor:publish --provider="Slimani\FilamentMediaManager\FilamentMediaManagerServiceProvider" --tag="filament-media-manager-config"
php artisan vendor:publish --provider="Slimani\FilamentMediaManager\FilamentMediaManagerServiceProvider" --tag="filament-media-manager-assets"

Register the Plugin: Add to app/Providers/AppServiceProvider.php:

use Slimani\FilamentMediaManager\FilamentMediaManagerPlugin;

public function register()
{
    FilamentMediaManagerPlugin::make()
        ->register();
}

First Use Case: Attach the media manager to a Filament resource or page:

use Slimani\FilamentMediaManager\Forms\Components\MediaManager;

MediaManager::make('media')
    ->label('Upload Media')
    ->directory('products')
    ->maxFiles(10)
    ->maxFileSize(5) // in MB
    ->acceptedFileTypes(['jpg', 'png', 'pdf'])
    ->columnSpanFull()

Implementation Patterns

Common Workflows

Resource Integration: Add media manager to a Filament resource form:

public static function form(Form $form): Form
{
    return $form
        ->schema([
            MediaManager::make('images')
                ->label('Product Images')
                ->directory('products/{product_id}')
                ->hiddenLabel()
                ->columnSpanFull(),
        ]);
}

Table Actions: Use media manager in table actions for inline uploads:

use Slimani\FilamentMediaManager\Tables\Actions\MediaManager;

MediaManager::make('media')
    ->label('Upload Media')
    ->directory('blog/{post_id}')
    ->modalHeading('Upload Media for Post')
    ->modalWidth('75%')

Dynamic Directories: Dynamically set directories based on context:

MediaManager::make('media')
    ->directory(fn () => "categories/{$this->record->category_id}")

Customizing File Handling: Override default file handling (e.g., for cloud storage):

use Slimani\FilamentMediaManager\Contracts\FileHandler;

FilamentMediaManagerPlugin::make()
    ->fileHandler(new CustomS3FileHandler())
    ->register();

Integration Tips

Leverage Filament’s Form Components: Combine with other Filament components like RichEditor or MarkdownEditor for seamless media embedding:
```
RichEditor::make('description')
    ->toolbarButtons([
        'attachFiles',
    ])
```

Batch Processing: Use the media manager in bulk actions for resources:

public static function table(Table $table): Table
{
    return $table
        ->actions([
            MediaManager::make('media')
                ->label('Upload for Selected')
                ->directory(fn (array $records) => "batch_{now()}")
                ->records($records)
        ]);
}

Permissions: Restrict access to specific folders using Filament’s built-in policies:

public static function getPages(): array
{
    return [
        'media-manager' => Pages\MediaManager::class,
    ];
}

public static function getNavigationGroup(): ?string
{
    return 'Admin';
}

public static function getNavigationSort(): ?int
{
    return 5;
}

Gotchas and Tips

Pitfalls

Directory Permissions: Ensure the storage directory (e.g., storage/app/public) has proper write permissions:
```
chmod -R 755 storage/app/public
```
Tip: Use php artisan storage:link if using symbolic links.
File Size Limits: Default PHP upload_max_filesize and post_max_size may block large uploads. Adjust in php.ini or .env:
```
upload_max_filesize = 20M
post_max_size = 25M
```
Caching Issues: Clear Filament’s view cache after updating the package:
```
php artisan filament:cache-reset
```
Directory Naming Conflicts: Avoid dynamic directories with special characters (e.g., /, \). Sanitize with:
```
->directory(fn () => Str::slug($this->record->name))
```

Debugging

Log Upload Errors: Enable debug mode in config/filament-media-manager.php:
```
'debug' => env('APP_DEBUG', false),
```
Check logs in storage/logs/laravel.log.
Verify File Handler: If files aren’t saving, inspect the FileHandler implementation:
```
Slimani\FilamentMediaManagerPlugin::getFileHandler();
```

Extension Points

Custom File Handlers: Extend Slimani\FilamentMediaManager\Contracts\FileHandler for cloud storage (e.g., S3, GCS):

class CustomS3Handler implements FileHandler
{
    public function store(File $file, string $directory, string $filename): string
    {
        // Custom logic (e.g., AWS SDK)
    }

    public function delete(string $path): void
    {
        // Custom logic
    }
}

Override Views: Publish and modify views:
```
php artisan vendor:publish --tag="filament-media-manager-views"
```
Edit in resources/views/vendor/filament-media-manager/.

Event Listeners: Listen to media events (e.g., MediaUploaded):

use Slimani\FilamentMediaManager\Events\MediaUploaded;

event(new MediaUploaded($file, $directory, $user));

Custom Validation: Add validation rules to the media manager:

MediaManager::make('media')
    ->rules([
        fn (array $files) => count($files) <= 5 ?: 'max.files',
    ])
    ->afterStateUpdated(fn (callable $set, array $state) => [
        $set('media', $state['media'] ?? []),
    ])

Pro Tips

Lazy Loading: Use lazy for better performance with large media libraries:
```
MediaManager::make('media')
    ->lazy()
    ->perPage(20)
```

Thumbnails: Generate thumbnails on upload via FileHandler:

public function store(File $file, string $directory, string $filename): string
{
    $path = $file->store($directory, 'public');
    $this->generateThumbnail($path);
    return $path;
}

Bulk Actions: Implement bulk uploads with MediaManager in table actions:

MediaManager::make('media')
    ->label('Bulk Upload')
    ->directory('bulk_uploads')
    ->modalSubmitAction(fn (array $files) => [
        'notify' => ['Uploaded ' . count($files) . ' files.'],
    ])

Filament Media Manager Laravel Package