Elfinder Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alphalemon/elfinder-bundle
   

   (Note: The original README uses legacy Git submodule setup; Composer is preferred for modern Symfony projects.)

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       AlphaLemon\ElFinderBundle\AlphaLemonElFinderBundle::class => ['all' => true],
   ];
   

3. Install Assets:

   php bin/console assets:install public
   php bin/console assetic:dump
   

4. First Use Case: Access the file manager at /al_showElFinder (default route). This renders a ready-to-use elFinder UI with minimal configuration.

Key Files to Review

• Default Template: vendor/alphalemon/elfinder-bundle/Resources/views/ElFinder/show.html.twig (Blocks for customization: stylesheet_files, javascript_files, init_script, elfinder_html)
• Connector Example: vendor/alphalemon/elfinder-bundle/Resources/config/services.yml (Defines the default el_finder_media_connector service.)

Implementation Patterns

1. Basic Integration Workflow

1. Extend the Default Template: Override show.html.twig in your theme (e.g., templates/ElFinder/show.html.twig) to customize:

   {% extends 'AlphaLemonElFinderBundle:ElFinder:show.html.twig' %}
   {% block init_script %}
       <script>
           $(document).ready(function() {
               $('<div/>').elfinder({
                   url: '/custom-connector',
                   lang: 'en',
                   width: '100%',
                   height: '500px'
               }).dialog();
           });
       </script>
   {% endblock %}
   

2. Configure the Connector: Create a custom connector service in config/services.yaml:

   services:
       App\Connector\CustomElFinderConnector:
           arguments: ['@service_container']
           tags: ['el_finder.connector']
   

   (Tagging ensures the service is autowired into the bundle.)

3. Define Connector Logic:

   // src/Connector/CustomElFinderConnector.php
   namespace App\Connector;
   
   use AlphaLemon\ElFinderBundle\Core\Connector\AlphaLemonElFinderBaseConnector;
   
   class CustomElFinderConnector extends AlphaLemonElFinderBaseConnector {
       protected function configure() {
           return [
               'roots' => [
                   [
                       'driver' => 'LocalFileSystem',
                       'path' => '%kernel.project_dir%/public/uploads',
                       'URL' => '/uploads',
                       'accessControl' => 'access',
                       'uploadAllow' => ['all'], // Allow all uploads (customize as needed)
                   ]
               ],
           ];
       }
   }
   

2. Common Use Cases

3. Integration with Symfony Features

• Security: Use Symfony’s security component in your connector:

  public function access($attr, $path = null) {
      if ($attr === 'read') {
          return $this->container->get('security.authorization_checker')->isGranted('ROLE_USER');
      }
      return false;
  }
  

• Routing: Customize the connector route in config/routes.yaml:

  al_custom_connector:
      path: /custom-connector
      defaults: { _controller: 'App\Controller\ElFinderController::connect' }
  

• Assetic: Add custom CSS/JS to the stylesheet_files or javascript_files blocks in your template.

Gotchas and Tips

Pitfalls

1. Asset Installation:

   • Forgetting assets:install or assetic:dump will break the UI.
   • Fix: Run both commands after installation or use make:elfinder (if available in your project).

2. Connector Caching:

   • The connector service is instantiated once. If you modify configure() dynamically (e.g., based on user input), cache the service or use a factory.

3. Path Configuration:

   • path must be an absolute filesystem path (e.g., /var/www/uploads).
   • URL must be the publicly accessible URL (e.g., /uploads).
   • Gotcha: Using relative paths (e.g., ./uploads) will fail.

4. Driver Compatibility:

   • The bundle ships with LocalFileSystem by default. For cloud storage (e.g., S3), install the elFinder S3 driver and configure it in roots.

5. CSRF Protection:

   • elFinder uses AJAX calls that may trigger Symfony’s CSRF protection. Disable it for the connector route:

     # config/routes.yaml
     al_custom_connector:
         path: /custom-connector
         defaults: { _controller: 'App\Controller\ElFinderController::connect' }
         methods: [GET, POST]
         requirements:
             _method: GET|POST
     

Debugging Tips

1. Check Connector Output:

   • Enable debug mode (APP_DEBUG=true) and inspect the JSON response at /custom-connector for errors.

2. Log Connector Configuration: Add this to your connector’s configure() method:

   error_log(print_r($options, true)); // Logs options to Symfony's error log.
   

3. Browser Console:

   • Open DevTools (F12) and check the Network tab for failed AJAX requests to the connector.

4. elFinder Console:

   • Use console.log(elFinder) in your init_script to inspect the elFinder instance.

Extension Points

1. Custom Drivers: Extend AlphaLemonElFinderBaseConnector to support non-standard storage (e.g., database files, API integrations).

2. Event Listeners: Subscribe to elFinder events (e.g., file uploads) using Symfony’s event dispatcher:

   // src/EventListener/ElFinderListener.php
   namespace App\EventListener;
   
   use Symfony\Component\HttpKernel\Event\RequestEvent;
   
   class ElFinderListener {
       public function onKernelRequest(RequestEvent $event) {
           if ($event->getRequest()->getPathInfo() === '/custom-connector') {
               // Custom logic (e.g., log uploads)
           }
       }
   }
   

   Register in config/services.yaml:

   services:
       App\EventListener\ElFinderListener:
           tags: ['kernel.event_listener', { event: 'kernel.request' }]
   

3. Twig Extensions: Create a Twig extension to dynamically generate elFinder configurations:

   // src/Twig/ElFinderExtension.php
   namespace App\Twig;
   
   class ElFinderExtension extends \Twig_Extension {
       public function getFunctions() {
           return [
               new \Twig_SimpleFunction('elfinder_config', [$this, 'getConfig']),
           ];
       }
   
       public function getConfig($options) {
           return json_encode($options);
       }
   }
   

   Use in Twig:

   {% block init_script %}
       <script>
           $(document).ready(function() {
               $('<div/>').elfinder({
                   url: '/custom-connector',
                   config: {{ elfinder_config({'lang': 'en', 'width': '100%'}) }}
               });
           });
       </script>
   {% endblock %}
   

Performance Tips

1. Disable Thumbnails for Large Directories: Set 'thumbnailSize' to false in roots if thumbnails are unnecessary.

2. Lazy-Load Roots: Dynamically load roots based on user roles to reduce connector overhead:

   protected function configure() {
       $roots = [];
       if ($this->container->get('security.authorization_checker')->isGranted('ROLE_ADMIN')) {
           $roots[] = ['driver' => 'LocalFileSystem', 'path' => '/admin-files', ...];
       }
       return ['roots' => $roots];
   }
   

3. Cache Connector Responses: Use Symfony’s HTTP cache for the connector route if the file structure rarely changes:

   # config/routes.yaml
   al