Symfony2 File Uploader Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require punkave/symfony2-file-uploader-bundle
   

   Add to AppKernel.php:

   new Punkave\FileUploaderBundle\PunkaveFileUploaderBundle(),
   

2. Basic Configuration Update config.yml:

   punkave_file_uploader:
       upload_dir: "%kernel.root_dir%/../web/uploads"
       allowed_mime_types: ['image/jpeg', 'image/png', 'application/pdf']
       max_file_size: 10M
   

3. First Use Case: File Upload Form

   {{ form_start(form) }}
       {{ form_widget(form.files) }}  <!-- Auto-generates BlueImp uploader -->
       <button type="submit">Upload</button>
   {{ form_end(form) }}
   

   Controller:

   use Punkave\FileUploaderBundle\Form\Type\FileUploaderType;
   
   public function editAction(Request $request) {
       $form = $this->createForm(FileUploaderType::class, $entity);
       if ($form->handleRequest($request)->isSubmitted()) {
           $files = $form->get('files')->getData(); // Array of UploadedFile
           // Process files...
       }
       return $this->render('...', ['form' => $form->createView()]);
   }
   

Implementation Patterns

Common Workflows

1. Multi-Step File Handling

   // Controller: Process files in chunks
   $uploader = $this->get('punkave_file_uploader.uploader');
   foreach ($request->files->get('files') as $file) {
       $uploadedFile = $uploader->upload($file, 'user_avatars');
       $entity->addAvatar($uploadedFile);
   }
   

2. Existing File Management

   {% for file in entity.files %}
       <div class="file-entry">
           <a href="{{ asset(file.path) }}">{{ file.name }}</a>
           <button data-file-id="{{ file.id }}">Remove</button>
       </div>
   {% endfor %}
   

   JavaScript (BlueImp integration):

   $('.file-entry button').click(function() {
       var fileId = $(this).data('file-id');
       $.ajax({
           url: '/delete-file/' + fileId,
           method: 'DELETE'
       });
   });
   

3. Dynamic Upload Directories

   # config.yml
   punkave_file_uploader:
       dynamic_upload_dirs:
           user_avatars: "%kernel.root_dir%/../web/uploads/avatars"
           documents: "%kernel.root_dir%/../web/uploads/docs"
   

   Controller:

   $uploader->upload($file, 'user_avatars'); // Auto-resolves path
   

4. Validation Integration

   $builder->add('files', FileUploaderType::class, [
       'constraints' => [
           new File([
               'maxSize' => '10M',
               'mimeTypes' => ['image/jpeg', 'image/png'],
               'mimeTypesMessage' => 'Only JPG/PNG allowed',
           ]),
       ],
   ]);
   

Gotchas and Tips

Pitfalls

1. File Overwrite Handling

   • By default, files with duplicate names overwrite. Use unique_filename: true in config to append timestamps:

     punkave_file_uploader:
         unique_filename: true
     

2. CSRF Token Mismatch

   • Ensure BlueImp uploader includes CSRF token in AJAX requests:

     $.ajaxSetup({
         headers: { 'X-CSRF-Token': $('meta[name="csrf-token"]').attr('content') }
     });
     

3. Memory Limits

   • Large uploads may hit PHP’s post_max_size/upload_max_filesize. Adjust in php.ini or use chunked uploads (see BlueImp docs).

4. Symfony 4+ Compatibility

   • Bundle assumes Symfony 2/3. For Symfony 4+, alias services in config/packages/punkave_file_uploader.yaml:

     services:
         Punkave\FileUploaderBundle\Service\Uploader:
             alias: punkave_file_uploader.uploader
     

Debugging Tips

1. Log Upload Paths Enable debug mode to log file paths:

   punkave_file_uploader:
       debug: true
   

2. Check File Permissions Ensure upload_dir is writable:

   chmod -R 775 %kernel.root_dir%/../web/uploads
   

3. Validate MIME Types Use fileinfo extension for accurate MIME detection:

   $mime = finfo_file(finfo_open(FILEINFO_MIME_TYPE), $file->getPathname());
   

Extension Points

1. Custom File Processor Override the uploader service to add preprocessing:

   # config/services.yaml
   Punkave\FileUploaderBundle\Service\Uploader:
       arguments:
           $processor: '@app.custom_file_processor'
   

   // src/Service/CustomFileProcessor.php
   class CustomFileProcessor implements FileProcessorInterface {
       public function process(UploadedFile $file): UploadedFile {
           // Resize images, etc.
           return $file;
       }
   }
   

2. Event Listeners Listen to upload events for post-processing:

   // src/EventListener/FileUploadListener.php
   class FileUploadListener {
       public function onUpload(FileUploadEvent $event) {
           $file = $event->getFile();
           // Generate thumbnails, etc.
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\FileUploadListener:
           tags:
               - { name: 'kernel.event_listener', event: 'punkave.file_upload', method: 'onUpload' }
   

3. Twig Extensions Add custom filters for file URLs:

   // src/Twig/AppExtension.php
   class AppExtension extends \Twig\Extension\AbstractExtension {
       public function getFilters() {
           return [
               new \Twig\TwigFilter('file_url', [$this, 'getFileUrl']),
           ];
       }
       public function getFileUrl($file) {
           return $this->container->get('punkave_file_uploader.uploader')->getUrl($file);
       }
   }
   

   Usage in Twig:

   <img src="{{ file_url(file) }}" alt="{{ file.name }}">