Mediabrowser Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require ecommit/mediabrowser-bundle
   

   Enable the bundle in config/bundles.php:

   Ecommit\MediaBrowserBundle\EcommitMediaBrowserBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php bin/console ecommit:mediabrowser:install
   

   Update config/packages/ecommit_media_browser.yaml with your storage paths (e.g., uploads/).

3. First Use Case Upload a file via the built-in controller:

   php bin/console make:controller MediaUploadController
   

   Use the MediaBrowserController in your route:

   # config/routes.yaml
   ecommit_media_browser:
       resource: "@EcommitMediaBrowserBundle/Resources/config/routing.yml"
       prefix: /media
   

   Access /media/browser in your browser to test the file manager UI.

Implementation Patterns

Core Workflows

1. File Uploads

   • Use the MediaBrowserController for drag-and-drop uploads. Extend with custom validation in config/packages/ecommit_media_browser.yaml:

     ecommit_media_browser:
         allowed_mime_types: ['image/jpeg', 'image/png', 'application/pdf']
         max_file_size: 10M
     

   • Trigger uploads via JavaScript (e.g., Dropzone.js) or direct form submissions.

2. File Management

   • Browse/Delete: Leverage the /media/browser endpoint for CRUD operations.
   • API Access: Fetch files via GET /media/api/files (returns JSON with metadata like id, path, mime_type).

3. Integration with Entities

   • Store file references in Eloquent models:

     use Ecommit\MediaBrowserBundle\Entity\Media;
     
     class Post extends Model {
         public function media() {
             return $this->morphToMany(Media::class, 'model');
         }
     }
     

   • Use the MediaBrowserService to attach files:

     $media = $this->mediaBrowserService->upload($request->file('file'));
     $post->media()->attach($media);
     

4. Custom Storage

   • Override storage adapters (e.g., S3) by extending Ecommit\MediaBrowserBundle\Storage\StorageInterface and binding it in services.yaml:

     services:
         App\Storage\CustomStorage:
             arguments:
                 - '@aws_s3.client'
             tags: ['ecommit_media_browser.storage']
     

Gotchas and Tips

Pitfalls

1. Permissions

   • Ensure the uploads/ directory (or custom path) is writable by the web server:

     chmod -R 775 var/uploads
     

   • Debug 403 errors with storage:link:

     php bin/console assets:install public
     php bin/console storage:link
     

2. Mime-Type Validation

   • False positives? Extend the MimeTypeValidator service:

     // src/Service/MimeTypeValidator.php
     class CustomMimeTypeValidator extends MimeTypeValidator {
         protected function getAllowedTypes() {
             return array_merge(parent::getAllowedTypes(), ['video/mp4']);
         }
     }
     

     Bind it in services.yaml:

     services:
         App\Service\CustomMimeTypeValidator:
             decorates: 'ecommit_media_browser.mime_type_validator'
     

3. Database Overhead

   • Disable metadata tracking if unused:

     ecommit_media_browser:
         track_metadata: false
     

Debugging

• Log Uploads: Enable debug mode in config/packages/ecommit_media_browser.yaml:

  debug: true
  

  Check var/log/dev.log for upload events.

• SQL Queries: Use Laravel’s query logger or tinker to inspect the media table:

  php artisan tinker
  >>> \DB::table('media')->get();
  

Extension Points

1. Custom Fields Add metadata fields via a database migration:

   Schema::table('media', function (Blueprint $table) {
       $table->string('custom_field')->nullable();
   });
   

   Extend the Media entity to include them.

2. Event Listeners Hook into upload events (e.g., resize images):

   // src/EventListener/MediaUploadListener.php
   class MediaUploadListener {
       public function onUpload(MediaUploadEvent $event) {
           if ($event->getMedia()->getMimeType() === 'image/jpeg') {
               // Resize logic here
           }
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\MediaUploadListener:
           tags:
               - { name: kernel.event_listener, event: ecommit.media.upload, method: onUpload }
   

3. Twig Integration Embed files in templates:

   {% for media in post.media %}
       <img src="{{ media.getUrl('thumb') }}" alt="{{ media.title }}">
   {% endfor %}
   

   Add custom presets in config/packages/ecommit_media_browser.yaml:

   presets:
       thumb:
           width: 200
           height: 200
           mode: outbound