Media Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require armetiz/media-bundle
   

   Enable the bundle in AppKernel.php:

   new Armetiz\MediaBundle\ArmetizMediaBundle(),
   

2. Basic Configuration (config.yml):

   armetiz_media:
       contexts:
           default:
               providers:
                   armetiz.media.provider.image:
                       formats:
                           thumbnail: { width: 200 }
   

3. First Use Case: Upload an image via a form (e.g., using Symfony's File type) and save it to the default storage (web/medias). Use Twig to render it:

   {{ media(mediaObject, 'thumbnail') }}
   

Implementation Patterns

Core Workflow

1. Media Storage:

   • Use the default filesystem (web/medias) or configure a custom one (e.g., S3 via Gaufrette).
   • Example for S3:

     armetiz_media:
         filesystems:
             s3:
                 id: gaufrette.s3
     

2. Contexts and Providers:

   • Define contexts to map media types to providers (e.g., image, youtube).
   • Prioritize providers by placing the most restrictive first (e.g., image before file).
   • Example:

     contexts:
         default:
             providers:
                 armetiz.media.provider.youtube: ~
                 armetiz.media.provider.image: ~
     

3. Transformations:

   • Use built-in transformers (e.g., image_to_thumbnail) or create custom ones.
   • Example for a thumbnail:

     {{ media(mediaObject, 'thumbnail', { width: 300 }) }}
     

4. CDN Integration:

   • Configure a CDN base URL for optimized delivery:

     cdns:
         local:
             base_url: %website_url%/medias
     

5. Twig Helpers:

   • Render media with templates, get raw data, or fetch URIs:

     {{ media(mediaObject, 'thumbnail', { template: 'media/thumbnail.html.twig' }) }}
     {{ mediaUri(mediaObject, 'thumbnail') }}
     

Integration Tips

• Forms: Use Symfony's File type to handle uploads and save media entities.
• Entities: Store media references in Doctrine entities (e.g., OneToOne with Armetiz\MediaBundle\Entity\Media).
• Validation: Validate file types/sizes before processing (e.g., using Symfony's File constraints).

Gotchas and Tips

Pitfalls

1. Provider Order:

   • If multiple providers handle a media type, the first defined provider takes precedence. Reorder contexts/providers if unexpected behavior occurs.

2. Transformer Configuration:

   • Default transformer options (e.g., engine: gd) may conflict with custom options. Merge them explicitly:

     formats:
         thumbnail:
             transformer: armetiz.media.transformer.image_to_thumbnail
             transformer_options:
                 engine: imagick  # Overrides default
     

3. Context Detection:

   • Avoid relying on automatic context/provider detection. Explicitly set them in the Media entity to ensure consistency across contexts.

4. Twig Template Overrides:

   • Customize media rendering by overriding Twig templates (e.g., media/thumbnail.html.twig) in your bundle's Resources/views.

5. CDN Caching:

   • Ensure CDN URLs are cache-friendly (e.g., include version hashes or timestamps in filenames).

Debugging

• Logs: Enable debug mode (%kernel.debug%: true) to inspect provider/media resolution.
• Dumping Contexts:

  $mediaManager = $this->get('armetiz.media.manager');
  dump($mediaManager->getContexts());
  

Extension Points

1. Custom Providers:

   • Extend Armetiz\MediaBundle\Provider\AbstractProvider to support new media types (e.g., SoundCloud, Instagram).

2. Transformers:

   • Create custom transformers by implementing Armetiz\MediaBundle\Transformer\TransformerInterface.

3. Filesystems:

   • Integrate additional Gaufrette adapters (e.g., Rackspace, Azure) by configuring them in filesystems.

4. Twig Extensions:

   • Extend Twig helpers by overriding the ArmetizMediaTwigExtension service.

Pro Tips

• Lazy Loading: Use lazy-loaded media entities to defer filesystem operations until rendering.
• Batch Processing: Process multiple media files in bulk (e.g., during cron jobs) using the MediaManager.
• Fallbacks: Define fallback providers for unsupported media types (e.g., default to file provider).