README

A Filament plugin for S3-compatible file management with file and folder selection support, built with Flysystem integration. Supports both FilamentPHP v3 and v4.

Features

🗂️ File and Folder Selection: Select files, folders, or both
📁 Folder Navigation: Browse through S3 storage with breadcrumb navigation
🔍 Search: Search files across your S3 storage
👁️ File Preview: Preview images, videos, PDFs, and audio files
📤 File Upload: Upload files directly to S3 with progress tracking
🎨 Grid & List Views: Switch between grid and list view modes
🔒 Secure: Presigned URLs for secure file access
⚡ Caching: Built-in caching for improved performance
🎯 Flysystem Integration: Works with any S3-compatible storage (AWS S3, DigitalOcean Spaces, etc.)
✏️ File Operations: Rename, move, copy, and delete files and folders
📂 Folder Management: Create new folders directly from the file browser
🗑️ Bulk Operations: Delete files and folders with confirmation
🔄 Real-time Updates: Automatic refresh after file operations

Installation

Via Composer

composer require muhamad-selim/filament-s3-filemanager

Publish Configuration

php artisan vendor:publish --tag=filament-s3-filemanager-config

Publish Views (Optional)

If you want to customize the views:

php artisan vendor:publish --tag=filament-s3-filemanager-views

Configuration

1. Configure S3 Disk

Make sure you have an S3-compatible disk configured in config/filesystems.php:

'disks' => [
    's3' => [
        'driver' => 's3',
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'region' => env('AWS_DEFAULT_REGION'),
        'bucket' => env('AWS_BUCKET'),
        'url' => env('AWS_URL'),
        'endpoint' => env('AWS_ENDPOINT'),
        'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', false),
    ],
],

2. Environment Variables

Add these to your .env file:

FILAMENT_S3_FILEMANAGER_DISK=s3
FILAMENT_S3_FILEMANAGER_SELECTION_MODE=file
FILAMENT_S3_FILEMANAGER_URL_EXPIRATION=3600
FILAMENT_S3_FILEMANAGER_MAX_SIZE=2048000
FILAMENT_S3_FILEMANAGER_CACHE_ENABLED=true
FILAMENT_S3_FILEMANAGER_CACHE_TTL=300

Usage

Basic Usage

use MuhamadSelim\FilamentS3Filemanager\Forms\Components\S3FileManager;

S3FileManager::make('file_path')
    ->label('Select File')
    ->disk('s3')

File Selection Only

S3FileManager::make('file_path')
    ->label('Select File')
    ->disk('s3')
    ->fileOnly()

Folder Selection Only

S3FileManager::make('folder_path')
    ->label('Select Folder')
    ->disk('s3')
    ->folderOnly()

Both File and Folder Selection

S3FileManager::make('path')
    ->label('Select File or Folder')
    ->disk('s3')
    ->fileOrFolder()

Dynamic Disk Selection

S3FileManager::make('file_path')
    ->label('Select File')
    ->disk(fn (Get $get) => $get('storage_disk') ?? 's3')

Complete Example

use Filament\Forms\Form;
use MuhamadSelim\FilamentS3Filemanager\Forms\Components\S3FileManager;

public function form(Form $form): Form
{
    return $form
        ->schema([
            S3FileManager::make('file_path')
                ->label('Select File')
                ->disk('s3')
                ->fileOnly()
                ->required()
                ->afterStateUpdated(function ($state, $set) {
                    if ($state) {
                        // Handle file selection
                        $set('file_name', basename($state));
                    }
                }),
        ]);
}

Selection Modes

The component supports three selection modes:

File Only (fileOnly()): Users can only select individual files
Folder Only (folderOnly()): Users can only select directories
Both (fileOrFolder()): Users can toggle between selecting files or folders

API Routes

The package registers the following API routes:

POST /api/s3-files/folder-contents - List files and directories in a folder with pagination
POST /api/s3-files/preview-url - Generate presigned URL for file preview
POST /api/s3-files/upload - Upload file to S3
DELETE /api/s3-files/file - Delete a file
DELETE /api/s3-files/folder - Delete a folder and all its contents
POST /api/s3-files/rename-file - Rename a file
POST /api/s3-files/rename-folder - Rename a folder
POST /api/s3-files/move-file - Move a file to a new location
POST /api/s3-files/move-folder - Move a folder to a new location
POST /api/s3-files/copy-file - Copy a file to a new location
POST /api/s3-files/copy-folder - Copy a folder to a new location
POST /api/s3-files/create-folder - Create a new folder

All routes are protected by authentication middleware and rate limiting.

Configuration Options

Default Disk

Set the default S3 disk to use:

'default_disk' => 's3',

Selection Mode

Set the default selection mode:

'default_selection_mode' => 'file', // 'file', 'folder', or 'both'

Presigned URL Expiration

Set how long presigned URLs remain valid (in seconds):

'presigned_url_expiration' => 3600, // 1 hour

Maximum File Size

Set the maximum file size for uploads (in KB):

'max_file_size' => 2048000, // 2GB

Allowed Extensions

Configure which file extensions are allowed:

'allowed_extensions' => [
    'mp4', 'pdf', 'jpg', 'png', // etc.
],

File Operations

The file browser includes comprehensive file management capabilities:

Delete Operations

Delete individual files
Delete folders and all their contents
Confirmation dialogs for safety

Rename Operations

Rename files and folders
Validation to prevent duplicate names
Real-time updates after renaming

Move Operations

Move files to different folders
Move folders with all contents
Path validation and error handling

Copy Operations

Copy files to new locations
Copy folders recursively
Maintains original files

Create Folder

Create new folders from the file browser
Automatic navigation to new folder
Validation for folder names

Testing

The package includes a comprehensive test suite using Pest. To run the tests:

# From the package directory
cd packages/muhamad-selim/filament-s3-filemanager
composer install
vendor/bin/pest

# Or from the main project root
php artisan test packages/muhamad-selim/filament-s3-filemanager/tests

Test Structure

Unit Tests: Service provider registration and configuration
Feature Tests:
- S3StorageService: File operations, caching, error handling
- S3FileBrowserController: API endpoints, authentication, validation
- S3FileManager Component: Form component functionality
- Integration: End-to-end workflows

Test Coverage

The test suite covers:

File upload, deletion, and metadata operations
Presigned URL generation
Folder structure listing and navigation
File/folder selection modes
Security (path sanitization, authentication)
Error handling and retry logic
Cache management

Requirements

PHP 8.2+
Laravel 11.0+ or 12.0+
Filament 3.2+ or 4.0+
League Flysystem 3.0+
League Flysystem AWS S3 V3 3.0+

Version Compatibility

This package supports multiple versions simultaneously:

FilamentPHP: v3.2+ and v4.0+
Laravel: v11.0+ and v12.0+

The same codebase works with both versions without requiring different branches or conditional code paths.

License

MIT

Support

For issues, questions, or contributions, please visit the GitHub repository.

muhamad-selim / filament-s3-filemanager

Maintainers

Details