Fm Elfinder Bundle Laravel Package

Getting Started

Minimal Setup for First Use

1. Installation:

   composer require helios-ag/fm-elfinder-bundle
   bin/console elfinder:install
   

   This copies ElFinder assets to public/ and sets up basic routing.

2. Routing: Add to config/routes.yaml:

   elfinder:
       resource: "@FMElfinderBundle/Resources/config/routing.yaml"
   

3. Security: Secure routes in config/security.yaml:

   access_control:
       - { path: ^/efconnect, role: ROLE_USER }
       - { path: ^/elfinder, role: ROLE_USER }
   

4. Basic Config: Define a root directory in config/packages/fm_elfinder.yaml:

   fm_elfinder:
       instances:
           default:
               connector:
                   roots:
                       uploads:
                           driver: LocalFileSystem
                           path: "%kernel.project_dir%/public/uploads"
                           upload_allow: ['image/png', 'image/jpg']
                           upload_deny: ['all']
   

5. First Use Case: Integrate with a WYSIWYG editor (e.g., CKEditor) by referencing the ElFinder instance in your editor config:

   CKEDITOR.replace('editor', {
       filebrowserBrowseUrl: '/elfinder/ckeditor',
       filebrowserUploadUrl: '/elfinder/ckeditor/upload'
   });
   

Implementation Patterns

Workflows

1. File Management Integration:

   • Use the fm_elfinder form type for Symfony forms:

     use FM\ElfinderBundle\Form\Type\ElfinderType;
     
     $builder->add('image', ElfinderType::class, [
         'instance' => 'default',
         'multiple' => true,
     ]);
     

   • For EasyAdmin 2.x, configure the field type:

     # config/packages/easy_admin.yaml
     easy_admin:
         form_types:
             - FM\ElfinderBundle\Form\Type\ElfinderType
     

2. Multi-User File Isolation:

   • Configure dynamic home folders for users:

     fm_elfinder:
         instances:
             user_files:
                 where_is_multi:
                     roots: 0
                 multi_home_folder: true
                 folder_separator: "|"
                 connector:
                     roots:
                         uploads:
                             driver: LocalFileSystem
                             path: "%kernel.project_dir%/public/uploads"
     

   • Access via URL: /elfinder/user_files/{username}.

3. Editor-Specific Configurations:

   • CKEditor:

     fm_elfinder:
         instances:
             ckeditor:
                 editor: ckeditor
                 connector:
                     roots:
                         uploads:
                             driver: LocalFileSystem
                             path: "uploads"
     

   • TinyMCE:

     fm_elfinder:
         instances:
             tinymce:
                 editor: fm_tinymce
                 connector:
                     roots:
                         uploads:
                             driver: LocalFileSystem
                             path: "uploads"
     

4. Custom Templates:

   • Override the default template for the custom editor:

     fm_elfinder:
         instances:
             custom_editor:
                 editor: custom
                 editor_template: "FMElfinderBundle:Elfinder:custom.html.twig"
     

5. Event-Driven Extensions:

   • Listen to pre/post execution events to modify behavior:

     // src/EventListener/ElFinderListener.php
     use FM\ElfinderBundle\Event\ElFinderPreExecutionEvent;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     
     class ElFinderListener implements EventSubscriberInterface
     {
         public static function getSubscribedEvents()
         {
             return [
                 'fm_elfinder.event.pre_execution' => 'onPreExecution',
             ];
         }
     
         public function onPreExecution(ElFinderPreExecutionEvent $event)
         {
             $request = $event->getRequest();
             if ($request->query->get('cmd') === 'open') {
                 $event->setHomeFolder('user_'.$request->get('user_id'));
             }
         }
     }
     

   • Register the listener in services.yaml:

     services:
         App\EventListener\ElFinderListener:
             tags:
                 - { name: fm_elfinder.event_listener }
     

Gotchas and Tips

Pitfalls

1. CORS Configuration:

   • Enable cors_support in config if using cross-domain requests:

     fm_elfinder:
         cors_support: true
     

   • Without this, post-execution events won’t fire. Use NelmioCorsBundle for cross-domain clients.

2. File Permissions:

   • Ensure the path in roots is writable by the web server (e.g., chmod -R 775 uploads).

3. Driver-Specific Quirks:

   • LocalFileSystem: Paths are relative to public/ by default. Use absolute paths (e.g., %kernel.project_dir%/public/uploads) for clarity.
   • Flysystem/S3: Requires additional configuration (see Advanced Config).

4. Editor Integration:

   • CKEditor: Use filebrowserBrowseUrl and filebrowserUploadUrl with /elfinder/{instance}.
   • TinyMCE: Configure the file_picker_callback and file_browser_callback to point to /elfinder/{instance}.

5. Multi-Home Folders:

   • The multi_home_folder feature only works with LocalFileSystem. Ensure home folders (e.g., uploads/{user}) exist and are writable.

6. Debugging:

   • Enable debug mode in the connector:

     connector:
         debug: true
     

   • Check Symfony logs (var/log/dev.log) for ElFinder errors.

Tips

1. Dynamic Instance Names: Use instance names dynamically (e.g., {user}_files) to isolate user uploads without complex routing.

2. MIME Type Filtering: Restrict uploads to specific MIME types for security:

   upload_allow: ['image/png', 'image/jpg', 'application/pdf']
   upload_deny: ['all']
   

3. Custom Attributes: Lock or restrict access to folders:

   attributes:
       - { pattern: '/protected/', read: true, write: false, locked: true }
   

4. Asset Paths: Override the default asset path (/assets) if needed:

   assets_path: "/custom/path"
   

5. Performance:

   • Cache ElFinder responses if using static assets.
   • Limit visible_mime_types to reduce UI clutter:

     visible_mime_types: ['image/png', 'image/jpg', 'application/pdf']
     

6. Testing:

   • Mock the ElFinder service in PHPUnit:

     $this->container->get('fm_elfinder.elfinder')->method('run')->willReturn(['output' => 'test']);
     

   • Use the ElFinderTestCase base class if available.

7. Backup Roots: Define multiple roots for redundancy:

   roots:
       primary:
           driver: LocalFileSystem
           path: "uploads/primary"
       backup:
           driver: LocalFileSystem
           path: "uploads/backup"
   

8. Localization: Override ElFinder’s language files by copying them to public/assets/elfinder/lang/ and translating keys.

9. Symfony Service as Driver: Use a custom service as a volume driver (advanced):

   fm_elfinder:
       instances:
           custom_driver:
               connector:
                   roots:
                       custom:
                           driver: "service_id"
   

   Implement FM\ElfinderBundle\Driver\VolumeDriverInterface.

10. Legacy Editors: For TinyMCE 3.x, use the tinymce editor instance:

    fm_elfinder:
        instances:
            tinymce3:
                editor: tinymce