Media Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Add the bundle via Composer:

   composer require discutea/media-bundle
   

   Enable the bundle in config/bundles.php (Symfony):

   return [
       // ...
       Discutea\MediaBundle\DiscuteaMediaBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default configuration:

   php bin/console discutea:media:install
   

   Update config/packages/discutea_media.yaml to define:

   • Storage paths (e.g., local, s3).
   • Allowed file types (e.g., image/*, application/pdf).
   • Default upload directory (e.g., uploads).

3. First Upload Use the MediaManager service in a controller:

   use Discutea\MediaBundle\Manager\MediaManager;
   
   class UploadController extends AbstractController
   {
       public function upload(MediaManager $mediaManager): Response
       {
           $file = $this->request->files->get('file');
           $media = $mediaManager->upload($file, 'default_directory');
   
           return $this->json($media->getUrl());
       }
   }
   

4. Verify Check the public/uploads (or configured) directory for uploaded files.

Where to Look First

• Bundle Docs: Review config/packages/discutea_media.yaml for default settings.
• Commands: Run php bin/console list discutea to see available commands (e.g., discutea:media:install, discutea:media:clear).
• Services: Explore MediaManager, MediaRepository, and StorageAdapter in src/Manager/ and src/Repository/.
• Entities: Inspect Media entity (src/Entity/Media.php) for properties like url, mimeType, and size.

First Use Case: File Upload with Validation

Upload a file with MIME type validation and store metadata:

$file = $this->request->files->get('document');
$media = $mediaManager->upload($file, 'documents', [
    'allowed_mimes' => ['application/pdf'],
    'max_size' => 10 * 1024 * 1024, // 10MB
]);

return $this->json([
    'url' => $media->getUrl(),
    'size' => $media->getSize(),
]);

Implementation Patterns

Core Workflows

1. Uploading Files

   • Basic Upload:

     $media = $mediaManager->upload($file, 'directory_name');
     

   • Custom Storage: Configure storage_adapters in discutea_media.yaml to use S3, FTP, etc.:

     storage_adapters:
         s3:
             type: 'aws'
             options:
                 bucket: 'my-bucket'
                 region: 'us-east-1'
     

     Then pass the adapter name:

     $media = $mediaManager->upload($file, 'directory', null, 's3');
     

2. Retrieving Media

   • Fetch a single media entity:

     $media = $mediaRepository->find($mediaId);
     

   • List media in a directory:

     $mediaList = $mediaRepository->findBy(['directory' => 'documents']);
     

3. Deleting Media

   • Delete a single media entity:

     $mediaManager->delete($media);
     

   • Clear all media in a directory:

     php bin/console discutea:media:clear documents
     

Integration Tips

1. Symfony Forms Use the MediaType field for file uploads in forms:

   use Discutea\MediaBundle\Form\Type\MediaType;
   
   $builder->add('document', MediaType::class, [
       'label' => 'Upload PDF',
       'directory' => 'documents',
       'allowed_mimes' => ['application/pdf'],
   ]);
   

2. Event Listeners Subscribe to media events (e.g., MediaUploadEvent) to trigger actions post-upload:

   // src/EventListener/MediaListener.php
   public function onMediaUpload(MediaUploadEvent $event)
   {
       $media = $event->getMedia();
       // Add custom logic (e.g., generate thumbnails)
   }
   

   Register in services.yaml:

   services:
       App\EventListener\MediaListener:
           tags:
               - { name: 'kernel.event_listener', event: 'media.upload', method: 'onMediaUpload' }
   

3. API Endpoints Create RESTful endpoints for media operations:

   // src/Controller/MediaApiController.php
   #[Route('/api/media', name: 'api_media_')]
   class MediaApiController extends AbstractController
   {
       #[Route('/upload', name: 'upload', methods: ['POST'])]
       public function upload(MediaManager $manager, Request $request): JsonResponse
       {
           $file = $request->files->get('file');
           $media = $manager->upload($file, 'uploads');
           return $this->json($media->toArray());
       }
   }
   

4. Twig Integration Display media URLs in templates:

   {% for media in mediaList %}
       <img src="{{ media.getUrl() }}" alt="{{ media.name }}">
   {% endfor %}
   

Advanced Patterns

1. Custom Storage Adapters Extend StorageAdapterInterface to support new backends (e.g., Google Cloud Storage):

   class GcsAdapter implements StorageAdapterInterface
   {
       public function upload(UploadedFile $file, string $directory, string $filename): string
       {
           // Implement GCS upload logic
       }
       // ... other methods
   }
   

   Register in discutea_media.yaml:

   storage_adapters:
       gcs:
           type: 'gcs'
           options:
               bucket: 'my-gcs-bucket'
   

2. Media Processing Use the MediaProcessor service to resize images or generate thumbnails:

   $processor = $this->container->get('discutea_media.processor');
   $thumbnail = $processor->resize($media, 200, 200);
   

3. Batch Operations Process multiple files in bulk:

   $files = $request->files->get('files');
   $results = [];
   foreach ($files as $file) {
       $media = $mediaManager->upload($file, 'batch_uploads');
       $results[] = $media->getUrl();
   }
   

Gotchas and Tips

Pitfalls

1. Directory Permissions

   • Ensure the configured upload directory (e.g., public/uploads) is writable by the web server user:

     chmod -R 775 public/uploads
     

   • For Docker/Linux, use chown -R www-data:www-data public/uploads.

2. MIME Type Spoofing

   • Always validate MIME types server-side, as client-side checks can be bypassed:

     $media = $mediaManager->upload($file, 'directory', [
         'allowed_mimes' => ['image/jpeg', 'image/png'],
     ]);
     

3. Memory Limits

   • Large file uploads may hit PHP’s upload_max_filesize or post_max_size. Adjust in php.ini:

     upload_max_filesize = 20M
     post_max_size = 25M
     

4. Database Bloat

   • The Media entity stores metadata (e.g., url, size). For high-volume uploads, consider archiving old media or using a database partition.

5. CORS Issues

   • If serving media via a CDN or different domain, configure CORS headers in your web server (e.g., Nginx):

     location /uploads/ {
         add_header 'Access-Control-Allow-Origin' '*';
         add_header 'Access-Control-Allow-Methods' 'GET';
     }
     

Debugging

1. Upload Failures

   • Check var/log/dev.log for exceptions. Common causes:
     • Invalid file type (not in allowed_mimes).
     • Directory doesn’t exist (create it manually or use discutea:media:install).
     • Storage adapter misconfiguration (e.g., S3 credentials).

2. Missing Media

   • Verify the url field in the media table matches the actual file path.
   • For S3/FTP, ensure the adapter’s base_url is correct in discutea_media.yaml.

3. Performance Issues

   • Use PROFILER to trace slow uploads:

     $media = $mediaManager->upload($file