Image Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies:

   composer require avro/image-bundle liip/imagine-bundle doctrine/mongodb-odm-bundle
   

   Ensure DoctrineMongoDBBundle and LiipImagineBundle are enabled in AppKernel.php.

2. Enable Bundle:

   // app/AppKernel.php
   $bundles[] = new Avro\ImageBundle\AvroImageBundle();
   

3. Add Routing:

   # app/config/routing.yml
   avro_image:
       resource: "@AvroImageBundle/Resources/config/routing/routing.xml"
   

4. First Use Case: Create a document implementing ImageObjectInterface (e.g., Product):

   use Avro\ImageBundle\Model\ImageObjectInterface;
   
   class Product implements ImageObjectInterface {
       // ...
       public function getDocumentName() { return 'product'; }
   }
   

5. Upload an Image: Use the provided controller or create a custom form handler to upload files to GridFS via the Image document.

Implementation Patterns

Workflow: Image Management

1. Uploading:

   • Use the Image document to store file metadata (e.g., filename, mimetype, path).
   • Example:

     $image = new \Avro\ImageBundle\Document\Image();
     $image->setFile($uploadedFile);
     $dm->persist($image);
     $dm->flush();
     

2. Associating Images with Documents:

   • Reference Image documents in your model (e.g., Product):

     $product->addImage($image);
     $dm->persist($product);
     $dm->flush();
     

3. Rendering:

   • Carousel: Use Twig templates for predefined styles (e.g., Twitter Bootstrap):

     {{ carousel_render('twitter', product.images) }}
     

   • Lightbox/Gallery: Extend with custom templates (see Configuration Reference).

4. Resizing with LiipImagine:

   • Configure filters in config.yml:

     liip_imagine:
         filters:
             thumbnail:
                 size: [100, 100]
                 mode: outbound
     

   • Generate URLs:

     {{ image_filter(image, 'thumbnail') }}
     

5. Batch Processing:

   • Use Doctrine events (e.g., prePersist) to auto-generate thumbnails or metadata.

Integration Tips

• Forms: Use Symfony’s FileType field with custom validation to ensure only images are uploaded.

  $builder->add('images', 'file', [
      'multiple' => true,
      'mime_types' => ['image/jpeg', 'image/png'],
  ]);
  

• GridFS Optimization:

  • Monitor GridFS storage with php app/console doctrine:mongodb:gridfs:info.
  • Consider chunk size tuning for large files.

• Caching: Cache rendered carousels/galleries in Twig or Varnish to reduce DB load.

Gotchas and Tips

Pitfalls

1. MongoDB GridFS Limitations:

   • Large files (>16MB) may require manual chunk size configuration in mongodb.yml.
   • GridFS does not support transactions; handle failures gracefully.

2. ImageObjectInterface:

   • Forgetting to implement getDocumentName() will break routing and template rendering.
   • Ensure images property is an ArrayCollection to avoid serialization issues.

3. LiipImagine Dependencies:

   • Filters must be configured before using image_filter in templates.
   • Clear cache (app/console cache:clear) after adding new filters.

4. Routing Conflicts:

   • The bundle’s routes (e.g., /image/upload) may clash with existing routes. Override in routing.yml if needed.

5. Assetic Assets:

   • If CSS/JS fails to load, verify assets:install and assetic:dump are run post-install.
   • Use --watch in development to auto-recompile assets.

Debugging

1. Upload Failures:

   • Check GridFS storage with:

     php app/console doctrine:mongodb:gridfs:list
     

   • Validate file MIME types server-side (client-side checks are bypassable).

2. Template Errors:

   • Ensure Twig templates extend the bundle’s base templates (e.g., AvroImageBundle::carousel.html.twig).
   • Debug with {{ dump(carousel) }} to inspect passed variables.

3. Performance:

   • Profile GridFS queries with MongoDB’s explain() to optimize slow loads.
   • Use LiipImagineBundle's cache to avoid regenerating thumbnails.

Extension Points

1. Custom Carousels:

   • Override templates in AcmeBundle:Carousel:my_carousel.html.twig and reference them in config:

     avro_image:
         carousels:
             my_carousel:
                 template: AcmeBundle:Carousel:my_carousel.html.twig
     

2. Image Validation:

   • Extend the Image document to add custom validation (e.g., max file size):

     use Symfony\Component\Validator\Constraints as Assert;
     
     /**
      * @Assert\File(maxSize="2M")
      */
     protected $file;
     

3. Event Listeners:

   • Hook into prePersist to auto-generate metadata (e.g., width, height):

     $dm->getEventManager()->addEventListener(
         \Doctrine\ODM\MongoDB\Events::prePersist,
         function ($event) {
             $image = $event->getDocument();
             if ($image instanceof \Avro\ImageBundle\Document\Image) {
                 $image->setDimensions(getimagesize($image->getPath()));
             }
         }
     );
     

4. Alternative Storage:

   • Replace GridFS with S3/Flysystem by extending the Image document’s storage logic (requires custom File handling).