Less Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add to composer.json:

   "require": {
       "da/less-bundle": "dev-master"
   }
   

   Run:

   composer update
   

2. Register Bundle In AppKernel.php (dev environment recommended):

   $bundles[] = new Da\LessBundle\DaLessBundle();
   

3. Configure Routes Add to routing_dev.yml:

   DaLessBundle:
       resource: "@DaLessBundle/Controller/"
       type: annotation
       prefix: /
   

4. Set Permissions In config.yml:

   da_less:
       roles: [ROLE_ADMIN]  # Restrict to admins
   

5. Update Assets

   php app/console assets:install --symlink
   

First Use Case

• Navigate to /less (or configured route) to access the compilation interface.
• Upload a .less file via the form or configure a .less.yml file for automated compilation.

Implementation Patterns

Workflow: Manual Compilation via Form

1. Access Interface Visit /less (or configured route) with ROLE_ADMIN (or allowed role).

2. Upload & Compile

   • Drag-and-drop or browse to upload a .less file.
   • Submit the form to trigger compilation.
   • Bundle outputs compiled CSS to a predefined directory (default: web/css/).

3. Integration with Twig Reference the compiled CSS in your templates:

   <link rel="stylesheet" href="{{ asset('css/compiled.css') }}">
   

Workflow: Automated Compilation via Config

1. Create Config File Define a .less.yml file in your project root (e.g., config/less.yml):

   files:
       - { input: 'src/Resources/assets/less/style.less', output: 'web/css/style.css' }
   

2. Trigger Compilation Use the console command:

   php app/console less:compile
   

   Or integrate into a build script (e.g., post-install-cmd in composer.json):

   "scripts": {
       "post-install-cmd": [
           "php app/console less:compile"
       ]
   }
   

3. Cache Management Clear cache after changes:

   php app/console cache:clear
   

Integration Tips

• Symfony Assetic: Use DaLessBundle alongside Assetic for hybrid workflows (e.g., compile LESS in dev, use Assetic filters in prod).
• Webpack Encore: For modern setups, use DaLessBundle for legacy LESS files while migrating new assets to Webpack.
• Event Listeners: Extend functionality by listening to less.compile events (see Extension Points).

Gotchas and Tips

Pitfalls

1. Permission Denied

   • Issue: 403 errors when accessing /less despite correct roles config.
   • Fix: Verify:
     • User has the specified role (e.g., ROLE_ADMIN).
     • ROLE_ADMIN is properly assigned in your security setup (e.g., security.yml).
     • No firewall blocks the route.

2. Output Directory Missing

   • Issue: Compiled CSS files appear in unexpected locations.
   • Fix: Override the default output path in config.yml:

     da_less:
         output_dir: "%kernel.root_dir%/../web/build/css"
     

3. Console Command Fails

   • Issue: less:compile throws errors about missing dependencies.
   • Fix: Ensure lessphp/lessphp is installed (bundle depends on it):

     composer require lessphp/lessphp
     

4. Symlink Issues (Windows)

   • Issue: assets:install fails on Windows.
   • Fix: Use the non-symlink command:

     php app/console assets:install
     

Debugging

• Enable Debug Mode Set da_less.debug: true in config.yml to log compilation errors to var/log/dev.log.

• Check Compilation Logs Inspect var/log/less.log for detailed output (ensure logging is configured in app/config/config.yml):

  monolog:
      handlers:
          main:
              type:   stream
              path:   "%kernel.logs_dir%/less.log"
              level:  debug
  

Configuration Quirks

1. Role Bypass in Production

   • Warning: Setting roles: [anonymous] in production is a security risk. Use environment-specific configs:

     # config_dev.yml
     da_less:
         roles: [anonymous]
     
     # config_prod.yml
     da_less:
         roles: [ROLE_ADMIN]
     

2. File Watching

   • The bundle does not support auto-reload. Use a tool like nodemon or integrate with Symfony’s debug:cache-clear in dev.

Extension Points

1. Custom Compilation Logic Override the compiler service by defining your own in services.yml:

   services:
       da_less.compiler:
           class: AppBundle\Service\CustomLessCompiler
           arguments: ["@da_less.compiler"]
           tags:
               - { name: da_less.compiler }
   

2. Event Listeners Listen to compilation events (e.g., less.compile.start, less.compile.end) in services.yml:

   services:
       app.less_listener:
           class: AppBundle\EventListener\LessCompileListener
           tags:
               - { name: kernel.event_listener, event: less.compile.start, method: onCompileStart }
   

3. Pre/Post-Processors Extend the compiler pipeline by implementing Da\LessBundle\Compiler\LessProcessorInterface and registering it:

   services:
       app.less_processor:
           class: AppBundle\Compiler\CustomLessProcessor
           tags:
               - { name: da_less.less_processor }