Dropzone Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require contao-components/dropzone
   

   Add the package to your config/app.php under providers:

   ContaoComponents\Dropzone\DropzoneServiceProvider::class,
   

2. Basic Blade Usage Include the package's CSS/JS in your layout file (e.g., resources/views/layouts/app.blade.php):

   @dropzoneStyles
   @dropzoneScripts
   

3. First Dropzone Field In your Blade template:

   {!! Dropzone::create('file-upload', [
       'url' => route('upload.handler'),
       'maxFilesize' => 5, // MB
       'acceptedFiles' => 'image/*',
   ]) !!}
   

4. Backend Handler Create a route and controller to handle uploads:

   Route::post('/upload', [UploadController::class, 'handle'])->name('upload.handler');
   

   // UploadController.php
   public function handle(Request $request)
   {
       $file = $request->file('file');
       $path = $file->store('uploads');
   
       return response()->json(['success' => true, 'path' => $path]);
   }
   

Implementation Patterns

Common Workflows

1. File Processing Pipeline

Chain file handling logic with middleware or observers:

// app/Observers/FileUploadObserver.php
use ContaoComponents\Dropzone\Events\FileUploaded;

FileUploaded::listen(function ($event) {
    $file = $event->file;
    // Process (resize, validate, etc.)
    $event->processed = $file->storeAs('processed/' . $file->hashName());
});

2. Dynamic Configuration

Fetch Dropzone settings from a model or database:

@php
    $settings = \App\Models\UploadConfig::first();
@endphp
{!! Dropzone::create('dynamic-upload', [
    'url' => $settings->endpoint,
    'maxFiles' => $settings->limit,
    'headers' => ['X-CSRF-TOKEN' => csrf_token()],
]) !!}

3. Laravel Validation Integration

Validate files before processing:

public function handle(Request $request)
{
    $validated = $request->validate([
        'file.*' => 'required|image|mimes:jpeg,png|max:2048',
    ]);

    // Process validated files...
}

4. Chunked Uploads for Large Files

Enable chunked uploads in Dropzone config:

{!! Dropzone::create('large-file-upload', [
    'url' => route('chunked.upload'),
    'chunking' => true,
    'chunkSize' => 5 * 1024 * 1024, // 5MB chunks
]) !!}

Use a package like intervention/image for reassembly.

5. Preview Templates

Customize file previews in Blade:

@dropzonePreviewTemplate
    <div class="dz-preview dz-file-preview">
        <div class="dz-details">
            <div class="dz-filename"><span data-dz-name></span></div>
            <div class="dz-size" data-dz-size></div>
        </div>
        <div class="dz-progress"><span class="dz-upload" data-dz-uploadprogress></span></div>
        <div class="dz-error-message"><span data-dz-errormessage></span></div>
        @if($dropzone->getOption('acceptedFiles') === 'image/*')
            <div class="dz-thumbnail">
                <img data-dz-thumbnail />
            </div>
        @endif
    </div>
@enddropzonePreviewTemplate

Integration Tips

Laravel Mix/Webpack

Add Dropzone CSS/JS via Mix:

// resources/js/app.js
require('dropzone/dist/dropzone');

In webpack.mix.js:

mix.postCss('resources/css/app.css', 'public/css', [
    require('postcss-import'),
    require('tailwindcss'),
]);

Form Requests

Use Laravel’s FormRequest for complex validation:

// app/Http/Requests/UploadRequest.php
public function rules()
{
    return [
        'file.*' => ['required', 'dimensions:max_width=2000,max_height=2000'],
    ];
}

Storage Integration

Leverage Laravel’s filesystem:

$path = Storage::disk('s3')->putFile('uploads', $file);

Event Dispatching

Trigger custom events post-upload:

event(new \App\Events\FileUploaded($file, $user));

Gotchas and Tips

Pitfalls

1. CSRF Token Mismatch

• Issue: Dropzone AJAX requests may fail with 419 (CSRF token mismatch).
• Fix: Explicitly include the token in headers:

  {!! Dropzone::create('upload', [
      'headers' => ['X-CSRF-TOKEN' => csrf_token()],
  ]) !!}
  

2. File Size Limits

• Issue: PHP’s upload_max_filesize or post_max_size may throttle large files.
• Fix: Adjust php.ini or use chunked uploads:

  upload_max_filesize = 64M
  post_max_size = 64M
  

3. CORS Errors

• Issue: Cross-origin uploads (e.g., from a SPA) may fail.
• Fix: Configure CORS middleware:

  // app/Http/Middleware/Cors.php
  $allowedMethods = ['POST', 'OPTIONS'];
  

4. Missing Dependencies

• Issue: Dropzone requires dropzone.js and dropzone.css.
• Fix: Ensure assets are published:

  php artisan vendor:publish --tag=dropzone-assets
  

5. Queueing Uploads

• Issue: Long-running uploads block the request.
• Fix: Use Laravel queues:

  dispatch(new ProcessUpload($file))->onQueue('uploads');
  

Debugging Tips

1. Log Dropzone Events

Enable Dropzone debug mode:

{!! Dropzone::create('debug-upload', [
    'debug' => true,
]) !!}

Check browser console for errors.

2. Validate File Input

Inspect $request->all() in your handler:

dd($request->input());

3. Check Storage Permissions

Ensure the target directory is writable:

chmod -R 775 storage/app/public/uploads

4. Test with Postman

Manually test the upload endpoint:

curl -X POST -F "file=@/path/to/file.jpg" http://yoursite.test/upload

Extension Points

1. Custom Dropzone Class

Extend the base Dropzone class:

// app/Extensions/CustomDropzone.php
namespace App\Extensions;

use ContaoComponents\Dropzone\Dropzone;

class CustomDropzone extends Dropzone
{
    public function __construct($elementId, array $options = [])
    {
        $options['autoProcessQueue'] = false;
        parent::__construct($elementId, $options);
    }

    public function getCustomOption()
    {
        return $this->options['custom_key'] ?? null;
    }
}

Register the extension in DropzoneServiceProvider:

$this->app->bind('dropzone', function () {
    return new \App\Extensions\CustomDropzone('custom-upload');
});

2. Dynamic URL Generation

Override the upload URL dynamically:

@php
    $dropzone = Dropzone::create('dynamic-url', [
        'url' => function () {
            return route('upload', ['folder' => 'user-' . auth()->id()]);
        },
    ]);
@endphp

3. Event Listeners

Listen for Dropzone events (e.g., addedfile, success):

Dropzone.options.myDropzone = {
    init: function() {
        this.on("addedfile", function(file) {
            console.log("File added:", file.name);
        });
    }
};

4. Laravel Mix Aliases

Add Dropzone to Mix aliases for easier imports:

// webpack.mix.js
mix.webpackConfig({
    resolve: {
        alias: {
            dropzone: path.resolve(__dirname, 'node_modules/dropzone/dist/d