Kunstmaan Config Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require dreadlabs/kunstmaan-config-bundle:*
   

2. Register the Bundle Add to AppKernel.php (or bundles.php in Symfony 4+):

   new DreadLabs\KunstmaanConfigBundle\DreadLabsKunstmaanConfigBundle(),
   

3. Configure parameters.yml.dist Add the required parameter:

   liipimagine_webroot: '%kernel.root_dir%/../web'
   

4. Update config.yml Integrate the bundle’s compiler pass for LiipImagineBundle:

   liip_imagine:
       resolvers:
           default:
               web_path:
                   web_root: '%liipimagine_webroot%'
       loaders:
           default:
               filesystem:
                   data_root: '%liipimagine_webroot%'
   

5. First Use Case After installation, the bundle automatically aligns Kunstmaan’s media filesystem adapter with LiipImagineBundle’s expected paths. Test by uploading media via Kunstmaan’s admin panel and verifying image transformations (e.g., thumbnails) render correctly in the web/ directory.

Implementation Patterns

Workflows

1. Media Path Standardization

   • The bundle enforces consistency between Kunstmaan’s media storage and LiipImagineBundle’s webroot by overriding the kunstmaan_media.filesystem_adapter compiler pass.
   • Workflow: Configure liipimagine_webroot in parameters.yml.dist and let the bundle handle the rest. No manual path adjustments are needed in Kunstmaan’s media configuration.

2. Integration with LiipImagine

   • Resolver/Loader Alignment: The bundle configures LiipImagineBundle to use the same root path (web/) for both image resolution and filesystem loading.
   • Example: If Kunstmaan stores media in web/uploads/, LiipImagineBundle will automatically resolve and load images from the same directory without additional mapping.

3. Environment-Specific Paths

   • Override liipimagine_webroot in environment-specific configs (e.g., config_dev.yml):

     liipimagine_webroot: '%kernel.root_dir%/../web/dev'
     

   • Useful for local development where media might be served from a subdirectory.

Tips for Daily Use

• Debugging Paths: Use Symfony’s %kernel.root_dir% and %kernel.project_dir% placeholders to dynamically reference paths across environments.
• Cache Clearing: After changing paths, run:

  php bin/console cache:clear
  

  to ensure compiler passes are re-evaluated.
• Media Uploads: Kunstmaan’s media manager will now use LiipImagineBundle’s configured paths by default. Verify uploads appear in the expected web/ directory.

Gotchas and Tips

Pitfalls

1. Compiler Pass Timing

   • The bundle’s compiler pass runs after LiipImagineBundle is loaded. If you manually configure kunstmaan_media.filesystem_adapter in code (e.g., via a service), the bundle’s override may not apply. Solution: Avoid hardcoding paths; rely on the bundle’s configuration.

2. Path Mismatches

   • If liipimagine_webroot points to a non-existent directory, LiipImagineBundle will fail to resolve images. Solution:
     • Ensure the directory exists (create it manually or via a post-install script).
     • Validate paths in config.yml match the actual filesystem structure.

3. Symfony 4+ Compatibility

   • The bundle assumes AppKernel. For Symfony 4+, ensure the bundle is registered in config/bundles.php and compiler passes are triggered via Kernel events (the bundle may need updates for full compatibility).

4. Media Permissions

   • Kunstmaan’s media uploads require write permissions on the web/ directory. Solution:

     chmod -R 775 %kernel.project_dir%/web
     

Debugging

• Check Compiler Passes: Dump the container’s compiled services to verify the override:

  php bin/console debug:container kunstmaan_media.filesystem_adapter
  

• Log Paths: Add temporary logging in a custom compiler pass to trace path resolutions:

  $this->container->setParameter('debug.liipimagine_webroot', '%liipimagine_webroot%');
  

Extension Points

1. Custom Paths Extend the bundle by overriding the kunstmaan_media.filesystem_adapter parameter in config.yml:

   parameters:
       kunstmaan_media.filesystem_adapter: custom.path.adapter
   

   Then define the service in services.yml.

2. Dynamic Paths Use a service to generate paths dynamically (e.g., based on environment variables):

   liipimagine_webroot: '%env(MEDIA_WEBROOT)%'
   

   Requires Symfony Flex or manual environment variable loading.

3. Additional Bundles The bundle is opinionated for LiipImagineBundle. For other media bundles (e.g., VichUploaderBundle), manually configure path alignment in config.yml.