Simple Gallery Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require c33s/simple-gallery-bundle
   

   Add to AppKernel.php:

   new C33s\SimpleGalleryBundle\C33sSimpleGalleryBundle(),
   

2. Enable AdminGenerator Ensure admingenerator is installed and configured. The bundle relies on it for CRUD operations.

3. First Use Case: Create a Gallery

   • Define a gallery in fixtures.yml (as shown in the README).
   • Run Propel fixtures:

     php app/console propel:data-load
     

   • Access the gallery admin panel (e.g., /admin/gallery) to manage items.

4. Display in Twig Use the single_gallery('slug') helper in templates:

   {% for item in single_gallery('background').galleryItems %}
       <img src="{{ item.image|att_url('liip_imagine_filter_name') }}">
   {% endfor %}
   

Implementation Patterns

Workflow: Image Management

1. Directory-Based Uploads

   • Configure ImagesLoadFromDirectory in fixtures to point to a local directory (e.g., app/propel/attachments/Gallery/background).
   • Upload images manually to this directory; the bundle reads them on demand.

2. Dynamic Sliders (e.g., Vegas)

   • Use Twig to generate JavaScript arrays for sliders:

     backgrounds: [{% spaceless %}{% for item in single_gallery('hero').galleryItems %}
         { src: '{{ item.image|att_url('slider') }}', fade: 1000 }{% if not loop.last %},{% endif %}{% endfor %}{% endspaceless %}]
     

3. Integration with LiipImagine

   • Pipe gallery images through att_url with Imagine filters:

     {{ item.image|att_url('thumbnail') }}
     

   • Ensure liip/imagine-bundle is installed and filters are configured.

4. Admin CRUD

   • Use AdminGenerator to manage Gallery and GalleryItem entities.
   • Customize admin templates (e.g., app/Resources/views/admin/C33sSimpleGalleryBundle/Gallery) for additional fields.

Best Practices

• Slug Consistency: Use lowercase, hyphenated slugs (e.g., hero-images) for Twig templates.
• Caching: Cache single_gallery() calls in controllers if galleries are static:

  $gallery = $this->get('simple_gallery.manager')->getGalleryBySlug('hero');
  

• Batch Processing: For large galleries, lazy-load images via JavaScript (e.g., Infinite Scroll).

Gotchas and Tips

Pitfalls

1. Propel Dependency

   • The bundle requires Propel ORM (not Doctrine). Ensure your project uses Propel.
   • If migrating from Doctrine, expect schema/behavior differences (e.g., no Doctrine events).

2. Directory Permissions

   • Ensure the ImagesLoadFromDirectory path is writable by the web server:

     chmod -R 755 app/propel/attachments/
     

3. AdminGenerator Conflicts

   • If AdminGenerator is misconfigured, the admin panel may fail to load. Verify:

     # app/config/config.yml
     admingenerator:
         model_manager_name: propel
     

4. Image Paths in Production

   • Hardcoded paths (e.g., app/propel/attachments) may break in shared hosting. Use kernel.root_dir or parameter('attachments_path'):

     # fixtures.yml
     ImagesLoadFromDirectory: "%attachments_path%/Gallery/background"
     

Debugging Tips

• Missing Galleries? Check if fixtures loaded:

  php app/console propel:data-dump --fixtures
  

  Re-run propel:data-load if needed.

• Broken Images? Verify:

  • The ImageFilePath in fixtures points to an existing file.
  • LiipImagine filters are correctly configured (check app/config/config.yml under liip_imagine).

• Twig Errors Ensure the gallery slug matches exactly (case-sensitive):

  {# Correct: #}
  {{ single_gallery('background').galleryItems }}
  
  {# Incorrect (extra space): #}
  {{ single_gallery('background ').galleryItems }}  {# Fails #}
  

Extension Points

1. Custom Fields Extend the GalleryItem model to add metadata (e.g., alt_text, caption):

   # fixtures.yml
   C33s\SimpleGalleryBundle\Model\GalleryItem:
       item1:
           gallery: [@background]
           image:    app/propel/attachments/Gallery/background/image1.jpg
           alt_text: "Description of image1"
   

   Update Twig templates to use the new field:

   <img src="{{ item.image|att_url('thumbnail') }}" alt="{{ item.altText }}">
   

2. Override Admin Templates Copy default templates from:

   vendor/c33s/simple-gallery-bundle/Resources/views/admin/
   

   to:

   app/Resources/views/admin/C33sSimpleGalleryBundle/
   

   Customize forms/layouts (e.g., add file upload fields).

3. Event Listeners Attach Propel listeners to GalleryItem for pre/post-save logic (e.g., auto-generate thumbnails):

   // src/C33s/SimpleGalleryBundle/EventListener/GalleryListener.php
   class GalleryListener
   {
       public function postSave(PostSaveEvent $event)
       {
           $item = $event->getObject();
           if ($item instanceof GalleryItem) {
               // Logic here
           }
       }
   }
   

   Register in services.yml:

   services:
       simple_gallery.listener:
           class: C33s\SimpleGalleryBundle\EventListener\GalleryListener
           tags:
               - { name: propel.post_save_listener, model: GalleryItem }
   

4. Dynamic Slugs Override the getSlug() method in the Gallery model to generate slugs dynamically (e.g., from title):

   public function getSlug()
   {
       return strtolower(preg_replace('/[^a-z0-9]+/', '-', $this->getTitle()));
   }