Easy Media Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require agence-adeliom/easy-media-bundle
   

   Add to config/bundles.php (Symfony) or config/packages/easy_media.yaml (Laravel via Symfony bridge):

   AgenceAdeliom\EasyMediaBundle\EasyMediaBundle: []
   

2. Configure in EasyAdmin Extend your CRUD controller to use the media manager:

   use AgenceAdeliom\EasyMediaBundle\EasyAdmin\Field\MediaField;
   
   $crud->addField(MediaField::new('media')->setUploadDir('uploads/%year%/%month%/%day%'));
   

3. First Use Case

   • Access /admin/media to open the media manager.
   • Upload files via drag-and-drop or URL paste.
   • Assign media to an EasyAdmin entity via the field UI.

Implementation Patterns

Workflows

1. Media Assignment in EasyAdmin

   • Use MediaField in CRUD controllers for one-to-many/media relationships:

     $crud->addField(MediaField::new('gallery')->setUploadDir('gallery/%year%')->allowMultiple());
     

   • Supports single or multiple media assignments.

2. Custom Upload Directories

   • Dynamically set paths per entity type:

     $crud->addField(MediaField::new('avatar')->setUploadDir('avatars/%entity_id%'));
     

3. Integration with Forms

   • Use the EasyMediaType form field for standalone media uploads:

     $builder->add('media', EasyMediaType::class, [
         'upload_dir' => 'documents/%year%',
     ]);
     

4. Media Preview & Metadata

   • Auto-extract metadata (e.g., EXIF for images, ID3 for audio) via:

     # config/packages/easy_media.yaml
     easy_media:
         metadata_extractors:
             - AgenceAdeliom\EasyMediaBundle\Metadata\Extractor\ImageExtractor
             - AgenceAdeliom\EasyMediaBundle\Metadata\Extractor\AudioExtractor
     

5. Bulk Operations

   • Select multiple files/folders in the media manager and:
     • Delete (Ctrl+Click + toolbar button).
     • Toggle visibility (e.g., hide drafts).

Integration Tips

• Laravel-Specific: Use symfony/ux bridge to embed the Vue.js media manager in Laravel Blade:

  @routes
  @vite(['resources/js/app.js', 'node_modules/@symfony/ux-vue/dist/index.js'])
  

  Mount the media manager route in routes/web.php:

  use AgenceAdeliom\EasyMediaBundle\Controller\MediaController;
  Route::prefix('admin')->group(function () {
      Route::get('/media', [MediaController::class, 'index']);
  });
  

• EasyAdmin 4.x: For newer EasyAdmin versions, wrap the field in EasyAdmin\Field\AssociationField for relationships:

  $crud->addField(AssociationField::new('media')->setFormType(EasyMediaType::class));
  

• Custom Metadata: Extend metadata extractors for niche formats (e.g., PDF thumbnails):

  use AgenceAdeliom\EasyMediaBundle\Metadata\ExtractorInterface;
  
  class PdfExtractor implements ExtractorInterface {
      public function extract(string $path): array {
          return ['thumbnail' => $this->generateThumbnail($path)];
      }
  }
  

Gotchas and Tips

Pitfalls

1. File Naming Conflicts

   • Default behavior overwrites files with duplicate names. Use setFilenameGenerator() to customize:

     $crud->addField(MediaField::new('file')->setFilenameGenerator(
         fn($file) => uniqid().'.'.$file->guessExtension()
     ));
     

2. Permission Issues

   • Ensure the uploads/ directory is writable by the web server:

     chmod -R 775 var/uploads
     

   • Configure storage adapter in easy_media.yaml for cloud storage (e.g., S3):

     easy_media:
         storage: 'oneup_flysystem'
         adapters:
             local:
                 adapter: 'local'
                 options:
                     directory: '%kernel.project_dir%/public/uploads'
     

3. Vue.js Conflicts

   • If using Laravel Mix/Vite, ensure @symfony/ux-vue is not bundled twice. Exclude in vite.config.js:

     optimizeDeps.exclude.push('@symfony/ux-vue');
     

4. Metadata Extraction Failures

   • Debug with bin/console debug:metadata-extractors to verify registered extractors.
   • Disable extractors for performance:

     easy_media:
         metadata_extractors: []
     

Debugging

• Log Upload Paths: Enable debug mode in easy_media.yaml:

  easy_media:
      debug: true
  

  Check var/log/dev.log for resolved upload paths.

• Broken Media Links: Clear the cache after changing upload_dir:

  php bin/console cache:clear
  

Extension Points

1. Custom File Types Add MIME types to config/packages/easy_media.yaml:

   easy_media:
       allowed_mime_types: ['image/jpeg', 'image/png', 'application/pdf', 'video/mp4']
   

2. Override Templates Copy templates/easy_media/ from the bundle to your project and modify (e.g., media_manager.html.twig).

3. API Endpoints Extend the media manager API for custom actions:

   // src/Controller/MediaApiController.php
   use AgenceAdeliom\EasyMediaBundle\Api\MediaApi;
   
   class CustomMediaApi extends MediaApi {
       public function customAction(): Response {
           // ...
       }
   }
   

   Route it in config/routes.yaml:

   easy_media.api.custom:
       path: /admin/media/custom
       controller: App\Controller\MediaApiController::customAction
   

4. Event Listeners Hook into media events (e.g., post-upload):

   use AgenceAdeliom\EasyMediaBundle\Event\MediaEvents;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class MediaSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               MediaEvents::MEDIA_POST_UPLOAD => 'onMediaUpload',
           ];
       }
   
       public function onMediaUpload(MediaEvent $event) {
           // $event->getMedia()->getPath();
       }
   }