File Manager Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ekyna/file-manager-bundle
   

   Add to config/bundles.php:

   Ekyna\FileManagerBundle\EkynaFileManagerBundle::class => ['all' => true],
   

2. Routing: Ensure the bundle’s routes are imported in config/routes.yaml:

   ekyna_file_manager:
       resource: "@EkynaFileManagerBundle/Resources/config/routing.yml"
       prefix: /admin/file-manager
   

3. First Use Case: Embed the file manager in a form via Twig:

   {{ form_widget(form.file_field) }}
   <script>
       $(document).ready(function() {
           $('#file_field').fileManager({
               url: '{{ path('ekyna_file_manager_browser') }}',
               uploadUrl: '{{ path('ekyna_file_manager_upload') }}',
               deleteUrl: '{{ path('ekyna_file_manager_delete') }}'
           });
       });
   </script>
   

Implementation Patterns

Common Workflows

1. File Uploads:

   • Use the uploadUrl endpoint for direct uploads from a form or AJAX calls.
   • Validate file types/sizes in a custom controller or via Symfony’s File constraint:

     use Symfony\Component\Validator\Constraints\File;
     
     $constraints = new File([
         'maxSize' => '1024k',
         'mimeTypes' => ['image/jpeg', 'image/png'],
     ]);
     

2. File Browsing:

   • Customize the browser view by extending the template:

     {% extends '@EkynaFileManager/FileManager/browser.html.twig' %}
     {% block file_row %}
         <tr>
             <td>{{ file.name }}</td>
             <td>{{ file.size|filesize }}</td>
             <td>{{ file.mimeType }}</td>
             <td>
                 <a href="{{ path('ekyna_file_manager_download', {'id': file.id}) }}">Download</a>
             </td>
         </tr>
     {% endblock %}
     

3. Permissions:

   • Override the security voter or ACL logic in a custom service:

     # config/services.yaml
     Ekyna\FileManagerBundle\Security\FileManagerVoter:
         arguments:
             - '@security.token_storage'
             - ['ROLE_FILE_MANAGER_EDIT']
     

4. Integration with Forms:

   • Use the file_manager type for Symfony forms:

     $builder->add('document', 'file_manager', [
         'url' => $this->generateUrl('ekyna_file_manager_browser'),
         'upload_url' => $this->generateUrl('ekyna_file_manager_upload'),
         'allowed_mime_types' => ['application/pdf'],
     ]);
     

Gotchas and Tips

Pitfalls

1. Outdated Dependencies:

   • The bundle relies on old Symfony (2.x) components. Use a compatibility layer like symfony/polyfill if integrating with Symfony 4/5/6:

     composer require symfony/polyfill-*
     

2. Missing Documentation:

   • The TODO sections in the README imply incomplete features. Refer to the Symfony CMF FileManagerBundle for modern alternatives.

3. Permission Quirks:

   • Default ACLs are minimal. Extend the FileManagerVoter to handle granular roles:

     public function supportsAttribute($attribute)
     {
         return in_array($attribute, ['EDIT', 'DELETE', 'VIEW']);
     }
     

4. Template Overrides:

   • Ensure template paths are correct. Override templates in:

     templates/bundles/ekynafilemanager/
     

Debugging Tips

• Check Routes: Run php bin/console debug:router | grep ekyna_file_manager to verify endpoints.

• Log Uploads: Enable debug mode and check var/log/dev.log for upload errors:

  // config/packages/dev/monolog.yaml
  handlers:
      main:
          type: stream
          path: "%kernel.logs_dir%/%kernel.environment%.log"
          level: debug
  

• File Storage: Default storage is app/Resources/files/. Change it via config (if available) or override the FileManager service:

  services:
      ekyna_file_manager.file_manager:
          arguments:
              - '%kernel.project_dir%/custom_uploads'
  

Extension Points

1. Custom File Model: Extend the Ekyna\FileManagerBundle\Entity\File entity to add metadata:

   namespace App\Entity;
   
   use Ekyna\FileManagerBundle\Entity\File as BaseFile;
   
   class File extends BaseFile
   {
       /**
        * @ORM\Column(type="string", length=255, nullable=true)
        */
       private $customMetadata;
   }
   

2. Event Listeners: Subscribe to file events (if supported) to trigger actions:

   // src/EventListener/FileManagerListener.php
   class FileManagerListener
   {
       public function onFileUpload(FileUploadEvent $event)
       {
           // Post-upload logic
       }
   }
   

3. API Integration: Use the bundle’s endpoints as a headless API by returning JSON responses:

   // src/Controller/FileManagerController.php
   public function uploadAction(Request $request)
   {
       $response = parent::uploadAction($request);
       $response->setContent(json_encode([
           'success' => true,
           'fileId' => $file->getId(),
       ]));
       return $response;
   }