Bigfoot Media Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require 7rin0/bigfoot-media-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       SevenRin0\BigfootMediaBundle\SevenRin0BigfootMediaBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console bigfoot:media:install
   

   Update config/packages/bigfoot_media.yaml to define:

   • media_root (e.g., %kernel.project_dir%/public/uploads)
   • allowed_mime_types (e.g., ['image/jpeg', 'image/png'])
   • max_file_size (e.g., 10M)

3. First Use Case: Uploading Media Use the MediaUploader service in a controller:

   use SevenRin0\BigfootMediaBundle\Service\MediaUploader;
   
   class UploadController extends AbstractController {
       public function upload(MediaUploader $uploader, Request $request): Response {
           $file = $request->files->get('file');
           $media = $uploader->upload($file, 'user_avatars'); // 'user_avatars' is a "media type"
           return $this->json($media->getUrl());
       }
   }
   

4. Database Setup Run migrations to create the media table:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

Implementation Patterns

Core Workflows

1. Media Types & Storage

   • Define media types in config/packages/bigfoot_media.yaml:

     media_types:
         user_avatars:
             storage: local
             path: '%bigfoot_media.media_root%/avatars'
             allowed_mime_types: ['image/jpeg', 'image/png']
             max_size: 5M
     

   • Use media_type to enforce rules per use case (e.g., documents, thumbnails).

2. Uploading with Validation Chain validation with uploads:

   $media = $uploader->upload($file, 'user_avatars', [
       'validate_mime_type' => true,
       'validate_max_size' => true,
   ]);
   

3. Accessing Media Retrieve media via:

   • Entity Repository:

     $media = $this->getDoctrine()->getRepository(Media::class)->findOneBy(['id' => 1]);
     $url = $media->getUrl(); // e.g., "/uploads/avatars/123.jpg"
     

   • Twig:

     <img src="{{ media.getUrl() }}" alt="{{ media.title }}">
     

4. Deleting Media

   $uploader->delete($media); // Removes file + DB record
   

Integration Tips

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

   use SevenRin0\BigfootMediaBundle\Form\Type\MediaType;
   
   $builder->add('avatar', MediaType::class, [
       'label' => 'Profile Picture',
       'media_type' => 'user_avatars',
   ]);
   

2. Event Listeners Trigger actions on upload/delete:

   // config/services.yaml
   SevenRin0\BigfootMediaBundle\EventListener\MediaListener:
       tags:
           - { name: kernel.event_listener, event: bigfoot.media.upload, method: onUpload }
   

3. Custom Storage Extend Storage\AbstractStorage for cloud storage (e.g., S3):

   class S3Storage extends AbstractStorage {
       public function save(FileInfo $fileInfo): Media {
           // Custom S3 logic
       }
   }
   

4. API Responses Serialize media in APIs:

   use SevenRin0\BigfootMediaBundle\Serializer\MediaNormalizer;
   
   // In config/packages/serializer.yaml
   attributes:
       normalization:
           object_to_populate: null
           enabled: true
           missing_image: 'no-image.jpg'
   

Gotchas and Tips

Pitfalls

1. Permissions

   • Ensure media_root is writable by the web server:

     chmod -R 775 %kernel.project_dir%/public/uploads
     

   • Debug 403 errors with chmod or SELinux policies.

2. Mime Type Validation

   • False positives? Extend MimeTypeValidator or whitelist edge cases:

     # config/packages/bigfoot_media.yaml
     mime_type_whitelist:
         'image/jpeg': ['jpg', 'jpeg']
     

3. Circular Dependencies

   • Avoid loading the bundle in AppKernel if using Symfony Flex (use config/bundles.php instead).

4. Doctrine Events

   • Media deletion triggers preRemove/postRemove events. Override cautiously to avoid infinite loops.

Debugging

1. Log Uploads Enable debug mode and check var/log/dev.log for:

   # config/packages/monolog.yaml
   handlers:
       bigfoot:
           type: stream
           path: "%kernel.logs_dir%/bigfoot_media.log"
           level: debug
   

2. Common Errors

   • "File not found": Verify media_root path and file permissions.
   • "Invalid MIME type": Check allowed_mime_types and file extensions.
   • Duplicate filenames: Use unique_filename: true in config or implement FileNamerInterface.

Extension Points

1. Custom File Naming Implement SevenRin0\BigfootMediaBundle\Service\FileNamerInterface:

   class CustomNamer implements FileNamerInterface {
       public function generateName(UploadedFile $file): string {
           return 'custom_' . uniqid() . '.' . $file->guessExtension();
       }
   }
   

   Register in services.yaml:

   SevenRin0\BigfootMediaBundle\Service\FileNamerInterface: '@app.custom_namer'
   

2. Post-Processing Hook into bigfoot.media.post_upload event to resize images:

   use SevenRin0\BigfootMediaBundle\Event\MediaEvent;
   
   public function onPostUpload(MediaEvent $event) {
       $media = $event->getMedia();
       $this->resizeImage($media->getPath());
   }
   

3. Media Metadata Extend Media entity to store custom fields:

   /**
    * @ORM\Entity
    */
   class Media extends BaseMedia {
       /**
        * @ORM\Column(type="string", nullable=true)
        */
       private $altText;
   }
   

4. Batch Operations Use the MediaManager service for bulk actions:

   $manager = $this->container->get('bigfoot_media.manager');
   $manager->deleteByType('user_avatars'); // Deletes all avatars