Media Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ekyna/media-bundle
   

   Add to config/bundles.php:

   Ekyna\MediaBundle\EkynaMediaBundle::class => ['all' => true],
   

2. Database Migration Run:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

   The bundle creates tables for media (files), folders, and media_gallery (if enabled).

3. First Use Case: Upload a File

   • Create a form with Ekyna\MediaBundle\Form\Type\MediaType:

     use Ekyna\MediaBundle\Form\Type\MediaType;
     
     $builder->add('media', MediaType::class, [
         'label' => 'Upload Media',
         'mapped' => false, // For standalone uploads
     ]);
     

   • Submit the form to a controller handling Media entity persistence.

4. Basic Configuration Edit config/packages/ekyna_media.yaml (auto-generated):

   ekyna_media:
       upload_dir: '%kernel.project_dir%/public/uploads'
       allowed_mime_types: ['image/jpeg', 'image/png', 'application/pdf']
       max_file_size: 10M
   

Implementation Patterns

Core Workflows

1. File Upload & Storage

   • Use Media entity for file metadata (e.g., title, description, folder).
   • Example controller:

     public function upload(Request $request, MediaManager $mediaManager)
     {
         $media = $mediaManager->upload($request->file('media'));
         return new JsonResponse(['url' => $media->getUrl()]);
     }
     

   • Tip: Chain with save() to persist to DB:

     $mediaManager->upload($file)->save();
     

2. Folder Management

   • Create folders via Folder entity or FolderManager:

     $folder = $folderManager->create('images', 'root');
     $media->setFolder($folder);
     

   • Pattern: Use tree structure for nested folders (e.g., root/photos/vacation).

3. Gallery Integration

   • Enable gallery feature in config:

     ekyna_media:
         gallery:
             enabled: true
     

   • Create galleries via Gallery entity or GalleryManager:

     $gallery = $galleryManager->create('My Gallery');
     $gallery->addMedia($media);
     

4. Frontend Integration

   • Symfony UX Turbo: Use MediaType with Turbo for live previews.
   • Blueimp jQuery-File-Upload: Configure in Twig:

     {{ include('EkynaMediaBundle::upload.html.twig', {
         'mediaType': mediaType,
         'options': {'maxFileSize': 1000000}
     }) }}
     

   • Tip: Extend JS validation via data-validate-* attributes (e.g., data-validate-max-number="3").

5. API Endpoints

   • Use MediaController (auto-registered) for CRUD:
     • GET /api/media → List media.
     • POST /api/media → Upload.
   • Customize routes in config/routes.yaml:

     ekyna_media:
         resource: '@EkynaMediaBundle/Resources/config/routing.yaml'
         prefix: '/api'
     

Integration Tips

1. Event Listeners

   • Subscribe to MediaEvents (e.g., MediaUploadEvent):

     public static function getSubscribedEvents()
     {
         return [
             MediaEvents::MEDIA_UPLOADED => 'onMediaUploaded',
         ];
     }
     

   • Use Case: Auto-generate thumbnails or log uploads.

2. Custom Fields

   • Extend Media entity with traits or inheritance:

     class CustomMedia extends Media
     {
         private $customField;
     
         // Add getter/setter + DB mapping.
     }
     

3. Validation

   • Override MediaValidator for custom rules:

     $validator->addConstraint(new CustomMediaConstraint());
     

4. Symfony Messenger

   • Dispatch MediaUploadedMessage for async processing:

     $bus->dispatch(new MediaUploadedMessage($media));
     

Gotchas and Tips

Pitfalls

1. Missing upload_dir Permissions

   • Error: Permission denied on upload.
   • Fix: Ensure public/uploads is writable:

     chmod -R 775 %kernel.project_dir%/public/uploads
     

2. MIME Type Restrictions

   • Gotcha: Default allowed_mime_types blocks common formats.
   • Fix: Extend config:

     ekyna_media:
         allowed_mime_types: ['image/*', 'video/*', 'application/pdf']
     

3. Gallery Positioning

   • Issue: GalleryMediaSubscriber may not set position correctly.
   • Workaround: Manually set position in GalleryMedia:

     $galleryMedia->setPosition($media->getId()); // Or custom logic.
     

4. JS Upload Validation

   • Problem: Client-side validation fails silently.
   • Debug: Check data-validate-* attributes in Blueimp config:

     $.ajaxSetup({
         beforeSend: function() {
             console.log('Validation rules:', $('#fileupload').data('validate'));
         }
     });
     

5. Folder Persistence

   • Gotcha: Folders aren’t auto-saved with media.
   • Fix: Explicitly save the folder:

     $folderManager->save($folder);
     

Debugging

1. Upload Failures

   • Check MediaEvents::MEDIA_UPLOAD_FAILED event payload for errors.
   • Enable debug in config:

     ekyna_media:
         debug: true
     

2. Entity Mapping

   • Tool: Use make:entity to regenerate Media if custom fields break migrations.

3. Route Conflicts

   • Tip: Override routes in config/routes.yaml to avoid clashes with other bundles.

Extension Points

1. Custom Storage

   • Implement Ekyna\MediaBundle\Storage\StorageInterface for S3/Azure:

     class S3Storage implements StorageInterface {
         public function save(File $file): string { ... }
     }
     

   • Register in config:

     ekyna_media:
         storage: Ekyna\MediaBundle\Storage\S3Storage
     

2. Media Transformers

   • Extend MediaTransformer for custom image/video processing:

     $transformer = new CustomTransformer();
     $media->setThumbnail($transformer->transform($media));
     

3. Event Subscribers

   • Override GalleryMediaSubscriber for custom gallery logic (e.g., auto-tagging).

4. Twig Extensions

   • Add helpers to EkynaMediaBundle:

     $twig->addFunction(new \Twig\TwigFunction('media_url', [$mediaManager, 'getUrl']));