Gallery Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require daemon/gallery-bundle
   

   Enable it in config/bundles.php:

   Daemon\GalleryBundle\DaemonGalleryBundle::class => ['all' => true],
   

2. Basic Configuration Publish the default config:

   php bin/console daemon:gallery:install
   

   Update config/packages/daemon_gallery.yaml (if needed) to match your asset paths (e.g., unitegallery_path).

3. First Use Case: Display a Gallery In a Twig template, render a gallery with:

   {{ daemon_gallery({
       'images': [
           { 'src': '/uploads/gallery/image1.jpg', 'thumb': '/uploads/gallery/thumbs/image1_thumb.jpg' },
           { 'src': '/uploads/gallery/image2.jpg', 'thumb': '/uploads/gallery/thumbs/image2_thumb.jpg' }
       ],
       'theme': 'modern',
       'effect': 'fade'
   }) }}
   

   • Ensure unitegallery.js and unitegallery-themes.css are loaded in your base template (check assets/ after installation).

Implementation Patterns

Common Workflows

1. Dynamic Gallery Generation Fetch images from a database (e.g., Doctrine entities) and pass them to the bundle:

   // Controller
   public function showGallery(Repository $imageRepo): Response
   {
       $images = $imageRepo->findAll();
       $galleryData = array_map(function ($image) {
           return [
               'src' => $image->getFullPath(),
               'thumb' => $image->getThumbPath(),
           ];
       }, $images);
   
       return $this->render('gallery/index.html.twig', [
           'gallery' => $galleryData,
       ]);
   }
   

2. Reusing Gallery Configs Define reusable configurations in config/packages/daemon_gallery.yaml:

   daemon_gallery:
       presets:
           blog_gallery:
               theme: 'light'
               effect: 'slide'
               transition: 'cubic'
   

   Use in Twig:

   {{ daemon_gallery(galleryData|merge({'preset': 'blog_gallery'})) }}
   

3. Asset Management

   • Custom Themes/Effects: Place custom unitegallery-themes.css or effects/ in public/assets/daemon_gallery/ and reference them in the config:

     daemon_gallery:
         theme_path: '%kernel.project_dir%/public/assets/daemon_gallery/themes/'
     

   • Lazy Loading: Use the lazy option to defer initialization:

     {{ daemon_gallery(galleryData|merge({'lazy': true})) }}
     

4. Integration with Forms For image uploads, pair with VichUploaderBundle:

   // Entity
   use Vich\UploaderBundle\Mapping\Annotation as Vich;
   #[Vich\Uploadable]
   class GalleryImage { ... }
   

   Then pass the uploaded paths to the gallery bundle as shown above.

Gotchas and Tips

Pitfalls

1. Asset Paths

   • Issue: Gallery fails to load if unitegallery_path in config points to a non-existent directory.
   • Fix: Verify the path in config/packages/daemon_gallery.yaml matches your public/ structure. Default is public/assets/daemon_gallery/.
   • Debug: Check the browser console for 404 errors on unitegallery.js or theme CSS files.

2. Twig Template Not Found

   • Issue: If you extend the bundle’s base template (e.g., DaemonGalleryBundle::base.html.twig), ensure the file exists in the bundle’s Resources/views/ or override it in your project.
   • Fix: Copy the template to templates/bundles/daemon_gallery/base.html.twig and modify as needed.

3. Image Paths Must Be Absolute

   • Issue: Relative paths (e.g., images/image.jpg) may break the gallery.
   • Fix: Use absolute paths from the root (e.g., /uploads/images/image.jpg) or prepend {{ asset() }} in Twig:

     {{ daemon_gallery({
         'images': [
             { 'src': asset('uploads/image1.jpg'), 'thumb': asset('uploads/thumbs/image1_thumb.jpg') }
         ]
     }) }}
     

4. Javascript Conflicts

   • Issue: UniteGallery may conflict with other JS libraries (e.g., jQuery plugins).
   • Fix: Wrap initialization in a $(document).ready() block or use the initCallback option:

     {{ daemon_gallery(galleryData|merge({
         'initCallback': 'function() { console.log("Gallery initialized"); }'
     })) }}
     

Tips

1. Debugging

   • Enable debug mode (APP_DEBUG=true) to see detailed errors.
   • Use the browser’s Network tab to verify JS/CSS files are loaded.

2. Customization

   • Override the bundle’s Twig templates by creating a templates/bundles/daemon_gallery/ directory.
   • Extend the DaemonGallery Twig extension to add custom filters or functions.

3. Performance

   • Lazy Loading: Use lazy: true to improve initial page load times.
   • Preload Critical Assets: Manually preload unitegallery.js and theme CSS in your base template:

     <link rel="preload" href="{{ asset('assets/daemon_gallery/unitegallery-themes.css') }}" as="style">
     <script src="{{ asset('assets/daemon_gallery/unitegallery.js') }}" defer></script>
     

4. Configuration

   • Default Options: The bundle uses sensible defaults (e.g., theme: 'modern', effect: 'fade'). Override only what’s necessary.
   • Environment-Specific Configs: Use %kernel.environment% to switch configs (e.g., dev vs. prod):

     daemon_gallery:
         debug: '%kernel.debug%'
     

5. Testing

   • Mock the DaemonGallery Twig extension in PHPUnit:

     $twig = new \Twig\Environment($loader);
     $twig->addExtension(new \Daemon\GalleryBundle\Twig\DaemonGalleryExtension());
     

   • Test gallery rendering with static data to avoid dependency on real assets.