Mediabundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ant/mediabundle
   

   Ensure sonata-project/media-bundle (v2.2.x-dev) is installed as a dependency.

2. Bundle Registration Add to config/bundles.php:

   return [
       // ...
       Ant\MediaBundle\AntMediaBundle::class => ['all' => true],
   ];
   

3. Database & Configuration Run migrations (if provided) and configure config/packages/ant_media.yaml:

   ant_media:
       db_driver: doctrine # or 'orm'/'mongodb'
       filesystem:
           local:
                 directory: '%kernel.project_dir%/public/uploads'
   

4. First Use Case Create a media entity (e.g., app/src/Entity/Image.php) and tag it with @ORM\Table + @ORM\Entity:

   use Sonata\MediaBundle\Model\MediaInterface;
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   class Image implements MediaInterface {
       // Required fields (e.g., `protected $providerName`, `protected $binaryContent`)
   }
   

   Register the provider in config/packages/sonata_media.yaml:

   sonata_media:
       providers:
           image:
               service: sonata.media.provider.image
               formats: [small, medium, large]
   

Implementation Patterns

Core Workflows

1. Uploading Media Use the SonataMediaManager service to handle uploads:

   $mediaManager = $this->get('sonata.media.manager.media');
   $media = $mediaManager->create([
       'provider_name' => 'sonata.media.provider.image',
       'context' => 'default',
       'enabled' => true,
   ]);
   $media->setBinaryContent($file->getContent());
   $mediaManager->save($media);
   

2. Generating Thumbnails Leverage Sonata’s built-in providers (e.g., image, video):

   # config/packages/sonata_media.yaml
   sonata_media:
       providers:
           image:
               formats:
                   small: { width: 100, quality: 70 }
                   medium: { width: 300 }
   

   Access thumbnails via:

   $media->getThumbnailUrl('small');
   

3. Integration with Forms Use SonataMediaType in Symfony forms:

   use Sonata\MediaBundle\Form\Type\MediaType;
   
   $builder->add('image', MediaType::class, [
       'provider' => 'image',
       'context' => 'default',
       'required' => false,
   ]);
   

4. Admin Panel Extend SonataAdminBundle to manage media:

   use Sonata\AdminBundle\Admin\AbstractAdmin;
   use Sonata\MediaBundle\Admin\MediaAdmin;
   
   class ImageAdmin extends MediaAdmin {
       protected $datamodel = 'Ant\MediaBundle\Model\Image';
   }
   

Advanced Patterns

• Custom Providers: Extend Sonata\MediaBundle\Model\MediaProvider for non-standard formats (e.g., PDF, 3D models).
• Events: Listen to sonata.media.create or sonata.media.update for post-processing (e.g., video transcoding).
• API Exposure: Use FOSRestBundle to expose media endpoints:

  # config/routes.yaml
  sonata_media.api.media:
      path: /api/media
      methods: [GET]
      defaults: { _controller: sonata.media.controller.api.media }
  

Gotchas and Tips

Pitfalls

1. Dependency Conflicts

   • sonata-project/media-bundle:2.2.x-dev is a dev branch. Test thoroughly; expect breaking changes.
   • Avoid mixing with stable sonata-project/media-bundle (v3+). Use composer why-not ant/mediabundle to check conflicts.

2. Filesystem Permissions Ensure the directory in ant_media.filesystem.local is writable by the web server:

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

3. ORM vs. DBAL The bundle defaults to Doctrine ORM. For non-Doctrine setups, configure db_driver: doctrine_dbal and adjust MediaManager services.

4. Media Contexts Contexts (e.g., default) are not shared between providers. Define contexts explicitly in sonata_media.yaml:

   sonata_media:
       contexts:
           default: ~
           gallery: { providers: [image, video] }
   

Debugging Tips

• Check Media Status: Use MediaManager::findAll() to verify saved media. Missing provider_name or binaryContent causes silent failures.
• Logs: Enable Sonata’s debug mode:

  sonata_media:
      debug: true
  

• Provider Validation: Override MediaProvider to add validation:

  public function validate(MediaInterface $media) {
      if (empty($media->getBinaryContent())) {
          throw new \RuntimeException('Binary content is required.');
      }
  }
  

Extension Points

1. Custom Metadata Add fields to MediaInterface via traits or inheritance:

   use Sonata\MediaBundle\Model\MediaTrait;
   
   class CustomMedia {
       use MediaTrait;
       protected $customField;
   }
   

2. Pre-Processing Hook into sonata.media.pre_persist event to resize/optimize uploads:

   $eventDispatcher->addListener('sonata.media.pre_persist', function ($event) {
       $media = $event->getSubject();
       // Resize image here
   });
   

3. Cloud Storage Replace the local filesystem provider with AWS/S3:

   ant_media:
       filesystem:
           aws:
               service: sonata.media.filesystem.aws
               bucket: my-media-bucket