Ux Dropzone Laravel Package

Getting Started

Minimal Steps

1. Install the Package:

   composer require symfony/ux-dropzone
   npm install @symfony/ux-dropzone  # For frontend assets
   

   Ensure your package.json includes the correct path to the assets directory (e.g., "assets/src").

2. Configure Symfony UX: Add the bundle to config/bundles.php (Symfony) or ensure it’s auto-discovered:

   return [
       // ...
       Symfony\UX\Dropzone\DropzoneBundle::class => ['all' => true],
   ];
   

3. Enable Stimulus Controller: Register the Dropzone controller in your Stimulus configuration (e.g., assets/controllers.json):

   {
       "controllers": {
           "dropzone": ["assets/controllers/dropzone_controller.js"]
       }
   }
   

4. Basic Form Integration: Use the DropzoneType in a Symfony Form:

   use Symfony\UX\Dropzone\DropzoneType;
   
   $builder->add('files', DropzoneType::class, [
       'label' => 'Upload Files',
       'multiple' => true,
       'mime_types' => ['image/*', 'application/pdf'],
       'max_size' => '10M',
   ]);
   

5. Render the Form: Ensure your template includes the Stimulus bridge and Dropzone assets:

   {{ include('bundles/SymfonyUxDropzone/dropzone.html.twig') }}
   {{ include('bundles/SymfonyUxDropzone/dropzone_controller.html.twig') }}
   

6. Handle Uploads in Controller: Symfony will automatically handle file uploads via UploadedFile objects:

   public function upload(Request $request): Response
   {
       $form = $this->createFormBuilder()
           ->add('files', DropzoneType::class)
           ->getForm();
   
       $form->handleRequest($request);
       if ($form->isSubmitted() && $form->isValid()) {
           $files = $form->get('files')->getData();
           // Process $files (array of UploadedFile objects)
       }
       // ...
   }
   

First Use Case

Replace a traditional file input with drag-and-drop functionality in a user profile picture upload form. This reduces friction for users uploading images and leverages Symfony’s validation pipeline for file constraints (e.g., max size, allowed types).

Implementation Patterns

Usage Patterns

1. Basic Dropzone Integration

• Use DropzoneType in Symfony Forms for simple drag-and-drop uploads.
• Example:

  $builder->add('profile_picture', DropzoneType::class, [
      'label' => 'Drag and drop your profile picture',
      'mime_types' => ['image/jpeg', 'image/png'],
      'max_size' => '2M',
      'required' => false,
  ]);
  

2. Multiple File Uploads

• Enable multiple: true to allow users to upload multiple files at once.
• Example:

  $builder->add('documents', DropzoneType::class, [
      'label' => 'Upload multiple documents',
      'multiple' => true,
      'max_size' => '5M',
  ]);
  

3. Customizing Dropzone Behavior

• Use JavaScript to customize Dropzone options (e.g., auto-process queue, preview templates).
• Example (Stimulus controller):

  // assets/controllers/dropzone_controller.js
  import { Controller } from '@hotwired/stimulus';
  import Dropzone from '@symfony/ux-dropzone';
  
  export default class extends Controller {
      connect() {
          Dropzone.attach(this.element, {
              url: this.data.get('url'),
              autoProcessQueue: true,
              previewTemplate: this.data.get('previewTemplate'),
          });
      }
  }
  

• Register options in Twig:

  {{ include('bundles/SymfonyUxDropzone/dropzone.html.twig', {
      'url': path('app_upload'),
      'previewTemplate': 'custom-preview-template.html.twig'
  }) }}
  

4. Integration with Symfony Validation

• Leverage Symfony’s constraints for file validation (e.g., File, Image, MaxSize).
• Example:

  use Symfony\Component\Validator\Constraints as Assert;
  
  $builder->add('resume', DropzoneType::class, [
      'constraints' => [
          new Assert\File([
              'maxSize' => '5M',
              'mimeTypes' => ['application/pdf'],
              'mimeTypesMessage' => 'Please upload a PDF file',
          ]),
      ],
  ]);
  

5. Chunked Uploads for Large Files

• Configure Dropzone to split large files into chunks for reliable uploads.
• Example (JavaScript):

  Dropzone.attach(this.element, {
      url: this.data.get('url'),
      chunking: true,
      chunkSize: 5 * 1024 * 1024, // 5MB chunks
      parallelUploads: 4,
  });
  

6. Fallback for Non-JavaScript Users

• Dropzone automatically falls back to a traditional <input type="file"> if JavaScript is disabled.
• Ensure your form remains functional without JavaScript by testing in a browser with JS disabled.

Workflows

Typical Laravel-Symfony Hybrid Workflow

1. Form Creation:

   • Use Symfony’s FormFactory to create a form with DropzoneType.
   • Example:

     $form = $this->createFormBuilder()
         ->add('files', DropzoneType::class, [
             'mime_types' => ['image/*'],
             'max_size' => '10M',
         ])
         ->getForm();
     

2. Rendering the Form:

   • Use Twig to render the form and include Dropzone assets:

     {{ form_start(form) }}
         {{ form_row(form.files) }}
         {{ include('bundles/SymfonyUxDropzone/dropzone.html.twig', {
             'url': path('app_upload'),
         }) }}
     {{ form_end(form) }}
     

3. Handling Uploads:

   • Process UploadedFile objects in the controller:

     public function handleUpload(Request $request): Response
     {
         $form = $this->createFormBuilder()
             ->add('files', DropzoneType::class)
             ->getForm();
     
         $form->handleRequest($request);
         if ($form->isSubmitted() && $form->isValid()) {
             $files = $form->get('files')->getData();
             foreach ($files as $file) {
                 $file->move($targetDir, $file->getClientOriginalName());
             }
         }
         // ...
     }
     

4. Frontend Asset Management:

   • Use Laravel Mix/Vite to compile Dropzone assets:

     // vite.config.js
     export default defineConfig({
         plugins: [
             symfonyBridge({
                 entry: [
                     './assets/controllers.json',
                     './assets/app.js',
                 ],
             }),
         ],
     });
     

Integration Tips

Laravel-Specific Tips

1. Symfony Form in Laravel:

   • Use symfony/form or laravel/symfony-bridge to integrate Symfony Forms into Laravel.
   • Example:

     composer require symfony/form laravel/symfony-bridge
     

2. Blade Template Integration:

   • Create a custom Blade directive or view composer to render Symfony Form widgets:

     // app/Providers/AppServiceProvider.php
     public function boot()
     {
         Blade::directive('symfonyForm', function ($expression) {
             return "<?php echo \$this->renderSymfonyForm($expression); ?>";
         });
     }
     

3. Asset Mapping:

   • Use Laravel’s asset mapper to include Dropzone assets:

     {# In Twig templates #}
     {{ asset('bundles/symfonyuxdropzone/dropzone.css') }}
     {{ asset('bundles/symfonyuxdropzone/dropzone.js') }}
     

4. Stimulus Bridge:

   • Ensure the Stimulus bridge is loaded in your Laravel app:

     <script src="{{ asset('build/stimulus.js') }}"></script>
     

Symfony-Specific Tips

1. AssetMapper Integration:

   • Use Symfony’s asset-mapper for modern asset handling:

     # config/packages/framework.yaml
     framework:
         assets:
             packages:
                 dropzone:
                     json_manifest_path: '%kernel.project_dir%/public/build/assets.json'
     

2. Twig Extensions:

   • Extend Twig to simplify Dropzone integration:

     // src/Twig/Extension/DropzoneExtension.php
     class DropzoneExtension extends AbstractExtension
     {
         public function getFunctions()
         {
             return [
                 new TwigFunction('dropzone', [$this,