Media Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cwd/media-bundle
   

   Add to AppKernel.php (Symfony 2.x) or config/bundles.php (Symfony 3.x/4.x):

   new Cwd\MediaBundle\CwdMediaBundle(),
   

2. Configuration: Override default settings in config/packages/cwd_media.yaml (Symfony 4.x+) or app/config/config.yml:

   cwd_media:
       upload_dir: '%kernel.project_dir%/public/uploads'
       allowed_types: ['image/jpeg', 'image/png']
   

3. First Use Case:

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

     use Cwd\MediaBundle\Form\Type\MediaType;
     
     $builder->add('media', MediaType::class);
     

   • Handle upload in controller:

     $media = $form->get('media')->getData();
     $file = $media->getFile(); // Uploaded file object
     

Implementation Patterns

Workflow Integration

1. File Upload Handling:

   • Use Cwd\MediaBundle\Service\MediaService to process files:

     $mediaService = $this->get('cwd_media.media_service');
     $media = $mediaService->upload($file, 'user_avatars');
     

   • Store metadata (e.g., path, mime_type) in your entity.

2. Entity Mapping:

   • Extend Cwd\MediaBundle\Entity\Media or embed fields in your own entity:

     /**
      * @ORM\Embedded(class="Cwd\MediaBundle\Entity\Media")
      */
     private $media;
     

3. Twig Integration:

   • Use media_path() helper to generate URLs:

     <img src="{{ media_path(media) }}" alt="{{ media.name }}">
     

4. Batch Processing:

   • Loop through MediaType collections in forms:

     $builder->add('gallery', CollectionType::class, [
         'entry_type' => MediaType::class,
         'allow_add'   => true,
         'allow_delete' => true,
     ]);
     

Gotchas and Tips

Pitfalls

1. Deprecated Symfony 2.x:

   • Last release predates Symfony 3.x+ features (e.g., no Flex support). Manual config required.
   • Fix: Use symfony/flex recipes or vendor patches for newer Symfony.

2. No Database Abstraction:

   • Assumes Doctrine ORM. For other DBALs, manually map Media entity fields.

3. Hardcoded Upload Logic:

   • upload_dir is global. Override via config or extend MediaService:

     class CustomMediaService extends MediaService {
         protected function getUploadDir() { return $this->container->getParameter('custom.upload_dir'); }
     }
     

Debugging

• File Permissions: Ensure upload_dir is writable by PHP (chmod -R 775 uploads/).

• Validation Errors: Check allowed_types in config. Extend via:

  cwd_media:
      allowed_types: ['image/*', 'application/pdf']
  

Extension Points

1. Custom Storage: Override MediaService::upload() to use S3/AWS:

   public function upload(File $file, $dir) {
       $s3 = $this->get('aws_s3.client');
       // Custom logic...
   }
   

2. Event Listeners: Hook into cwd_media.upload.post event to process files post-upload:

   $dispatcher->addListener('cwd_media.upload.post', function($event) {
       $media = $event->getMedia();
       // Resize, optimize, etc.
   });
   

3. Twig Filters: Extend media_path() with custom logic:

   {{ media_path(media, {'width': 200}) }}  {# Custom filter #}