Symfony3 File Uploader Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Symfony 2.0.x project via Composer:

   composer require punkave/file-uploader-bundle
   

   Register the bundle in app/AppKernel.php:

   new PunkAve\FileUploaderBundle\PunkAveFileUploaderBundle(),
   

2. Configuration Configure the uploader in app/config/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
       image_sizes: [small: [100, 100], medium: [400, 400]]
   

3. First Use Case Add the uploader to a form in a Twig template:

   {{ punkave_file_uploader_form({
       'name': 'document_upload',
       'max_file_count': 5,
       'image_sizes': ['small', 'medium']
   }) }}
   

Implementation Patterns

Workflows

1. Basic File Upload

   • Use the punkave_file_uploader_form Twig helper in your form.
   • Submit the form to handle file processing via the PunkAveFileUploaderBundle controller logic.

2. Image Resizing

   • Configure image_sizes in config.yml to auto-generate thumbnails.
   • Access resized images via:

     {{ punkave_file_uploader_image(file, 'small') }}
     

3. File Management

   • Display existing files in a form for re-uploads:

     {{ punkave_file_uploader_existing_files(form) }}
     

   • Handle file deletion via the delete action in the uploader controller.

4. Form Integration

   • Sync file uploads with form submission using the sync option:

     {{ punkave_file_uploader_form({
         'name': 'product_images',
         'sync': true
     }) }}
     

Integration Tips

• Custom Validation Extend the uploader’s validation by overriding the PunkAve\FileUploaderBundle\Validator\Constraints\File constraint in your own bundle or service.

• Event Listeners Subscribe to punkave_file_uploader.pre_upload and punkave_file_uploader.post_upload events for custom logic:

  services:
      app.file_uploader_listener:
          class: AppBundle\EventListener\FileUploaderListener
          tags:
              - { name: kernel.event_listener, event: punkave_file_uploader.pre_upload, method: onPreUpload }
  

• Asset Management Use the punkave_file_uploader_assets Twig function to include BlueImp’s JS/CSS:

  {{ punkave_file_uploader_assets() }}
  

Gotchas and Tips

Pitfalls

1. IE Compatibility

   • IE < 10 lacks multi-file support. Users can only upload single files sequentially.
   • Test thoroughly in IE10+ and provide fallback instructions for older versions.

2. File Overwrites

   • The bundle does not auto-rename duplicate filenames. Handle collisions manually in a pre-upload listener or via custom logic.

3. Symfony 3+ Deprecation

   • This bundle is not compatible with Symfony 3/4/5. Use alternatives like VichUploaderBundle for modern projects.

4. CSRF Issues

   • Ensure your form includes {{ form_start(form, { attr: {'enctype': 'multipart/form-data'} }) }} to avoid CSRF token errors during uploads.

5. Permission Errors

   • Verify upload_dir permissions (e.g., chmod 777 -R uploads/). PHP-FPM may need write access to the directory.

Debugging

• Log Uploads Enable debug mode and check app/logs/dev.log for upload errors (e.g., file size limits, MIME type restrictions).

• BlueImp Console Errors Inspect browser console for BlueImp-specific errors (e.g., FileUpload object failures). Common fixes:

  • Ensure jQuery and BlueImp JS are loaded before the uploader.
  • Check for conflicts with other JS libraries (e.g., jQuery UI).

Extension Points

1. Custom Storage Override the PunkAve\FileUploaderBundle\Storage\FileStorage service to use S3, database storage, etc.:

   services:
       app.custom_storage:
           class: AppBundle\Storage\CustomStorage
           arguments: ["@punkave_file_uploader.storage.file"]
           tags:
               - { name: punkave_file_uploader.storage }
   

2. Template Overrides Extend Twig templates by copying them from PunkAveFileUploaderBundle/Resources/views/ to AppBundle/Resources/PunkAveFileUploaderBundle/views/.

3. Post-Processing Use the post_upload event to trigger actions like:

   • Generating PDF previews.
   • Indexing files in Elasticsearch.
   • Sending notifications.

Configuration Quirks

• Dynamic upload_dir Use %kernel.root_dir% or environment variables for flexibility:

  upload_dir: "%env(UPLOAD_DIR)%/uploads"
  

• MIME Type Whitelisting Be explicit with allowed_mime_types to block malicious uploads. Example:

  allowed_mime_types: ["image/jpeg", "image/png", "application/pdf", "application/msword"]
  

• Memory Limits Large files may hit PHP’s memory_limit. Increase it temporarily for uploads:

  ini_set('memory_limit', '256M');