Mediabox Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require contao-components/mediabox
   

   Ensure contao-components/mediabox is listed in composer.json under require.

2. Basic Usage The package provides a MediaBox component for handling media (images, videos, files) with a clean API. Start by initializing it in a controller or service:

   use ContaoComponents\MediaBox\MediaBox;
   
   $mediaBox = new MediaBox();
   

3. First Use Case: Uploading an Image

   $uploadedFile = $mediaBox->upload('image', $request->file('image'));
   $mediaBox->save($uploadedFile); // Persist to storage
   $url = $mediaBox->getUrl($uploadedFile); // Generate public URL
   

4. Key Files to Explore

   • src/MediaBox.php – Core class with methods for uploads, storage, and URL generation.
   • config/mediabox.php (if auto-generated) – Default settings for storage paths, allowed MIME types, etc.

Implementation Patterns

1. Workflow: Handling File Uploads

• Request Handling Validate and process uploads in a Laravel controller:

  public function upload(Request $request)
  {
      $this->validate($request, ['file' => 'required|image']);
  
      $mediaBox = new MediaBox();
      $file = $mediaBox->upload('image', $request->file('file'));
      $mediaBox->save($file);
  
      return response()->json(['url' => $mediaBox->getUrl($file)]);
  }
  

• Storage Integration Configure storage disks in config/mediabox.php:

  'storage' => [
      'disk' => 'public', // Default: 'public'
      'path' => 'uploads/media', // Relative to storage path
  ],
  

2. Workflow: Managing Media Metadata

• Tagging & Categorization Extend the MediaBox class to add custom metadata:

  $mediaBox->setMetadata($file, ['tags' => ['newsletter', 'promo']]);
  $tags = $mediaBox->getMetadata($file, 'tags', []);
  

• Lazy Loading URLs Generate URLs on-demand to avoid pre-processing:

  $url = $mediaBox->getUrl($file, ['width' => 800, 'height' => 600]); // Resize via Intervention Image (if supported)
  

3. Integration with Laravel Ecosystem

• Form Requests Use Laravel’s FormRequest to validate uploads:

  public function rules()
  {
      return [
          'file' => 'required|mimes:jpg,png|max:2048',
      ];
  }
  

• Service Providers Bind MediaBox to the container for dependency injection:

  $this->app->singleton(MediaBox::class, function ($app) {
      return new MediaBox(config('mediabox'));
  });
  

• Events & Observers Listen for upload events (extend the package or wrap calls):

  event(new MediaUploaded($file, $request));
  

Gotchas and Tips

Pitfalls

1. MIME Type Restrictions

   • Default allowed MIME types may not cover all use cases. Extend via config:

     'allowed_mimes' => ['image/jpeg', 'image/png', 'video/mp4', 'application/pdf'],
     

   • Debug Tip: Use dd($request->file('file')->getMimeType()) to verify types.

2. Storage Permissions

   • Ensure the configured storage disk has write permissions:

     chmod -R 775 storage/app/public/uploads
     

   • Gotcha: If using local disk, symlink storage/app/public to public/storage.

3. File Naming Collisions

   • The package auto-generates filenames (e.g., hash.jpg). Overwrite with custom logic:

     $mediaBox->setCustomName($file, 'custom-name.jpg');
     

4. Missing Intervention Image

   • If using image resizing, ensure intervention/image is installed:

     composer require intervention/image
     

   • Error: Class 'Intervention\Image\ImageManager' not found → Install the package.

Debugging Tips

• Log Uploads Enable debug mode in config/mediabox.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs will appear in storage/logs/mediabox.log.

• Validate File Paths Check if files are saved to the correct path:

  $mediaBox->getStoragePath($file); // Returns full path
  

Extension Points

1. Custom Storage Adapters Implement ContaoComponents\MediaBox\Contracts\StorageAdapter for S3, Dropbox, etc.

2. Pre/Post-Process Hooks Override methods like save() or getUrl() to add logic:

   class CustomMediaBox extends MediaBox {
       public function save($file) {
           // Add watermark before saving
           $this->addWatermark($file);
           parent::save($file);
       }
   }
   

3. API Wrapper Expose a RESTful API for media management:

   Route::post('/api/upload', [MediaController::class, 'upload']);
   

Performance Considerations

• Batch Processing Use MediaBox::batchSave() for multiple files:

  $mediaBox->batchSave([$file1, $file2]);
  

• Lazy URL Generation Avoid generating URLs for files not yet requested (e.g., deferred resizing).