Sonata Media Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require awaresoft/sonata-media-bundle
   

   If using the symlinked local version (as per README), ensure the /src/Awaresoft symlink exists and run:

   php bin/console cache:clear
   

2. Enable the Bundle: Add to config/bundles.php:

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

3. Basic Configuration: Override the default config in config/packages/sonata_media.yaml:

   sonata_media:
       db_driver: doctrine_orm # or doctrine_mongodb
       default_context: default
       contexts:
           default:
               providers:
                   - sonata.media.provider.dailymotion
                   - sonata.media.provider.youtube
                   - sonata.media.provider.image
               formats:
                   small: { width: 100 , quality: 70}
                   large: { width: 500 , quality: 70}
   

4. First Use Case: Upload an image via a form:

   {{ form_start(form) }}
       {{ form_widget(form.media) }}
       <button type="submit">Upload</button>
   {{ form_end(form) }}
   

   Controller:

   public function upload(Request $request, MediaManager $mediaManager) {
       $media = $mediaManager->create();
       $form = $this->createForm(MediaType::class, $media);
       $form->handleRequest($request);
   
       if ($form->isSubmitted() && $form->isValid()) {
           $mediaManager->save($media);
           return new RedirectResponse($this->generateUrl('home'));
       }
       return $this->render('upload.html.twig', ['form' => $form->createView()]);
   }
   

Implementation Patterns

Common Workflows

1. Media Upload & Management

• Provider Integration: Extend existing providers (e.g., sonata.media.provider.image) or create custom ones:

  // src/Provider/CustomProvider.php
  class CustomProvider extends AbstractProvider {
      public function generateUrl($media, $format = 'reference') { ... }
      public function generateHttpResponse($media, $format = 'reference') { ... }
  }
  

  Register in config:

  sonata_media:
      contexts:
          default:
              providers:
                  - app.custom_provider
  

• Form Handling: Use MediaType for uploads or MediaGalleryType for multiple files:

  $form = $this->createForm(MediaGalleryType::class, $media, [
      'provider' => 'sonata.media.provider.image',
      'context' => 'default',
  ]);
  

2. Media Display

• Twig Integration: Use the sonata_media Twig extension:

  {% set media = sonata_media.getMedia(1) %}
  <img src="{{ sonata_media.getMediaUri(media, 'small') }}" alt="{{ media.name }}">
  

  Or embed directly:

  {{ sonata_media_embed(media, 'large') }}
  

• Dynamic Formats: Generate thumbnails on-the-fly:

  $url = $mediaManager->generatePublicUrl($media, 'large');
  

3. Admin Integration

• Sonata Admin Bundle: Enable media admin in config/packages/sonata_admin.yaml:

  sonata_admin:
      templates:
          layout: 'SonataMediaBundle::standard_layout.html.twig'
  

  Create a media admin class:

  class MediaAdmin extends AbstractMediaAdmin { ... }
  

4. API Exposure

• API Platform: Annotate media entities:

  use ApiPlatform\Core\Annotation\ApiResource;
  use Sonata\MediaBundle\Entity\Media;
  
  #[ApiResource]
  class CustomMedia extends Media { ... }
  

Integration Tips

• Doctrine ORM/MongoDB: Configure db_driver in sonata_media.yaml and ensure your Media entity extends Sonata\MediaBundle\Entity\Media.

• Symfony UX Stimulus: Use Stimulus controllers for drag-and-drop uploads:

  // assets/controllers/media_controller.js
  import { Controller } from '@hotwired/stimulus';
  export default class extends Controller {
      connect() {
          this.element.addEventListener('change', (e) => {
              const files = e.target.files;
              // Handle files via fetch API
          });
      }
  }
  

• Cloud Storage: Use providers like sonata.media.provider.aws_s3 or sonata.media.provider.gcs for cloud storage.

Gotchas and Tips

Pitfalls

1. Symlink Issues:

   • If using local symlinks, ensure autoload_psr4.php is updated manually after changes.
   • Clear cache after symlink modifications:

     php bin/console cache:clear --env=prod --no-debug
     

2. Provider Conflicts:

   • Avoid duplicate provider names in sonata_media.yaml. Use unique keys (e.g., app.custom_provider).

3. Media Entity Inheritance:

   • Extend Sonata\MediaBundle\Entity\Media directly or use MediaHashed for hashed filenames:

     use Sonata\MediaBundle\Entity\MediaHashed;
     class CustomMedia extends MediaHashed { ... }
     

4. File Size Limits:

   • Configure max_file_size in sonata_media.yaml to avoid upload failures:

     sonata_media:
         providers:
             sonata.media.provider.image:
                 max_file_size: 10M
     

5. Twig Debugging:

   • Use {{ dump(sonata_media) }} to inspect available media and formats in Twig templates.

Debugging

• Log Media Events: Enable debug mode and check logs for media-related errors:

  php bin/console debug:config sonata_media
  

• Provider Validation: Test providers in isolation:

  $provider = $this->container->get('sonata.media.provider.image');
  $media = $mediaManager->find(1);
  $url = $provider->generateUrl($media, 'small');
  

• Doctrine Events: Listen for media lifecycle events:

  // src/EventListener/MediaListener.php
  class MediaListener {
      public function onMediaPrePersist(Media $media) {
          // Custom logic before save
      }
  }
  

  Register in services.yaml:

  services:
      App\EventListener\MediaListener:
          tags:
              - { name: doctrine.event_listener, event: prePersist }
  

Extension Points

1. Custom Media Types: Extend MediaType to add custom fields:

   class CustomMediaType extends MediaType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           $builder->add('custom_field', TextType::class);
       }
   }
   

2. Media Filters: Create custom filters for admin lists:

   class CustomMediaFilter extends FilterForm {
       protected function createQueryBuilder($queryBuilder, $alias, $field, $value) {
           // Custom filtering logic
       }
   }
   

3. Media Events: Dispatch custom events:

   $dispatcher->dispatch(new MediaEvent($media, 'custom.event'));
   

   Listen in services:

   services:
       App\EventListener\CustomMediaListener:
           tags:
               - { name: kernel.event_listener, event: custom.event, method: onCustomEvent }
   

4. Media Metadata: Override metadata handling:

   class CustomMediaManager extends MediaManager {
       public function generatePublicUrl(MediaInterface $media, $format = 'reference') {
           // Custom URL generation
       }
   }
   

   Register as a service:

   services:
       sonata.media.manager.media:
           class: App\Service\CustomMediaManager