Media Manager Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require canal-tp/media-manager-bundle
   

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

   CanalTP\MediaManagerBundle\CanalTPMediaManagerBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php bin/console canal:media-manager:install
   

   Update config/packages/canal_tp_media_manager.yaml to define:

   • Storage paths (local, S3, etc.)
   • Allowed MIME types
   • Default upload directories

3. First Use Case: Uploading a File Inject the MediaManager service and use the upload() method:

   use CanalTP\MediaManagerBundle\Service\MediaManager;
   
   class MyController extends AbstractController {
       public function uploadFile(MediaManager $mediaManager, Request $request): Response {
           $file = $request->files->get('file');
           $media = $mediaManager->upload($file, 'products'); // 'products' = directory
   
           return $this->json($media->getUrl());
       }
   }
   

Implementation Patterns

Core Workflows

1. File Uploads with Metadata Attach metadata (e.g., alt, title) during upload:

   $media = $mediaManager->upload($file, 'products', [
       'alt' => 'Product Image',
       'title' => 'Premium Widget',
   ]);
   

2. Custom Storage Adapters Extend CanalTP\MediaManagerBundle\Storage\StorageInterface for cloud storage (e.g., AWS S3):

   class S3Storage implements StorageInterface {
       public function save($file, $path): string { /* ... */ }
       public function delete($path): bool { /* ... */ }
   }
   

   Register in config:

   canal_tp_media_manager:
       storage:
           default: s3
           adapters:
               s3: CanalTP\MediaManagerBundle\Storage\S3Storage
   

3. Transformations (Resizing, Thumbnails) Use the transform() method with predefined presets:

   # config/packages/canal_tp_media_manager.yaml
   presets:
       thumbnail: { width: 200, height: 200, fit: 'crop' }
   

   Apply in code:

   $media->transform('thumbnail');
   

4. Entity Integration (Doctrine) Map media to entities via Media entity:

   use CanalTP\MediaManagerBundle\Entity\Media;
   
   class Product {
       #[ORM\ManyToOne(targetEntity: Media::class)]
       private ?Media $image = null;
   }
   

Integration Tips

• Symfony Forms: Use CanalTP\MediaManagerBundle\Form\Type\MediaType for file upload fields.
• APIs: Return media URLs via API responses (e.g., media->getUrl()).
• Events: Listen to media.uploaded or media.deleted events for post-processing.

Gotchas and Tips

Common Pitfalls

1. Permissions Ensure the storage directory (public/uploads by default) is writable:

   chmod -R 775 public/uploads
   

   For S3, verify IAM roles have s3:PutObject permissions.

2. MIME Type Restrictions Default config blocks unsafe types (e.g., .php). Whitelist in config:

   allowed_mimes: ['image/jpeg', 'image/png', 'application/pdf']
   

3. Path Collisions Avoid hardcoding paths. Use mediaManager->getStorage()->getPath() for dynamic paths.

4. Large Files Increase PHP upload limits in php.ini:

   upload_max_filesize = 20M
   post_max_size = 25M
   

Debugging

• Logs: Enable debug mode (APP_DEBUG=true) to log upload errors.
• Storage Issues: Check var/log/dev.log for CanalTP\MediaManagerBundle entries.
• Database: Verify media table entries if using Doctrine.

Extension Points

1. Custom Validators Override CanalTP\MediaManagerBundle\Validator\Constraints\File to add rules (e.g., max dimensions):

   use Symfony\Component\Validator\Constraints\Expression;
   
   $constraints = new Expression(
       'value.getSize() < 5MB',
       'File too large (max 5MB)'
   );
   

2. Post-Upload Actions Subscribe to events:

   // src/EventListener/MediaUploadListener.php
   class MediaUploadListener {
       public function onMediaUploaded(MediaUploadedEvent $event) {
           // Send notification, update DB, etc.
       }
   }
   

   Register in services.yaml:

   CanalTP\MediaManagerBundle\EventListener\MediaUploadListener:
       tags:
           - { name: kernel.event_listener, event: media.uploaded, method: onMediaUploaded }
   

3. Custom Metadata Fields Extend the Media entity:

   #[ORM\Column(nullable: true)]
   private ?string $customField = null;
   

   Update migrations and forms accordingly.

Pro Tips

• Presets: Define reusable presets (e.g., social_share, product_gallery) in config to avoid repetition.
• Fallback Storage: Configure a fallback adapter in case the primary fails:

  storage:
      fallback: local
  

• Soft Deletes: Enable soft deletes for media records:

  soft_delete: true