Plupload Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require defrag/plupload-bundle:dev-master
   

   Add to AppKernel.php:

   new Defrag\PluploadBundle\DefragPluploadBundle(),
   

2. Basic Configuration (config.yml):

   defrag_plupload:
       upload_service: your.upload_service_id  # Must implement `UploaderInterface`
       orm_class: Your\Bundle\Entity\YourEntity
   

3. First Use Case:

   • Create a form type extending Symfony\Component\Form\AbstractType.
   • Add the plupload field:

     $builder->add('assets', 'plupload');
     

   • Ensure your upload_service handles file processing (e.g., saving to disk/S3).

Implementation Patterns

Workflow Integration

1. Form Handling:

   • Use plupload field in forms for drag-and-drop/multiple uploads.
   • Example form type:

     use Defrag\PluploadBundle\Form\Type\PluploadType;
     
     class YourFormType extends AbstractType {
         public function buildForm(FormBuilderInterface $builder, array $options) {
             $builder->add('files', PluploadType::class, [
                 'label' => 'Upload Files',
                 'upload_service' => 'your.service_id', // Override config if needed
             ]);
         }
     }
     

2. Custom Upload Logic:

   • Implement UploaderInterface for your service:

     use Defrag\PluploadBundle\Mode\UploaderInterface;
     
     class YourUploader implements UploaderInterface {
         public function upload(array $files) { /* Handle files */ }
     }
     

   • Register as a service in services.yml:

     your.upload_service:
         class: Your\Uploader
         tags: ['defrag_plupload.uploader']
     

3. Twig Integration:

   • Include JS/CSS assets in your template:

     {{ defrag_plupload_js() }}
     {{ defrag_plupload_css() }}
     

   • Initialize Plupload via JS (check Resources/public/js/plupload.js for defaults).

4. Entity Association:

   • Use orm_class to auto-associate uploaded files with entities (e.g., Asset).
   • Example entity:

     /**
      * @ORM\Entity
      */
     class Asset {
         // Fields for file metadata (e.g., path, name)
     }
     

Gotchas and Tips

Pitfalls

1. Symfony Version Lock:

   • Only works with Symfony 2.0.x. Avoid in Symfony 3+ projects without forks.
   • Check composer.json for symfony/* version constraints.

2. UploaderInterface Strictness:

   • The upload_service must implement UploaderInterface exactly. Missing methods (e.g., upload()) will fail silently or throw errors.
   • Debug with:

     php bin/console debug:container your.upload_service
     

3. File Validation:

   • The bundle provides no built-in validation. Handle file types/sizes in your UploaderInterface implementation or via Symfony validators:

     $builder->add('assets', PluploadType::class, [
         'constraints' => [
             new File\FileType(['mime_types' => ['image/jpeg']]),
             new File\MaxSize('1024k'),
         ],
     ]);
     

4. ORM Integration Quirks:

   • If orm_class is set but the entity lacks required fields (e.g., path, name), uploads may succeed but associations will fail.
   • Example minimal entity:

     class Asset {
         /** @ORM\Column(type="string") */
         private $path;
         /** @ORM\Column(type="string") */
         private $name;
     }
     

5. JavaScript Conflicts:

   • Plupload’s default JS may conflict with other libraries (e.g., jQuery UI). Override templates in Resources/views or use custom JS:

     $('#your-plupload-container').pluploadQueue({
         // Custom config
     });
     

Debugging Tips

1. Check Upload Events:

   • Plupload emits events like UploadFile and Error. Listen in JS:

     $('#plupload-container').bind('Error', function(up, err) {
         console.error('Upload error:', err);
     });
     

2. Log Upload Service Calls:

   • Decorate your UploaderInterface service to log inputs/outputs:

     your.upload_service:
         class: Your\Uploader
         decorates: your.upload_service
         arguments: ['@your.upload_service.inner']
     

3. Verify File Paths:

   • Use Symfony’s file_exists() or Storage components to confirm files are saved:

     if (!file_exists($filePath)) {
         throw new \RuntimeException("File not saved: $filePath");
     }
     

Extension Points

1. Custom Templates:

   • Override Plupload templates by copying Resources/views to your bundle and extending:

     {# app/Resources/DefragPluploadBundle/views/Type/plupload.html.twig #}
     {% extends 'DefragPluploadBundle:Type:plupload.html.twig' %}
     

2. Dynamic Config:

   • Pass runtime options to PluploadType:

     $builder->add('assets', PluploadType::class, [
         'upload_service' => 'dynamic.service',
         'options' => [
             'max_file_size' => '5mb',
             'multipart' => true,
         ],
     ]);
     

3. Chunked Uploads:

   • Enable for large files by configuring Plupload’s chunk_size in JS or via options:

     chunk_size: '1mb',
     upload_chunk_size: '1mb',