Media Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require sonata-project/media-bundle
   

   Add to config/bundles.php (Symfony):

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

2. Database & Fixtures Run migrations:

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

   Load default media providers (e.g., sonata.media.provider.image):

   php bin/console sonata:easy-extends:generate SonataMediaBundle
   

3. First Use Case: Uploading an Image

   • Create a form with SonataMediaType:

     use Sonata\MediaBundle\Form\Type\MediaType;
     
     $builder->add('image', MediaType::class, [
         'provider' => 'sonata.media.provider.image',
     ]);
     

   • Upload an image via the admin interface (/admin/media) or programmatically:

     $mediaManager = $this->get('sonata.media.manager.media');
     $media = $mediaManager->create();
     $media->setProviderValue('image', $file); // $file is an UploadedFile
     $mediaManager->save($media);
     

Implementation Patterns

Common Workflows

1. Media Management

   • Admin CRUD: Use Sonata’s built-in admin (/admin/media) for manual uploads.
   • Programmatic Uploads: Attach files to entities via Media model:

     $post->setMedia([$media]); // Assuming $post has a `media` relation
     $entityManager->persist($post);
     $entityManager->flush();
     

2. Custom Providers

   • Extend Sonata\MediaBundle\Model\MediaProviderInterface for new formats (e.g., PDFs, videos):

     class CustomProvider extends AbstractProvider
     {
         public function generatePublicUrl($directory, $name)
         {
             return "/uploads/custom/{$name}";
         }
     }
     

   • Register in config/packages/sonata_media.yaml:

     sonata_media:
         providers:
             sonata.media.provider.custom:
                 class: App\Provider\CustomProvider
     

3. Thumbnails & Transformations

   • Use sonata.media.thumbnail.format to generate thumbnails:

     $thumbnail = $media->getThumbnail('small');
     

   • Configure formats in config/packages/sonata_media.yaml:

     sonata_media:
         formats:
             small: { width: 100, quality: 90 }
     

4. Integration with Entities

   • Add ManyToOne/ManyToMany relations to entities:

     /**
      * @ORM\ManyToOne(targetEntity="Sonata\MediaBundle\Entity\Media", inversedBy="posts")
      */
     private $featuredImage;
     

   • Use MediaType in forms to auto-populate relations.

5. API Exposure

   • Serialize media with sonata.media.api.read:

     $serializer = $this->get('serializer');
     $mediaData = $serializer->serialize($media, 'json', ['groups' => ['media']]);
     

Gotchas and Tips

Pitfalls

1. Provider Configuration

   • Forgetting to register providers in sonata_media.yaml will break uploads.
   • Fix: Verify providers section includes all custom providers.

2. File Permissions

   • Media files must be writable by the web server (e.g., chmod -R 775 var/media).

3. Thumbnail Generation

   • Thumbnails fail silently if imagick/gd PHP extensions are missing.
   • Fix: Install extensions (sudo apt-get install php-imagick) and restart PHP.

4. Caching Issues

   • Clear cache after adding new providers/formats:

     php bin/console cache:clear
     

5. Entity Relations

   • Bidirectional relations (inversedBy) must match exactly (case-sensitive).
   • Fix: Use make:entity to generate correct relations.

Debugging Tips

• Log Upload Errors: Enable debug mode and check var/log/dev.log for SonataMediaBundle errors.
• Test Providers: Use php bin/console sonata:media:debug to list available providers.
• Clear Media Cache: Run php bin/console sonata:media:clear-cache if thumbnails appear broken.

Extension Points

1. Custom Media Models

   • Extend Sonata\MediaBundle\Entity\Media to add fields (e.g., altText):

     class CustomMedia extends Media
     {
         /**
          * @ORM\Column(type="string", nullable=true)
          */
         private $altText;
     }
     

   • Update sonata_media.yaml to use the new class.

2. Event Listeners

   • Hook into sonata.media.post_persist to auto-tag media:

     $event->getSubject()->setContext(['tags' => ['uploaded']]);
     

3. Custom Admin

   • Override the media admin class to add fields:

     sonata_admin:
         options:
             group: 'Media'
             label: 'Custom Media'
             label_catalogue: 'sonata_media'
             class: App\Entity\CustomMedia