Filemanager Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require artgris/filemanager-bundle
   

2. Enable Routes in config/routes.yaml:

   artgris_bundle_file_manager:
       resource: "@ArtgrisFileManagerBundle/Controller"
       type: attribute
       prefix: /manager
   

3. Configure Default Storage in config/packages/artgris_file_manager.yaml:

   artgris_file_manager:
       conf:
           default:
               dir: '%kernel.project_dir%/public/uploads'
   

4. Enable Translator in config/packages/translation.yaml:

   framework:
       translator: { fallbacks: ["en"] }
   

5. Create Uploads Directory:

   mkdir -p public/uploads
   

First Use Case

Access the file manager at /manager/?conf=default to upload files, create folders, and manage assets.

Implementation Patterns

Core Workflows

1. Multi-Configuration Management Define multiple configurations in artgris_file_manager.yaml for different storage needs (e.g., media, documents):

   artgris_file_manager:
       conf:
           media:
               dir: '%kernel.project_dir%/public/media'
               allow_uploaded_files: ['jpg', 'png', 'gif']
           documents:
               dir: '%kernel.project_dir%/public/docs'
               allow_uploaded_files: ['pdf', 'docx']
   

   Access via /manager/?conf=media.

2. Integration with CKEditor/TinyMCE Use the provided tutorials to embed the file manager as a button in editors:

   • TinyMCE Integration
   • FOSCKEditor Integration

3. Dynamic File URL Generation Use the artgris_file_manager.url_generator service to generate URLs for uploaded files:

   $url = $this->container->get('artgris_file_manager.url_generator')->generateUrl(
       'default',
       'path/to/file.jpg'
   );
   

4. Event-Driven Extensions Subscribe to events (e.g., file.uploaded) to extend functionality:

   // config/services.yaml
   services:
       App\EventListener\FileUploadListener:
           tags:
               - { name: kernel.event_listener, event: artgris_file_manager.file.uploaded, method: onFileUploaded }
   

Common Patterns

• Private vs. Public Folders: Use private: true in config to restrict access.
• File Sanitization: Enable slugger/sanitizer via:

  artgris_file_manager:
      conf:
          default:
              sanitize_filename: true
  

• Tree View: Toggle folder tree visibility with show_tree: true.

Gotchas and Tips

Pitfalls

1. Directory Permissions Ensure the configured directory (public/uploads) is writable by the web server:

   chmod -R 775 public/uploads
   

   Symptom: Uploads fail silently or throw Permission denied errors.

2. URL Generation Edge Cases

   • Private Files: Use generatePrivateUrl() for private files to avoid 404s.
   • Path Traversal: Always validate paths server-side to prevent directory traversal attacks.

3. Multilingual Quirks

   • Translations may not load if fallbacks in translation.yaml is misconfigured.
   • Test all supported languages (en, fr, es, etc.) to ensure UI consistency.

4. File Size Limits

   • Default limits are inherited from blueimp/jQuery-File-Upload. Override in config:

     artgris_file_manager:
         conf:
             default:
                 max_file_size: 10M  # 10MB
     

Debugging Tips

1. Log Upload Events Enable Symfony’s profiler to inspect file upload events:

   framework:
       profiler: { only_exceptions: false }
   

   Check the "Events" tab in the profiler for artgris_file_manager.* events.

2. Check File Paths Use var_dump() in a custom event listener to debug file paths:

   public function onFileUploaded(FileUploadEvent $event) {
       var_dump($event->getFile()->getPathname());
   }
   

3. Clear Cache After Config Changes Run:

   php bin/console cache:clear
   

   Symptom: Configuration changes (e.g., allow_uploaded_files) are ignored.

Extension Points

1. Custom ACLs Override the Artgris\FileManagerBundle\Security\AccessControl service to implement role-based access:

   services:
       App\Security\CustomAccessControl:
           decorates: artgris_file_manager.access_control
           arguments: ['@artgris_file_manager.access_control.inner']
   

2. File Validation Extend the FileValidator service to add custom rules (e.g., virus scanning):

   public function validate(File $file) {
       if ($file->getMimeType() === 'image/jpeg' && $file->getSize() > 5M) {
           throw new \RuntimeException('JPEGs must be <5MB');
       }
   }
   

3. Theming Override Twig templates in templates/artgris_file_manager/ to customize the UI (e.g., change Bootstrap classes).

4. File Preview Extend preview logic for non-image files (e.g., PDFs) by overriding the FilePreviewer service.

Pro Tips

• Use Multiple Configs for Environments

  # config/packages/dev/artgris_file_manager.yaml
  artgris_file_manager:
      conf:
          dev_media:
              dir: '%kernel.project_dir%/public/dev-media'
  

• Leverage Events for Auditing Log file changes to a database in onFileUploaded/onFileDeleted listeners.
• Disable Tree View for Performance Set show_tree: false in config for large directories to reduce load times.