Elfinder Flysystem Driver Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require barryvdh/elfinder-flysystem-driver
   

   Ensure league/flysystem and barryvdh/laravel-elfinder are also installed (core dependencies).

2. Register the Driver In config/elfinder.php, add the Flysystem driver under drivers:

   'drivers' => [
       'local' => [
           'driver' => 'local',
       ],
       'flysystem' => [
           'driver' => 'barryvdh\ElfinderFlysystemDriver\ElfinderFlysystem',
           'filesystem' => 's3', // Your Flysystem adapter name
       ],
   ],
   

3. First Use Case Configure a route to serve elFinder with the Flysystem driver:

   Route::get('/elfinder', '\Barryvdh\Elfinder\Facades\Elfinder::open');
   

   Ensure your Flysystem adapter (e.g., S3, Dropbox) is properly configured in config/filesystems.php.

Implementation Patterns

Workflows

1. Multi-Adapter Support Use the same elFinder UI to manage files across different Flysystem adapters (e.g., local, S3, Dropbox) by defining multiple drivers in config/elfinder.php:

   'drivers' => [
       's3' => ['driver' => 'barryvdh\ElfinderFlysystemDriver\ElfinderFlysystem', 'filesystem' => 's3'],
       'dropbox' => ['driver' => 'barryvdh\ElfinderFlysystemDriver\ElfinderFlysystem', 'filesystem' => 'dropbox'],
   ],
   

   Switch adapters dynamically via JavaScript:

   $('#elfinder').elfinder({
       url: '/elfinder?driver=s3', // or 'dropbox'
   });
   

2. Custom Permissions Override default permissions (e.g., disable uploads for read-only adapters) by extending the driver:

   use Barryvdh\ElfinderFlysystemDriver\ElfinderFlysystem;
   
   class CustomElfinderFlysystem extends ElfinderFlysystem {
       public function getConfig() {
           $config = parent::getConfig();
           $config['disabled'] = ['upload', 'mkfile', 'mkdir']; // Disable actions
           return $config;
       }
   }
   

   Register the custom driver in config/elfinder.php:

   'drivers' => [
       'custom-s3' => [
           'driver' => 'App\CustomElfinderFlysystem',
           'filesystem' => 's3',
       ],
   ],
   

3. Event-Driven Integrations Listen to elFinder events (e.g., file uploads) to trigger Laravel logic:

   Elfinder::event('upload', function ($event) {
       $file = $event->getFile();
       // Process $file->getPathname() (Flysystem path)
       event(new FileUploaded($file->getPathname()));
   });
   

Integration Tips

• Laravel Storage Integration Use Laravel’s Storage facade to interact with files post-elFinder operations:

  use Illuminate\Support\Facades\Storage;
  
  $path = 's3:user-uploads/file.txt';
  Storage::put($path, 'Content...'); // Sync with elFinder
  

• Thumbnail Generation For image previews, integrate with intervention/image:

  Elfinder::event('init', function () {
      Elfinder::driver('flysystem')->setConfig([
          'thumbsMime' => ['image/jpeg', 'image/png'], // Enable thumbnails
      ]);
  });
  

• Caching Cache Flysystem filesystem instances to avoid reinitialization:

  $filesystem = Cache::remember('flysystem.s3', 3600, function () {
      return Storage::disk('s3')->getDriver();
  });
  

Gotchas and Tips

Pitfalls

1. Filesystem Initialization

   • Issue: Flysystem adapters may fail silently if misconfigured (e.g., missing AWS credentials).
   • Fix: Validate configurations in config/filesystems.php and test with:

     Storage::disk('s3')->listContents();
     

2. Permission Mismatches

   • Issue: elFinder may throw AccessDenied errors if Flysystem permissions differ from expected.
   • Fix: Use setVisibility() or setVisibilityCallback in the driver:

     $driver->setVisibilityCallback(function ($path) {
         return 'public'; // Force public visibility
     });
     

3. Path Normalization

   • Issue: Flysystem paths (e.g., s3://bucket/path) may not work with elFinder’s local path expectations.
   • Fix: Normalize paths in the driver:

     $path = str_replace('s3://', '', $path); // Strip adapter prefix
     

4. Large File Handling

   • Issue: Uploads to cloud storage (e.g., S3) may time out or fail for large files.
   • Fix: Adjust PHP settings (upload_max_filesize, max_execution_time) and use chunked uploads:

     Elfinder::driver('flysystem')->setConfig([
         'uploadMaxSize' => '100M',
         'uploadChunkSize' => '5M',
     ]);
     

Debugging

• Enable Logging Add debug output to config/elfinder.php:

  'debug' => env('APP_DEBUG', false),
  'log' => storage_path('logs/elfinder.log'),
  

• Check Driver Output Use dd() or Log::debug() in the driver’s methods (e.g., getChildren) to inspect Flysystem responses.

Extension Points

1. Custom Metadata Extend file metadata with Flysystem-specific data:

   Elfinder::event('getFile', function ($event) {
       $file = $event->getFile();
       $file->set('custom', [
           'size_human' => size_format($file->getSize()),
           'url' => Storage::disk('s3')->url($file->getPathname()),
       ]);
   });
   

2. Dynamic Driver Switching Switch drivers at runtime based on user roles or contexts:

   $driver = auth()->user()->isAdmin() ? 's3' : 'local';
   Elfinder::driver($driver)->open();
   

3. Webhook Triggers Use Laravel’s queue to process elFinder actions asynchronously:

   Elfinder::event('upload', function ($event) {
       ProcessFileUpload::dispatch($event->getFile())->delay(now()->addSeconds(10));
   });