Media Library Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baconmanager/media-library-bundle
   

   Ensure your AppKernel.php includes the required bundles in this order:

   new Oneup\UploaderBundle\OneupUploaderBundle(),
   new Knp\Bundle\GaufretteBundle\KnpGaufretteBundle(),
   new Liip\ImagineBundle\LiipImagineBundle(),
   new Bacon\Bundle\MediaLibraryBundle\BaconMediaLibraryBundle(),
   new FOS\JsRoutingBundle\FOSJsRoutingBundle(),
   

2. Configuration Import the default config:

   # app/config/config.yml
   imports:
       - { resource: "@BaconMediaLibraryBundle/Resources/config/config.yml" }
   

   Add routing:

   # app/config/routing.yml
   bacon_media_library:
       resource: "@BaconMediaLibraryBundle/Controller/"
       type:     annotation
       prefix:   /media-library
   

3. First Use Case Run migrations (if provided) and clear cache:

   php bin/console doctrine:migrations:migrate
   php bin/console cache:clear
   

   Access /media-library to test the UI. Upload a file via the frontend form to verify the integration with OneupUploaderBundle and LiipImagineBundle.

Implementation Patterns

Core Workflows

1. Media Upload

   • Use the bundle’s upload form (typically in BaconMediaLibraryBundle:Media:upload).
   • Configure oneup_uploader in config.yml to define storage adapters (e.g., gaufrette for local/S3):

     oneup_uploader:
         mappings:
             media:
                 frontend: true
                 upload_directory: '%kernel.root_dir%/../web/uploads/media'
     

   • Thumbnails are auto-generated via LiipImagineBundle (configure filters in liip_imagine section).

2. Media Management

   • List media via BaconMediaLibraryBundle:Media:list (or create a custom controller extending MediaController).
   • Filter/sort media using query parameters (e.g., ?type=image&sort=created_at).

3. Integration with Entities

   • Attach media to entities by storing IDs in a media_ids field (e.g., ManyToMany with BaconMediaLibraryBundle\Model\Media).
   • Example:

     // src/AppBundle/Entity/Article.php
     /**
      * @ORM\ManyToMany(targetEntity="Bacon\Bundle\MediaLibraryBundle\Model\Media")
      */
     private $media;
     

4. Custom Templates

   • Override templates in app/Resources/BaconMediaLibraryBundle/views/ (e.g., Media/upload.html.twig).
   • Extend base templates like list.html.twig to add custom columns or actions.

Advanced Patterns

• Event Listeners Use the bundle’s events (e.g., media.pre_upload) to validate files or log uploads:

  // src/AppBundle/EventListener/MediaListener.php
  public function onPreUpload(MediaEvent $event) {
      $file = $event->getFile();
      if ($file->getClientOriginalExtension() === 'exe') {
          throw new \RuntimeException('Executables not allowed.');
      }
  }
  

  Register in services.yml:

  services:
      app.media_listener:
          class: AppBundle\EventListener\MediaListener
          tags:
              - { name: kernel.event_listener, event: media.pre_upload, method: onPreUpload }
  

• API Endpoints Create a custom API controller extending MediaController to expose media via JSON:

  use Bacon\Bundle\MediaLibraryBundle\Controller\MediaController;
  
  class ApiMediaController extends MediaController {
      public function listAction() {
          $media = $this->getMediaManager()->findAll();
          return $this->json($media);
      }
  }
  

Gotchas and Tips

Pitfalls

1. Dependency Order

   • Issue: BaconMediaLibraryBundle relies on OneupUploaderBundle and LiipImagineBundle. Misordering in AppKernel.php causes errors.
   • Fix: Load bundles in this exact order: OneupUploaderBundle → KnpGaufretteBundle → LiipImagineBundle → BaconMediaLibraryBundle.

2. Missing Migrations

   • Issue: The bundle may not include migrations for its Media entity. Manually create one if needed:

     php bin/console doctrine:migrations:diff
     

   • Tip: Check src/Resources/config/doctrine/ for entity definitions.

3. Gaufrette Configuration

   • Issue: If using KnpGaufretteBundle, ensure the adapter is properly configured in config.yml:

     knp_gaufrette:
         adapters:
             media_adapter:
                 local:
                     directory: '%kernel.root_dir%/../web/uploads/media'
         filesystems:
             media:
                 adapter: media_adapter
     

   • Tip: Verify oneup_uploader mappings point to the correct filesystem:

     oneup_uploader:
         mappings:
             media:
                 filesystem: media
     

4. JavaScript Routing

   • Issue: The bundle uses FOSJsRoutingBundle for AJAX. If routes fail, ensure:

     // app/Resources/public/js/app.js
     var routes = Routing.generate();
     

     is loaded before the bundle’s JS.

5. Thumbnail Generation

   • Issue: Thumbnails may not appear if LiipImagineBundle filters are misconfigured.
   • Fix: Define filters in config.yml:

     liip_imagine:
         filter_sets:
             media_thumbnail:
                 quality: 75
                 filters:
                     thumbnail: { size: [200, 200], mode: outbound }
     

     Then reference them in the bundle’s config:

     bacon_media_library:
         thumbnail_filter: media_thumbnail
     

Debugging Tips

• Check Uploads Directory Ensure upload_directory in oneup_uploader mappings is writable:

  chmod -R 775 %kernel.root_dir%/../web/uploads/media
  

• Symfony Profiler Use the profiler to inspect MediaEvent objects during uploads:

  // In a listener
  dump($event->getFile()->getClientOriginalName());
  

• Log Events Enable debug logging for the bundle:

  # app/config/config_dev.yml
  monolog:
      handlers:
          media:
              type: stream
              path: "%kernel.logs_dir%/media.log"
              level: debug
  

Extension Points

1. Custom Media Types Extend the Media entity to add fields (e.g., alt_text, caption):

   // src/AppBundle/Entity/MediaExtension.php
   use Bacon\Bundle\MediaLibraryBundle\Model\Media;
   
   class MediaExtension extends Media {
       /**
        * @ORM\Column(type="string", nullable=true)
        */
       private $caption;
   }
   

   Register as a service override:

   services:
       bacon.media.class: AppBundle\Entity\MediaExtension
   

2. Custom Actions Add buttons to the media list via Twig:

   {# app/Resources/BaconMediaLibraryBundle/views/Media/list.html.twig #}
   <td>
       <a href="{{ path('app_media_download', { id: media.id }) }}" class="btn btn-default">
           <i class="glyphicon glyphicon-download"></i>
       </a>
   

   Create a route and controller for app_media_download.

3. Bulk Operations Implement a bulk delete action by extending the MediaController:

   public function bulkDeleteAction(Request $request) {
       $ids = $request->request->get('media_ids');
       $this->getMediaManager()->removeByIds($ids);
       return $this->redirect($this->generateUrl('bacon_media_library_list'));
   }