Async Uploader Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require champs-libres/async-uploader-bundle
   

   Add to config/app.php under providers:

   ChampsLibres\AsyncUploaderBundle\AsyncUploaderBundle::class,
   

2. Publish Configuration

   php artisan vendor:publish --provider="ChampsLibres\AsyncUploaderBundle\AsyncUploaderBundle" --tag="config"
   

   Configure config/async_uploader.php with your Swift/S3 credentials and storage settings.

3. First Use Case: Basic Upload Endpoint Add the middleware to your upload route:

   Route::post('/upload', [UploadController::class, 'handle'])
       ->middleware('async.uploader');
   

   Ensure your frontend sends files via multipart/form-data with a temp-url field (auto-generated by the middleware).

Implementation Patterns

Workflow: Async Upload Pipeline

1. Frontend

   • Use the AsyncUploader JS library (if provided) or manually construct a request with:

     const formData = new FormData();
     formData.append('file', fileInput.files[0]);
     formData.append('temp-url', await fetchTempUrl()); // Optional if middleware auto-generates
     fetch('/upload', { method: 'POST', body: formData });
     

2. Middleware

   • Validates the temp-url (if provided) or generates a temporary Swift/S3 URL.
   • Streams the file directly to storage without blocking the request.

3. Backend

   • Return a JSON response with a job_id for tracking:

     { "job_id": "abc123", "status": "queued" }
     

   • Use AsyncUploaderBundle's Job model to track progress (e.g., Job::find($job_id)->status).

Integration Tips

• Laravel Queues: Pair with Laravel Queues for post-upload processing (e.g., thumbnails, notifications):

  // In UploadController
  public function handle(Request $request) {
      $job = AsyncUploader::upload($request->file('file'));
      ProcessUploadJob::dispatch($job->job_id);
      return response()->json(['job_id' => $job->job_id]);
  }
  

• Storage Switching: Use environment-based configs to toggle between Swift/S3:

  // config/async_uploader.php
  'storage' => env('UPLOAD_DRIVER') === 'swift' ? 'swift' : 's3',
  

• Validation: Extend the middleware to validate file types/sizes:

  // app/Http/Middleware/ValidateUpload.php
  public function handle($request, Closure $next) {
      $request->validate([
          'file' => 'required|file|mimes:jpg,png|max:10240',
      ]);
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Temp-URL Expiry

   • Swift/S3 temp URLs expire quickly (default: 15 minutes). Ensure frontend requests are fast or implement retry logic.
   • Fix: Increase temp_url_ttl in config or use shorter-lived URLs with client-side retries.

2. Large File Handling

   • Direct streaming to Swift/S3 may fail for files > 5GB due to PHP memory limits or server timeouts.
   • Fix: Use chunked uploads (not natively supported; may require custom middleware).

3. Job Tracking

   • The Job model may not persist if the upload fails mid-stream.
   • Fix: Wrap upload logic in a transaction or use a database queue (e.g., database driver in Laravel).

Debugging

• Logs: Enable storage.log in config/async_uploader.php to debug Swift/S3 connection issues.
• Middleware Order: Ensure async.uploader runs before any validation that might reject the request early.

Extension Points

1. Custom Storage Adapters Override the default adapter by binding a new ChampsLibres\AsyncUploaderBundle\Storage\AdapterInterface:

   // app/Providers/AppServiceProvider.php
   public function register() {
       $this->app->bind(
           StorageAdapterInterface::class,
           CustomS3Adapter::class
       );
   }
   

2. Event Listeners Listen for upload events (e.g., UploadStarted, UploadFailed) to trigger notifications:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       UploadStarted::class => [UploadLogger::class, 'log'],
   ];
   

3. Frontend Hooks If the bundle includes JS, extend it with custom hooks for progress bars or retries:

   AsyncUploader.on('upload:progress', (progress) => {
       console.log(`Uploaded ${progress}%`);
   });