Arbitration Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require camelot/arbitration
   

   For Symfony bundles, add to config/bundles.php:

   Camelot\ArbitrationBundle\ArbitrationBundle::class => ['all' => true],
   

2. Basic Middleware Registration: Register the middleware in config/routes.php (Symfony) or app/Http/Kernel.php (Laravel):

   // Laravel (Kernel.php)
   protected $middleware = [
       \Camelot\Arbitration\Middleware\ImageArbitration::class,
   ];
   

3. First Use Case:

   • Upload an image via a form (e.g., POST /upload).
   • The middleware automatically processes the image using Intervention Image (e.g., resizing, filtering).
   • Example controller:

     public function upload(Request $request) {
         $request->validate(['image' => 'required|image']);
         $path = $request->file('image')->store('uploads');
         return response()->json(['path' => $path]);
     }
     

4. Configuration: Override default settings in config/packages/camelot_arbitration.yaml (Symfony) or config/arbitration.php (Laravel):

   # Symfony
   arbitration:
       default_driver: 'gd'
       allowed_formats: ['jpg', 'png', 'webp']
       max_width: 2000
       max_height: 2000
   

Implementation Patterns

Workflow: Image Processing Pipeline

1. Request Handling:

   • Attach middleware to routes handling file uploads:

     Route::post('/profile-pic', [ProfileController::class, 'upload'])
          ->middleware(ImageArbitration::class);
     

2. Custom Processing:

   • Extend the middleware to add custom logic:

     public function handle($request, Closure $next) {
         if ($request->hasFile('image')) {
             $img = $request->file('image');
             $image = Image::make($img->getRealPath());
             $image->fit(800, 600); // Custom resize
             $image->save($img->path());
         }
         return $next($request);
     }
     

3. Batch Processing:

   • Process multiple images in a single request:

     public function uploadMultiple(Request $request) {
         foreach ($request->file('images') as $image) {
             $processedPath = $this->processImage($image);
             // Store $processedPath
         }
     }
     

4. Integration with Storage:

   • Use Laravel’s filesystem or Symfony’s Filesystem to handle processed files:

     use Illuminate\Support\Facades\Storage;
     
     $path = Storage::disk('public')->putFile('processed', $request->file('image'));
     

Common Patterns

• Conditional Processing: Use middleware groups or route middleware to apply arbitration only to specific routes.

  Route::middleware(['arbitration'])->group(function () {
      Route::post('/admin/images', [AdminController::class, 'upload']);
  });
  

• Dynamic Configuration: Override settings per route or controller:

  public function upload(Request $request) {
      config(['arbitration.max_width' => 1500]);
      // Process image...
  }
  

• Event-Based Processing: Listen for image.processed events to trigger post-processing (e.g., notifications, analytics):

  event(new ImageProcessed($request->file('image'), $processedPath));
  

Gotchas and Tips

Pitfalls

1. Missing Intervention Image: Ensure intervention/image is installed (composer require intervention/image). The bundle relies on it for core functionality.

2. File Validation: The middleware assumes files are validated before processing. Add validation rules to avoid errors:

   $request->validate([
       'image' => 'required|image|mimes:jpg,png|max:2048',
   ]);
   

3. Memory Limits: Large images may hit PHP’s memory limit. Adjust memory_limit in php.ini or optimize image processing:

   $image->resize(1000, null, function ($constraint) {
       $constraint->aspectRatio();
       $constraint->upsize();
   });
   

4. Symlink Issues (Symfony): If using Symfony, ensure the public/uploads directory is symlinked to var/uploads to avoid permission errors.

5. Middleware Order: Place ImageArbitration after file upload middleware (e.g., ConvertEmptyStringsToNull) but before business logic.

Debugging

• Log Processing: Enable debug mode to log image operations:

  arbitration:
      debug: true
  

  Check logs in storage/logs/laravel.log (Laravel) or var/log/dev.log (Symfony).

• Common Errors:

  • "Class not found": Verify Camelot\ArbitrationBundle is autoloaded (run composer dump-autoload).
  • "GD library missing": Install PHP-GD (sudo apt-get install php-gd) or use imagick driver:

    arbitration:
        default_driver: 'imagick'
    

Tips

1. Performance:

   • Cache processed images using Laravel’s cache or Symfony’s Cache component.
   • Use ->encode() with optimal quality settings to reduce file size:

     $image->encode('jpg', 80); // 80% quality
     

2. Extension Points:

   • Custom Drivers: Extend \Camelot\Arbitration\Driver\DriverInterface to support new image libraries (e.g., Imagick).
   • Filters: Create reusable filter chains:

     $image->filter(function ($img) {
         $img->contrast(10);
         $img->brightness(5);
     });
     

3. Testing:

   • Mock the middleware in PHPUnit:

     $middleware = new ImageArbitration();
     $response = $middleware->handle($request, function () {
         return new Response();
     });
     

   • Use laravel-breeze or symfony/panther for end-to-end upload tests.

4. Security:

   • Sanitize filenames to prevent directory traversal:

     $filename = Str::random(40).'.'.$request->file('image')->extension();
     

   • Restrict allowed formats in config to avoid malicious uploads.

5. Laravel-Specific:

   • For Laravel, publish the config:

     php artisan vendor:publish --tag=arbitration-config
     

   • Use Laravel’s HandleUploadedFile trait for seamless file handling:

     use Illuminate\Foundation\Bus\DispatchesJobs;
     use Illuminate\Contracts\Queue\ShouldQueue;
     use Illuminate\Foundation\WithSymfonyRequest;
     
     class UploadController extends Controller implements ShouldQueue
     {
         use DispatchesJobs, WithSymfonyRequest;
         // ...
     }