Filemanager Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require adsign/filemanager-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Adsign\FileManagerBundle\AdsignFileManagerBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Create a config file at config/packages/adsign_filemanager.yaml:

   adsign_filemanager:
       directories:
           default:
               path: '%kernel.project_dir%/public/uploads'
               acl: true
               upload_formats: ['jpg', 'png', 'gif']
   

3. First Use Case: Embedding in a Twig Template

   {{ render(controller('AdsignFileManagerBundle:Default:index', {
       'config': 'default',
       'tree': true,
       'view': 'list'
   })) }}
   

Key First Steps

• Run migrations (if using database storage):

  php bin/console doctrine:migrations:diff
  php bin/console doctrine:migrations:migrate
  

• Clear cache:

  php bin/console cache:clear
  

• Access the file manager at /filemanager (default route).

Implementation Patterns

Core Workflows

1. File Upload Integration

• Twig Integration:

  {{ render(controller('AdsignFileManagerBundle:Default:upload', {
      'config': 'default',
      'targetUrl': path('your_upload_handler')
  })) }}
  

• Custom Upload Handler (Symfony Controller):

  use Adsign\FileManagerBundle\Manager\FileManager;
  
  public function uploadHandler(Request $request, FileManager $fileManager)
  {
      $response = $fileManager->upload($request, 'default');
      return new JsonResponse($response);
  }
  

2. TinyMCE Integration

• Configure TinyMCE to use the file manager:

  tinymce.init({
      selector: 'textarea',
      plugins: 'filemanager',
      external_filemanager_path: '/filemanager',
      filemanager_title: 'File Manager',
      external_plugins: {
          'filemanager': '/filemanager/tinymce4/plugin.min.js'
      }
  });
  

• Ensure the tinymce plugin is enabled in config/packages/adsign_filemanager.yaml:

  adsign_filemanager:
      tinymce: true
  

3. Dynamic Configurations

• Runtime Configuration:

  $config = [
      'path' => $customPath,
      'acl' => false,
      'upload_formats' => ['pdf', 'docx'],
      'max_file_size' => '10M'
  ];
  $fileManager->setConfig($config);
  

4. File Operations in Controllers

• Upload a File:

  $fileManager->upload($request, 'default');
  

• Delete a File:

  $fileManager->delete('default', 'path/to/file.jpg');
  

• Get File URL:

  $url = $fileManager->getUrl('default', 'path/to/file.jpg');
  

5. Tree View with Custom Root

• Override the root directory in Twig:

  {{ render(controller('AdsignFileManagerBundle:Default:index', {
      'config': 'default',
      'tree': true,
      'root': '/custom/root/path'
  })) }}
  

Integration Tips

Symfony Forms

• Use the FileManagerType for file upload fields:

  use Adsign\FileManagerBundle\Form\Type\FileManagerType;
  
  $builder->add('document', FileManagerType::class, [
      'config' => 'default',
      'multiple' => true,
      'required' => false
  ]);
  

API Endpoints

• Expose file manager actions via API:

  # config/routes.yaml
  adsign_filemanager_api:
      resource: '@AdsignFileManagerBundle/Resources/config/routing/api.yaml'
      prefix: /api/filemanager
  

Custom ACL Logic

• Extend the ACL service:

  services:
      app.file_manager.acl:
          class: App\Service\CustomAclService
          tags:
              - { name: adsign_filemanager.acl }
  

  Implement Adsign\FileManagerBundle\Service\AclInterface.

Thumbnail Generation

• Configure thumbnail sizes in config/packages/adsign_filemanager.yaml:

  adsign_filemanager:
      thumbnails:
          small: [100, 100]
          medium: [300, 300]
  

Gotchas and Tips

Pitfalls

1. Permission Issues

• Symptom: Uploads fail silently or return 403 errors.
• Fix: Ensure the web server user (e.g., www-data) has write permissions to the upload directory:

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

  For private folders, verify ACL settings in the config.

2. Missing JavaScript/CSS Assets

• Symptom: File manager UI is broken or non-functional.
• Fix: Run composer dump-autoload and clear the cache:

  php bin/console assets:install
  php bin/console cache:clear
  

  Ensure assets are published:

  php bin/console adsign:filemanager:assets:install
  

3. Multilingual Route Conflicts

• Symptom: Routes fail to generate in multilingual apps.
• Fix: Explicitly define routes in config/routes.yaml:

  adsign_filemanager:
      resource: '@AdsignFileManagerBundle/Resources/config/routing.yml'
      prefix: /{_locale}
      requirements:
          _locale: en|fr
  

4. File Size Limits

• Symptom: Large files fail to upload with no clear error.
• Fix: Adjust PHP and Nginx/Apache limits:

  # php.ini
  upload_max_filesize = 20M
  post_max_size = 20M
  

  For Nginx, add to server block:

  client_max_body_size 20M;
  

5. Database Storage Issues

• Symptom: File metadata not saved or corrupted.
• Fix: Ensure Doctrine is properly configured and migrations are up-to-date:

  php bin/console doctrine:schema:update --force
  

Debugging Tips

1. Enable Debug Mode

• Add to config/packages/dev/adsign_filemanager.yaml:

  adsign_filemanager:
      debug: true
  

  This logs file operations to var/log/dev.log.

2. Check Upload Errors

• Inspect the blueimp upload logs:

  $.blueimp.fileupload.prototype.options.done = function(e, data) {
      console.log('Upload response:', data.result);
  };
  

3. Validate Config

• Use the validate command:

  php bin/console adsign:filemanager:validate
  

4. Clear Thumbnail Cache

• If thumbnails appear broken:

  rm -rf %kernel.project_dir%/public/uploads/thumbs/*
  

Extension Points

1. Custom File Filter

• Extend the FileFilter service:

  services:
      app.custom_file_filter:
          class: App\Service\CustomFileFilter
          tags:
              - { name: adsign_filemanager.file_filter }
  

  Implement Adsign\FileManagerBundle\Filter\FileFilterInterface.

2. Event Listeners

• Listen to file upload events:

  use Adsign\FileManagerBundle\Event\FileUploadEvent;
  
  public function onFileUpload(FileUploadEvent $event)
  {
      if ($event->getFile()->getExtension() === 'pdf') {
          $event->setAllowed(true);
      }
  }
  

  Register in services.yaml:

  services:
      App\EventListener\FileUploadListener:
          tags:
              - { name: kernel.event_listener, event: adsign.filemanager.upload, method: onFileUpload }
  

3. Override Templates

• Copy templates from vendor/adsign/filemanager-bundle/Resources/views/ to templates/AdsignFileManagerBundle/Default/ to customize.

4. Custom Storage Adapter

• Implement Adsign\FileManagerBundle\Storage\StorageInterface for S3, FTP, etc.:

  services:
      app.s3_storage:
          class: App\Storage\S3Storage