Laravel Mediaman Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require farhanshares/laravel-mediaman
   php artisan vendor:publish --provider="FarhanShares\MediaMan\MediaManServiceProvider"
   php artisan migrate
   

   • Publishes config (config/mediaman.php) and migrations (creates media and media_models tables).

2. Configuration:

   • Define storage disks in config/mediaman.php:

     'disks' => [
         'public' => 'public',
         's3' => 's3',
     ],
     

   • Set default disk and upload paths (e.g., uploads/{model}).

3. First Use Case:

   • Attach media to a model (e.g., Post):

     use FarhanShares\MediaMan\Traits\MediaMan;
     
     class Post extends Model
     {
         use MediaMan;
     }
     
     $post = Post::create(['title' => 'Hello World']);
     $post->addMediaFromUrl('https://example.com/image.jpg')->toMediaCollection('images');
     

Implementation Patterns

Core Workflows

1. Media Uploads:

   • From URL:

     $model->addMediaFromUrl($url)->toMediaCollection('collection_name');
     

   • From File:

     $model->addMediaFromRequest('file_input')->toMediaCollection('collection_name');
     

   • From Path:

     $model->addMediaFromPath($localPath)->toMediaCollection('collection_name');
     

2. Media Collections:

   • Define collections in a model:

     public function registerMediaCollections(): void
     {
         $this->addMediaCollection('images')
               ->singleFile()
               ->useDisk('public');
     
         $this->addMediaCollection('documents')
               ->multipleFiles()
               ->useDisk('s3');
     }
     

   • Validation: Use validateMedia() to enforce rules (e.g., MIME types, max size):

     $this->validateMedia('images', function ($attribute, $value, $fail) {
         $value->mimeTypeIn(['image/jpeg', 'image/png'], $fail);
     });
     

3. Media Conversion:

   • Define conversions in registerMediaConversions():

     public function registerMediaConversions(Media $media = null): void
     {
         $this->addMediaConversion('thumb')
               ->width(200)
               ->height(200)
               ->sharpen(10);
     }
     

   • Generate converted media:

     $media = $model->getFirstMedia('images');
     $model->addMedia($media)->toMediaCollection('thumbs')->usingFileName('thumb_'.$media->file_name);
     

4. Model Associations:

   • Eager Loading:

     $posts = Post::with('images')->get();
     

   • Accessing Media:

     $media = $post->getFirstMedia('images');
     $url = $media->getUrl();
     $path = $media->getPath();
     

5. Broadcasting:

   • Listen for media events (e.g., MediaAdded):

     use FarhanShares\MediaMan\Events\MediaAdded;
     
     MediaAdded::dispatch($model, $media);
     

Integration Tips

1. Form Handling:

   • Use laravel-mediaman's form helpers for file uploads:

     <input type="file" name="images[]" multiple>
     

   • Process in controller:

     $model->addMedia($request->file('images'))->toMediaCollection('images');
     

2. API Responses:

   • Serialize media with MediaResource:

     use FarhanShares\MediaMan\Http\Resources\MediaResource;
     
     return new MediaResource($media);
     

3. Queueing Uploads:

   • Offload processing to queues:

     $model->addMediaFromUrl($url)->toMediaCollection('images')->queue();
     

4. Custom Storage:

   • Extend FarhanShares\MediaMan\Filesystem\MediaFilesystem for custom logic (e.g., S3 presigned URLs).

Gotchas and Tips

Pitfalls

1. Disk Configuration:

   • Ensure disks in config/mediaman.php match your filesystems.php configuration.
   • Gotcha: Forgetting to run php artisan storage:link for local public disk.

2. Media Collection Naming:

   • Collection names must be unique per model. Overwriting can lead to silent failures.
   • Tip: Use hasMediaCollection() to check existence before adding.

3. Event Dispatching:

   • Events like MediaAdded are not dispatched by default. Explicitly dispatch if needed:

     $model->addMedia(...)->dispatchMediaEvents();
     

4. Conversion Caching:

   • Converted files are cached. Clear cache with:

     php artisan mediaman:clear-cache
     

   • Tip: Use ->keepOriginal(false) to avoid storing originals for conversions.

5. Large Files:

   • For large uploads, use chunked uploads or queue processing:

     $model->addMediaFromRequest('file')->queue();
     

6. Model Binding:

   • Media models are polymorphic. Ensure media_models table has model_type and model_id columns.

Debugging

1. Log Media Events:

   • Enable logging in config/mediaman.php:

     'logging' => true,
     

   • Check storage/logs/laravel.log for media operations.

2. Validate Media:

   • Use dd($media->errors()) to inspect validation failures.

3. Check Disk Space:

   • Monitor disk usage for media table growth. Archive old media if needed.

Extension Points

1. Custom Validators:

   • Extend FarhanShares\MediaMan\Validation\Rules\Media for custom rules.

2. Media Events:

   • Listen to events like MediaDeleting to add cleanup logic:

     MediaDeleting::subscribe(function ($media) {
         // Custom logic before deletion
     });
     

3. Filesystem Adapters:

   • Implement FarhanShares\MediaMan\Contracts\FilesystemAdapter for custom storage backends.

4. UI Integration:

   • Use mediaman:ui package (if available) or build custom UI with:

     $media = $model->getMedia('images');
     $media->map->getUrl();
     

5. Model Observers:

   • Sync media on model events:

     $model->observedBy(MediaObserver::class);