Uploaderbundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require cekurte/uploaderbundle
   

   Add to config/bundles.php:

   return [
       // ...
       Cekurte\UploaderBundle\CekurteUploaderBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console cekurte:uploader:install
   

   Update config/packages/cekurte_uploader.yaml to match your LiipImagineBundle and OneupUploaderBundle setups.

3. First Use Case

   • Use the provided Twig extension to render the uploader:

     {{ render(cekurte_uploader('image_field', {
         'upload_url': path('oneup_uploader_upload', {'fieldName': 'image_field'}),
         'preview_url': path('cekurte_uploader_preview', {'fieldName': 'image_field'}),
         'delete_url': path('oneup_uploader_delete', {'fieldName': 'image_field'}),
         'max_size': 2097152,
         'allowed_types': ['image/jpeg', 'image/png']
     })) }}
     

Implementation Patterns

Workflows

1. Form Integration

   • Use the bundle with Symfony forms:

     $builder->add('image', FileType::class, [
         'mapped' => false,
         'required' => false,
     ]);
     

   • Ensure the form field name matches the fieldName in the Twig template.

2. Ajax Preview Handling

   • The bundle automatically triggers a preview request after upload via oneup_uploader_upload.
   • Configure the preview route in routing.yaml:

     cekurte_uploader_preview:
         path: /upload/preview/{fieldName}
         methods: [POST]
         defaults: { _controller: 'CekurteUploaderBundle:Uploader:preview' }
     

3. Image Processing

   • Leverage LiipImagineBundle filters in the config:

     cekurte_uploader:
         image_filters:
             thumbnail: { filter: 'thumbnail', options: { size: [200, 200] } }
     

Integration Tips

• Validation: Extend the bundle’s validator to add custom rules for file types/sizes.
• Storage: Use OneupUploaderBundle’s storage adapters (e.g., AWS S3) via config:

  oneup_uploader:
      mappings:
          image_field:
              frontend: oneup_uploader_frontend
              storage: oneup_uploader_storage
  

• Twig Extensions: Customize the preview template by overriding: templates/CekurteUploaderBundle/Uploader/preview.html.twig.

Gotchas and Tips

Pitfalls

1. Route Conflicts

   • Ensure oneup_uploader_upload, oneup_uploader_delete, and cekurte_uploader_preview routes are unique.
   • Debug with php bin/console debug:router if previews fail.

2. CORS Issues

   • If using AJAX previews, configure CORS headers for the preview endpoint:

     # config/packages/nelmio_cors.yaml
     paths:
         '^/upload/preview':
             methods: [POST]
             allow_origin: ['*']
     

3. Image Filter Mismatch

   • Verify LiipImagineBundle filters exist in config/packages/liip_imagine.yaml before use.

Debugging

• Log Uploads: Enable debug mode to log upload events:

  cekurte_uploader:
      debug: true
  

• Preview Failures: Check browser console for 404s or CORS errors. Validate the preview_url path.

Extension Points

1. Custom Preview Logic Override the preview controller:

   // src/Controller/UploaderPreviewController.php
   namespace App\Controller;
   use Cekurte\UploaderBundle\Controller\UploaderController;
   
   class UploaderPreviewController extends UploaderController {
       public function previewAction(Request $request, $fieldName) {
           // Custom logic (e.g., add watermarks)
           return parent::previewAction($request, $fieldName);
       }
   }
   

   Update routing to point to your controller.

2. Event Listeners Subscribe to cekurte.uploader.pre_upload or cekurte.uploader.post_upload events for pre/post-processing:

   // src/EventListener/UploaderListener.php
   use Cekurte\UploaderBundle\Event\UploadEvent;
   
   class UploaderListener {
       public function onUpload(UploadEvent $event) {
           $file = $event->getFile();
           // Modify $file or $event->stopPropagation();
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\UploaderListener:
           tags:
               - { name: kernel.event_listener, event: cekurte.uploader.post_upload, method: onUpload }
   

3. Asset Configuration Dynamically set allowed types/sizes via Twig:

   {{ render(cekurte_uploader('image_field', {
       'allowed_types': app.parameter('allowed_image_types'),
       'max_size': app.parameter('max_image_size')
   })) }}