Media Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require disjfa/media-bundle
   

   Add to config/app.php under providers:

   Disjfa\MediaBundle\MediaServiceProvider::class,
   

   Publish the config:

   php artisan vendor:publish --provider="Disjfa\MediaBundle\MediaServiceProvider" --tag=config
   

2. Configuration Edit config/media.php to define:

   • Storage paths (local, s3, etc.)
   • Allowed file types (e.g., ['jpg', 'png', 'pdf'])
   • Max file sizes (e.g., 10MB)

3. First Use Case: Uploading a File

   use Disjfa\MediaBundle\Facades\Media;
   
   $path = Media::upload('file.jpg', 'uploads');
   // Returns: "/uploads/file.jpg"
   

Implementation Patterns

Core Workflows

1. File Uploads

   • Single File:

     $path = Media::upload($file, 'folder', ['resize' => [200, 200]]);
     

   • Multiple Files:

     $paths = Media::uploadMultiple($files, 'folder');
     

2. File Management

   • Delete:

     Media::delete($path); // Deletes from storage and DB (if tracked)
     

   • List Files:

     $files = Media::list('folder'); // Returns array of file info
     

3. Integration with Eloquent

   • Track Media in Models:

     use Disjfa\MediaBundle\Traits\HasMedia;
     
     class Post extends Model {
         use HasMedia;
     }
     

   • Attach Media to Model:

     $post->addMedia($file)->toMediaCollection('images');
     

4. Storage Adapters

   • Switch between local, s3, or custom adapters via config:

     'disks' => [
         'local' => [
             'driver' => 'local',
             'root' => storage_path('app/public'),
         ],
         's3' => [
             'driver' => 's3',
             'key' => env('AWS_ACCESS_KEY_ID'),
             'secret' => env('AWS_SECRET_ACCESS_KEY'),
             'bucket' => env('AWS_BUCKET'),
         ],
     ],
     

5. Resizing and Thumbnails

   • Auto-generate thumbnails on upload:

     $path = Media::upload($file, 'folder', [
         'resize' => [100, 100],
         'thumbs' => ['small' => [50, 50], 'medium' => [300, 300]],
     ]);
     

Gotchas and Tips

Common Pitfalls

1. Permission Issues

   • Ensure storage directories are writable:

     chmod -R 775 storage/app/public
     

   • For S3, verify IAM permissions and bucket policies.

2. Missing Config

   • Always publish the config (php artisan vendor:publish) to avoid default values overriding your settings.

3. File Validation

   • The bundle validates file types/sizes after upload. For pre-upload validation:

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

4. Database Tracking

   • If using HasMedia, run migrations:

     php artisan migrate
     

   • Media records are stored in media table by default.

5. Custom Storage Paths

   • Override default paths in config/media.php:

     'paths' => [
         'local' => storage_path('custom/media'),
     ],
     

Debugging Tips

• Check Uploaded Files:

  dd(Media::list('folder')); // Inspect stored files
  

• Log Errors: Enable Laravel logging to catch storage adapter issues:

  \Log::debug('Media upload error', ['path' => $path, 'error' => $e]);
  

• Clear Cached Config:

  php artisan config:clear
  

Extension Points

1. Custom Storage Adapters Extend Disjfa\MediaBundle\Contracts\StorageAdapter for new backends (e.g., Azure Blob).

2. Events Listen for upload/delete events:

   Media::uploaded(function ($path) {
       // Post-upload logic
   });
   

3. Middleware Restrict uploads by role:

   Media::middleware(function ($request) {
       return auth()->user()->can('upload-media');
   });
   

4. Override Defaults Bind custom classes in AppServiceProvider:

   $this->app->bind(
       Disjfa\MediaBundle\Contracts\StorageAdapter::class,
       CustomStorageAdapter::class
   );