Elfinderwidget Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require captjm/elfinderwidget-bundle
   

   Add to config/bundles.php:

   Captjm\ElfinderWidgetBundle\CaptjmElfinderWidgetBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php artisan config:dump
   

   Update config/packages/captjm_elfinder_widget.yaml with your storage path (e.g., public/uploads or a custom filesystem disk).

3. First Use Case Embed the widget in a Twig template:

   {{ render(controller('CaptjmElfinderWidgetBundle:Default:index')) }}
   

   Or use the standalone JS/CSS assets:

   {{ asset('bundles/captjmelfinderwidget/js/elfinder.min.js') }}
   

Implementation Patterns

Workflows

1. File Manager Integration

   • Use the widget as a standalone file manager or embed it in forms (e.g., for image uploads).
   • Example: Attach to a textarea for file path input:

     <textarea id="file-path-input" name="file_path"></textarea>
     {{ render(controller('CaptjmElfinderWidgetBundle:Default:widget', {'target': 'file-path-input'})) }}
     

2. Custom Connector Configuration Extend the default connector (PHP backend) by overriding the connector service:

   # config/packages/captjm_elfinder_widget.yaml
   captjm_elfinder_widget:
       connector:
           class: App\Services\CustomElfinderConnector
   

   Implement Captjm\ElfinderWidgetBundle\Connector\ConnectorInterface.

3. Twig Extensions Use the elfinder_widget Twig function for dynamic rendering:

   {{ elfinder_widget({
       'target': 'file-input',
       'options': {'uploadMaxSize': 2097152}  # 2MB limit
   }) }}
   

4. Asset Management

   • Override default assets (JS/CSS) by publishing assets:

     php artisan vendor:publish --tag=elfinder-widget-assets
     

   • Customize via webpack.mix.js or manual asset compilation.

Gotchas and Tips

Pitfalls

1. Connector Misconfiguration

   • Ensure the connector path in config/packages/captjm_elfinder_widget.yaml is correct (default: bundles/captjmelfinderwidget/connector.php).
   • Debug with tail -f storage/logs/laravel.log if the connector fails silently.

2. Filesystem Permissions

   • Verify the storage path (e.g., public/uploads) has 755 permissions and is writable by the web server user.
   • For custom disks, ensure the filesystem config is properly set in config/filesystems.php.

3. Twig Autoloading

   • If Twig functions fail, clear the cache:

     php artisan cache:clear
     php artisan config:clear
     

4. CSRF Protection

   • The connector may block requests without CSRF tokens. Add this to your middleware:

     // app/Http/Middleware/VerifyCsrfToken.php
     protected $except = [
         'bundles/captjmelfinderwidget/connector',
     ];
     

Tips

1. Custom Commands Extend the bundle by creating a custom command to sync files or generate thumbnails:

   // app/Console/Commands/SyncElfinder.php
   use Captjm\ElfinderWidgetBundle\Services\ElfinderService;
   $elfinder = app(ElfinderService::class);
   $elfinder->syncDisk('public', 'uploads');
   

2. Event Listeners Hook into file operations (e.g., post-upload) via the ElfinderEvents:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'Captjm\ElfinderWidgetBundle\Events\FileUploaded' => [
           'App\Listeners\LogUploadedFile',
       ],
   ];
   

3. Localization Override translations by publishing the bundle’s language files:

   php artisan vendor:publish --tag=elfinder-widget-translations
   

4. Performance

   • Disable unused drivers (e.g., Net, FTP) in the connector config to reduce overhead.
   • Use cache:tag to invalidate Twig cache when configs change:

     php artisan cache:clear --tags=elfinder-widget