Laravel Chunky Laravel Package

Getting Started

Minimal Steps

1. Install Backend:

   composer require netipar/laravel-chunky
   php artisan vendor:publish --tag=chunky-config
   php artisan migrate
   

2. Install Frontend (Vue 3 example):

   npm install @netipar/chunky-vue3
   

3. Drop-in Vue 3 Composable:

   <script setup>
   import { useChunkUpload } from '@netipar/chunky-vue3';
   const { upload, progress, isUploading } = useChunkUpload();
   </script>
   <input type="file" @change="(e) => upload(e.target.files[0])" />
   

First Use Case

Upload a large file (e.g., 100MB) with progress tracking:

<script setup>
const { upload, progress, isComplete, error } = useChunkUpload();
function handleUpload(e) {
  upload(e.target.files[0]);
}
</script>
<template>
  <input type="file" @change="handleUpload" />
  <progress v-if="isUploading" :value="progress" max="100" />
  <p v-if="error">{{ error }}</p>
</template>

Implementation Patterns

Core Workflow

1. Frontend:

   • Use framework-specific composables (useChunkUpload, useBatchUpload).
   • Configure chunk size (default: 5MB) via chunkSize prop.
   • Handle events: onProgress, onComplete, onError.

2. Backend:

   • Listen to events (e.g., UploadCompleted) in EventServiceProvider.
   • Process final files via AssembleFileJob (run on queue).

Integration Tips

• Livewire: Use <livewire:chunky-upload /> with slots for custom UI.
• Batch Uploads: Use useBatchUpload for multiple files with shared progress.
• Authentication: Bind a custom Authorizer to override default ownership checks.
• Observability: Enable metrics in config/chunky.php for Datadog/Prometheus.

Example: Event-Driven Processing

// app/Listeners/ProcessUploadedFile.php
public function handle(UploadCompleted $event) {
    $filePath = $event->finalPath;
    // Process file (e.g., generate thumbnail, store metadata)
}

Frontend Configuration

<script setup>
const { upload } = useChunkUpload({
  maxConcurrent: 4,       // Parallel chunks
  autoRetry: true,         // Retry failed chunks
  maxRetries: 3,           // Max retries
  chunkSize: 10 * 1024 * 1024, // 10MB chunks
  context: 'user_avatars', // Optional context for validation
});
</script>

Gotchas and Tips

Pitfalls

1. Queue Worker Required:

   • AssembleFileJob must run on a queue (not sync). Use queue:work or a supervisor.
   • Symptom: Uploads complete but files never appear in storage/app/chunky/uploads/.

2. Lock Driver:

   • Avoid array or file cache drivers for chunky.lock_driver. Use Redis/Memcached/DB.
   • Symptom: Race conditions on concurrent uploads.

3. CSRF Token:

   • Frontend auto-reads XSRF-TOKEN cookie. If using custom headers, set via setDefaults():

     import { setDefaults } from '@netipar/chunky-core';
     setDefaults({ headers: { 'X-CSRF-TOKEN': 'custom-token' } });
     

4. Staging Directory:

   • Large uploads (> /tmp space) need chunky.staging_directory configured.
   • Symptom: Uploads fail silently with "disk full" errors.

5. Broadcasting:

   • Real-time updates require CHUNKY_BROADCASTING=true + Laravel Echo + WebSocket server.
   • Symptom: UI doesn’t reflect progress changes.

Debugging

• Check Upload Status:

  php artisan chunky:status {uploadId}
  

• Clean Up Stale Uploads:

  php artisan chunky:cleanup
  

• Logs: Enable chunky.log_level = debug in config.

Extension Points

1. Custom Storage: Override ChunkStorage to use S3/Cloudflare directly:

   // config/chunky.php
   'storage' => \App\Services\CustomChunkStorage::class,
   

2. Validation: Extend UploadValidator to reject files by MIME type or size:

   public function validate(array $data): void {
       parent::validate($data);
       if ($data['size'] > 500 * 1024 * 1024) { // 500MB
           throw new ValidationException('File too large.');
       }
   }
   

3. Frontend Theming: Override default styles by targeting .chunky-upload-progress or .chunky-upload-button.

Pro Tips

• Resume Support: Paused uploads retain state. Use pause()/resume() in UI.
• Batch Progress: Track per-file progress in useBatchUpload:

  <div v-for="file in completedFiles" :key="file.name">
    {{ file.name }} ({{ file.size }})
  </div>
  

• Livewire Events: Listen for chunky-upload-completed in parent components:

  #[On('chunky-upload-completed')]
  public function handleUpload(array $data) {
      $this->dispatch('upload-success', data: $data);
  }
  

• Security: Restrict uploads to authenticated users via chunky.routes.middleware.