Fm Elfinder Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require helios-ag/fm-elfinder-bundle
   

   Enable in config/bundles.php:

   return [
       // ...
       HeliosAg\FMElfinderBundle\FMElfinderBundle::class => ['all' => true],
   ];
   

2. Configure Routes Add to config/routes.yaml:

   fm_elfinder:
       resource: "@FMElfinderBundle/Resources/config/routing.yml"
       prefix: /elfinder
   

3. Basic Usage Include the JS/CSS in your template:

   {{ include('@FMElfinder/elfinder.html.twig', {
       id: 'elfinder',
       lang: 'en',
       url: path('fm_elfinder')
   }) }}
   

   Trigger via:

   $('#elfinder').elfinder({
       url: '/elfinder/connector'
   });
   

4. First Use Case Integrate with a WYSIWYG editor (e.g., TinyMCE) for file uploads:

   tinymce.init({
       selector: 'textarea',
       plugins: 'filemanager',
       filemanager_callback: function(callback, value, meta) {
           $('#elfinder').elfinder('open', function(elfinder) {
               elfinder.callbacks.open.call(elfinder, callback, value, meta);
           });
       }
   });
   

Implementation Patterns

Common Workflows

1. File Management Integration

   • Use FMElfinderBundle's built-in connectors for Symfony file systems (e.g., Flysystem, Symfony Filesystem).
   • Example: Configure config/packages/fm_elfinder.yaml:

     fm_elfinder:
         instances:
             default:
                 connector: 'fm_elfinder.connector.filesystem'
                 root: '%kernel.project_dir%/public/uploads'
     

2. Custom Connectors Extend FMElfinderBundle\Connector\AbstractConnector for database-backed storage or cloud services (e.g., S3):

   namespace App\Connector;
   
   use FMElfinderBundle\Connector\AbstractConnector;
   
   class S3Connector extends AbstractConnector {
       public function init() {
           $this->driver = 'S3';
           $this->volume = new \League\Flysystem\AwsS3v3\AwsS3Adapter(...);
       }
   }
   

   Register in services:

   services:
       app.elfinder.connector.s3:
           class: App\Connector\S3Connector
           tags: ['fm_elfinder.connector']
   

3. Permissions & ACLs Use Symfony’s security component to restrict access:

   fm_elfinder:
       instances:
           admin:
               connector: 'fm_elfinder.connector.filesystem'
               root: '%kernel.project_dir%/public/admin-uploads'
               access_control: 'ROLE_ADMIN'
   

   In Twig:

   {% if is_granted('ROLE_ADMIN') %}
       {{ include('@FMElfinder/elfinder.html.twig', { id: 'admin-elfinder' }) }}
   {% endif %}
   

4. Event-Driven Extensions Listen to file events (e.g., upload, delete) via Symfony events:

   // config/services.yaml
   App\EventListener\ElfinderEventListener:
       tags:
           - { name: kernel.event_listener, event: fm_elfinder.pre_upload, method: onPreUpload }
   

Integration Tips

• Asset Optimization: Use Webpack Encore to bundle elFinder JS/CSS with your app’s assets.
• Translation: Override translations in translations/messages.en.yaml:

  fm_elfinder:
      dialog:
          title: 'Custom File Manager'
  

• Theming: Extend assets/elfinder/css/elfinder.min.css or override templates in templates/bundles/FMElfinder/.

Gotchas and Tips

Pitfalls

1. CORS Issues If using elFinder in a SPA or cross-domain context, ensure:

   • The connector endpoint (/elfinder/connector) has proper CORS headers.
   • Configure Symfony’s AccessControl for OPTIONS requests:

     # config/packages/security.yaml
     access_control:
         - { path: ^/elfinder/connector, roles: PUBLIC_ACCESS }
     

2. File System Permissions

   • Ensure the root directory in fm_elfinder.yaml is writable by the web server user (e.g., www-data).
   • Debug with:

     chmod -R 775 %kernel.project_dir%/public/uploads
     chown -R www-data:www-data %kernel.project_dir%/public/uploads
     

3. Connector Caching

   • Clear the cache after adding custom connectors:

     php bin/console cache:clear
     

4. JavaScript Conflicts

   • elFinder relies on jQuery and jQuery UI. Load them before elFinder:

     {{ include('FMElfinder::jquery-ui.html.twig') }}
     {{ include('@FMElfinder/elfinder.html.twig') }}
     

Debugging

• Enable Debug Mode: Set debug: true in fm_elfinder.yaml to log connector requests.
• Check Connector Logs: Inspect Symfony’s var/log/dev.log for errors like:

  [FMElfinderBundle] Connector error: "File not found" (code: 2)
  

• Test Connector Manually: Use curl to test the connector endpoint:

  curl -X POST http://localhost/elfinder/connector -d 'cmd=open&target='
  

Extension Points

1. Custom Commands Add new elFinder commands (e.g., "Compress") by extending the connector:

   public function init() {
       $this->commands = array_merge($this->commands, [
           'compress' => [$this, 'handleCompress'],
       ]);
   }
   

2. UI Customization Override Twig templates (e.g., elfinder.html.twig) in templates/bundles/FMElfinder/. Example: Add a custom toolbar button:

   {# templates/bundles/FMElfinder/elfinder.html.twig #}
   <button id="custom-button" class="elfinder-button">Custom Action</button>
   

3. Database Metadata Store file metadata (e.g., title, description) in a database table and hydrate it via a custom connector:

   public function open($path, $options = []) {
       $files = $this->fetchFilesFromDB($path);
       return $this->formatFiles($files);
   }
   

4. Lazy Loading For large directories, implement lazy loading in the connector:

   public function open($path, $options = []) {
       if (strpos($path, 'large-folder') !== false) {
           return $this->streamFiles($path); // Stream files on demand
       }
       return parent::open($path, $options);
   }
   

Configuration Quirks

• Relative vs. Absolute Paths: The root in fm_elfinder.yaml must be an absolute path (e.g., %kernel.project_dir%/public/uploads).
• URL Generation: Use path() in Twig to generate the connector URL:

  url: "{{ path('fm_elfinder') }}"
  

• Multiple Instances: Configure multiple instances in fm_elfinder.yaml for different use cases (e.g., admin vs. user uploads). Access them via:

  $('#elfinder-admin').elfinder({ url: '/elfinder/connector?instance=admin' });