Media Manager Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel-admin/media-manager
   php artisan vendor:publish --provider="LaravelAdmin\MediaManager\MediaManagerProvider"
   php artisan migrate
   

   Add the provider to config/app.php:

   LaravelAdmin\MediaManager\MediaManagerProvider::class
   

2. Basic Upload:

   use LaravelAdmin\MediaManager\Upload;
   $media = Upload::handle($request, 'file'); // 'file' is the request field name
   

3. First Use Case:

   • Upload a file via a form with enctype="multipart/form-data".
   • Access the uploaded file’s URL via $media->url.

Where to Look First

• Configuration: config/media-manager.php (upload drivers, storage, image styles).
• Vue Component: resources/js/bootstrap.js (integrate MediaBrowser.vue).
• Model Trait: Traits\MediaTrait (for automatic media relations).

Implementation Patterns

Core Workflows

1. Uploading Media:

   // Default storage (local)
   $media = Upload::handle($request, 'avatar');
   
   // Custom storage (e.g., S3)
   $media = Upload::storage('s3')->handle($request, 'avatar');
   
   // Replace existing media
   $media = Upload::update($existingMedia)->handle($request, 'avatar');
   

2. Model Relations:

   • Add media_id to your model’s migration and use the MediaTrait:

     use LaravelAdmin\MediaManager\Traits\MediaTrait;
     class Post extends Model {
         use MediaTrait;
     }
     

   • Access media via:

     $post->mediaUrl(); // Public URL
     $post->imagestyle('thumbnail'); // Styled URL
     

3. Image Styles:

   • Define styles in config/media-manager.php under image_styles.
   • Use in Blade:

     <img src="{{ $post->imagestyle('thumbnail') }}">
     

4. Vue Media Browser:

   • Include in your Vue app:

     import MediaBrowser from '../../../vendor/laravel-admin/media-manager/resources/js/bootstrap';
     

   • Trigger via:

     <media-browser @selected="handleMediaSelect"></media-browser>
     

Integration Tips

• Laravel Admin Integration: Use the MediaItem field in CRUD modules:

  $form->addField([
      'type' => 'media',
      'name' => 'header_image',
      'label' => 'Header Image',
      'upload' => true,
  ]);
  

• Custom Drivers: Implement LaravelAdmin\Mediamanager\Contracts\UploadDriver for non-standard uploads (e.g., YouTube URLs):

  class YouTubeDriver implements UploadDriver {
      public function upload($request, $field, $media) { ... }
  }
  

  Register in config/media-manager.php:

  'drivers' => [
      'url' => \App\Drivers\YouTubeDriver::class,
  ],
  

• API Endpoints: Leverage the built-in AjaxController for media operations:

  Route::resource('media/ajax', \LaravelAdmin\MediaManager\Http\Controllers\AjaxController::class)->only(['destroy']);
  

Gotchas and Tips

Pitfalls

1. Vue Dependency:

   • The package requires Vue 2/3 and Dropzone.js (npm install dropzone --save-dev).
   • Ensure your app.js includes:

     require('../../../vendor/laravel-admin/media-manager/resources/js/bootstrap.js');
     

2. Storage Configuration:

   • The storage method assumes a configured filesystem in config/filesystems.php.
   • Defaults to local if unspecified.

3. Linked-Object Deletion:

   • The destroy method checks for linked objects (e.g., posts.media_id = media.id).
   • Returns 409 Conflict if media is in use. Handle this in your frontend:

     axios.delete('/media/ajax/1')
         .catch(error => {
             if (error.response.status === 409) {
                 alert('Media is linked to other objects!');
             }
         });
     

4. Image Style Caching:

   • Styles are cached by default. Clear cache if styles don’t update:

     php artisan cache:clear
     

5. Migration Conflicts:

   • The package generates a media table. Ensure no naming conflicts with existing tables.

Debugging Tips

• Upload Failures: Check config/media-manager.php for allowed_filetypes or max_filesize limits. Log errors in Upload::handle():

  try {
      $media = Upload::handle($request, 'file');
  } catch (\Exception $e) {
      \Log::error($e->getMessage());
  }
  

• Vue Component Issues: Verify Dropzone is initialized only once per browser instance (fixed in v1.0.4). Check browser console for errors like:

  Dropzone is not defined
  

  Solution: Ensure bootstrap.js is loaded after Vue and Dropzone.

• Style Generation: If styles fail, ensure Intervention Image is installed:

  composer require intervention/image
  

  Rebuild config cache:

  php artisan config:clear
  

Extension Points

1. Custom Media Fields: Override the trait’s relation name:

   class Post extends Model {
       use MediaTrait;
       protected $mediaRelation = 'custom_media';
   }
   

2. Event Listeners: Listen for media events (e.g., media.created):

   \Event::listen('media.created', function ($media) {
       \Log::info("New media uploaded: {$media->id}");
   });
   

3. Admin Panel Customization: Publish and modify views:

   php artisan vendor:publish --tag=media-manager-views
   

   Edit resources/views/vendor/media-manager/....

4. Bulk Operations: Extend the AjaxController for batch deletes:

   public function destroyBatch(Request $request) {
       $ids = $request->input('ids');
       foreach ($ids as $id) {
           $this->destroy($id);
       }
   }