Livewire Dropzone Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dasundev/livewire-dropzone
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Dasun\LivewireDropzone\LivewireDropzoneServiceProvider"
   

2. First Use Case: Add the component to a Livewire blade view:

   <livewire:dropzone
       upload-url="{{ route('upload') }}"
       max-files="5"
       accepted-files="image/*,application/pdf"
       @uploaded="uploaded($event)"
   />
   

   Define the upload route in routes/web.php:

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

3. Basic Controller Logic:

   use Dasun\LivewireDropzone\DropzoneUploadedFile;
   
   public function store()
   {
       $files = request()->file('files');
       foreach ($files as $file) {
           // Handle file (e.g., store in storage)
           $path = $file->store('uploads');
       }
       return response()->json(['success' => true]);
   }
   

4. Livewire Component Integration:

   use Livewire\Component;
   use Dasun\LivewireDropzone\DropzoneUploadedFile;
   
   public function uploaded($event)
   {
       $files = $event['files'];
       foreach ($files as $file) {
           $this->handleFile($file); // Custom logic
       }
   }
   

Implementation Patterns

Common Workflows

1. Basic File Upload with Livewire

• Blade:

  <livewire:dropzone
      upload-url="{{ route('upload') }}"
      @uploaded="handleUpload($event)"
  />
  

• Livewire Component:

  public function handleUpload($event)
  {
      $files = $event['files'];
      foreach ($files as $file) {
          $this->storeFile($file);
      }
  }
  

2. Chunked Uploads for Large Files

• Configure chunking in config/livewire-dropzone.php:

  'chunking' => [
      'enabled' => true,
      'chunk_size' => 5 * 1024 * 1024, // 5MB
  ],
  

• Blade:

  <livewire:dropzone
      upload-url="{{ route('upload.chunk') }}"
      chunking="true"
  />
  

3. Custom Thumbnail Generation

• Use @thumbnail event to generate thumbnails on upload:

  <livewire:dropzone
      @thumbnail="generateThumbnail($event)"
  />
  

• Livewire Component:

  public function generateThumbnail($event)
  {
      $file = $event['file'];
      $thumbnail = \Intervention\Image\Facades\Image::make($file->getRealPath())
          ->resize(200, 200)
          ->encode();
      $this->saveThumbnail($thumbnail, $file->getClientOriginalName());
  }
  

4. Integration with Laravel Filesystem

• Store files directly in S3 or other disks:

  public function storeFile(DropzoneUploadedFile $file)
  {
      $path = $file->store('s3-uploads', 's3');
      // Log or process further
  }
  

5. Validation and Error Handling

• Validate files in Livewire:

  public function handleUpload($event)
  {
      foreach ($event['files'] as $file) {
          $this->validateFile($file);
          $this->storeFile($file);
      }
  }
  
  protected function validateFile(DropzoneUploadedFile $file)
  {
      $this->validate([
          'file' => 'required|mimes:jpg,png,pdf|max:10240',
      ], [], [
          'file' => $file->getClientOriginalName(),
      ]);
  }
  

6. Real-Time Progress Tracking

• Use @upload-progress event:

  <livewire:dropzone
      @upload-progress="updateProgress($event)"
  />
  

• Livewire Component:

  public $progress = 0;
  
  public function updateProgress($event)
  {
      $this->progress = $event['progress'];
  }
  

• Display progress in Blade:

  <progress value="{{ $progress }}" max="100"></progress>
  

Gotchas and Tips

Pitfalls and Debugging

1. CORS Issues

• If using chunked uploads or external storage (e.g., S3), ensure CORS headers are configured:

  // For S3, add this to your bucket policy:
  {
      "AllowedHeaders": ["Authorization"],
      "AllowedMethods": ["PUT", "POST", "DELETE"],
      "AllowedOrigins": ["https://yourdomain.com"],
  }
  

2. File Size Limits

• Default PHP upload_max_filesize and post_max_size may block large uploads. Adjust in php.ini:

  upload_max_filesize = 20M
  post_max_size = 25M
  

• For chunked uploads, ensure max_execution_time is sufficient.

3. Event Ordering

• Events fire in this order: upload-started → upload-progress → thumbnail (if enabled) → uploaded. Use this to chain logic (e.g., show progress bar before uploaded).

4. Livewire Wire:ignore

• If files disappear after upload, wrap the component in wire:ignore to prevent Livewire from re-rendering it:

  <div wire:ignore>
      <livewire:dropzone ... />
  </div>
  

5. Chunking Quirks

• Ensure your upload endpoint (upload-url) supports chunked uploads. For Laravel, use:

  public function chunkStore()
  {
      $chunk = request()->file('chunk');
      $identifier = request()->input('identifier');
      $totalChunks = request()->input('totalChunks');
      $chunkIndex = request()->input('chunkIndex');
  
      // Logic to handle chunk (e.g., save to temporary storage)
  }
  

6. File Naming Conflicts

• Use unique() or custom naming in storage:

  public function storeFile(DropzoneUploadedFile $file)
  {
      $path = $file->storeAs(
          'uploads',
          Str::uuid() . '.' . $file->getClientOriginalExtension()
      );
  }
  

Tips for Daily Use

1. Reusable Livewire Component

• Create a base component for consistency:

  class BaseDropzone extends Component
  {
      public function handleUpload($event)
      {
          foreach ($event['files'] as $file) {
              $this->validateFile($file);
              $this->storeFile($file);
          }
      }
  
      protected function validateFile(DropzoneUploadedFile $file) { /* ... */ }
      protected function storeFile(DropzoneUploadedFile $file) { /* ... */ }
  }
  

  Extend it for specific use cases:

  class ProfileAvatarDropzone extends BaseDropzone { /* ... */ }
  

2. Dynamic Configuration

• Pass dynamic props to the component:

  <livewire:dropzone
      :upload-url="$uploadUrl"
      :max-files="$maxFiles"
      :accepted-files="$allowedTypes"
  />
  

3. Localization

• Translate messages (e.g., "Uploading...") via Laravel's localization:

  <livewire:dropzone
      :messages="__('livewire-dropzone::messages')"
  />
  

  Publish and customize the language file:

  php artisan vendor:publish --tag=livewire-dropzone-lang
  

4. Testing

• Test file uploads with Laravel's UploadedFile facade:

  public function test_upload()
  {
      $file = UploadedFile::fake()->image('test.jpg');
      $this->call('POST', '/upload', [
          'files' => [$file],
      ])->assertOk();
  }
  

5. Performance Optimization

• Disable thumbnail generation for non-image files:

  <livewire:dropzone
      thumbnail-method="isImage"
  />
  

  Define isImage in your Livewire component:

  public function isImage(DropzoneUploadedFile $file)
  {
      return in_array($file->getClientOriginalExtension(), ['jpg', 'png', 'gif']);
  }
  

6. Extending Functionality

• Use @removed event to handle file deletions:

  <livewire:dropzone
      @removed="removeFile($event)"