Less Elephant Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require cypresslab/less-elephant-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       CypressLab\LessElephantBundle\CypressLabLessElephantBundle::class => ['all' => true],
   ];
   

2. Configure for Dev Environment Add to config/packages/dev/cypress_less_elephant.yaml (or config_dev.yml in older Symfony):

   cypress_less_elephant:
       less_projects:
           app:
               source_folder: "%kernel.project_dir%/assets/less"
               source_file: "styles.less"
               destination_css: "%kernel.project_dir%/public/css/styles.css"
   

3. First Use Case

   • Place your .less files in assets/less/.
   • Reference the compiled CSS in your Twig templates:

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

   • Access the page in dev mode—the bundle auto-compiles on request.

Implementation Patterns

Workflow Integration

1. Project Structure Organize LESS files hierarchically (e.g., assets/less/components/, assets/less/pages/). Use @import for modularity:

   @import "variables";
   @import "mixins";
   @import "components/button";
   

2. Symfony Asset Pipeline

   • Dev Mode: Auto-compiles on every request (no cache).
   • Prod Mode: Disable auto-compilation (use force_compile: false) and pre-compile assets via CI/CD:

     # config/packages/prod/cypress_less_elephant.yaml
     cypress_less_elephant:
         force_compile: false
     

3. Dynamic Imports For dynamic LESS paths (e.g., user-uploaded themes), use a custom compiler:

   cypress_less_elephant:
       less_projects:
           dynamic_theme:
               source_folder: "%kernel.project_dir%/var/themes/%theme_id%/less"
               source_file: "theme.less"
               destination_css: "%kernel.project_dir%/public/themes/%theme_id%.css"
   

   Override the compiler service in config/services.yaml:

   services:
       App\Service\DynamicLessCompiler:
           tags: ['cypress_less_elephant.compiler']
   

4. Twig Integration Extend Twig to auto-generate asset paths:

   {% set less_project = 'app' %}
   <link rel="stylesheet" href="{{ path('cypress_less_elephant_output', { project: less_project }) }}">
   

   Add a route in config/routes.yaml:

   cypress_less_elephant_output:
       path: /css/{project}.css
       defaults: { _controller: 'CypressLabLessElephantBundle:Default:output' }
   

Gotchas and Tips

Pitfalls

1. Binary Path Issues

   • Error: Command 'lessc' not found.
   • Fix: Explicitly set less_binary_path in config (e.g., /usr/bin/lessc or C:\Program Files\nodejs\lessc.exe on Windows).
   • Debug: Run which lessc (Linux/Mac) or where lessc (Windows) to locate the binary.

2. Permission Denied

   • Error: Failed to write to destination CSS.
   • Fix: Ensure the web server user (e.g., www-data) has write permissions to the public/ directory:

     chmod -R 775 %kernel.project_dir%/public
     

3. Circular Dependencies

   • Error: Infinite compilation loops with @import cycles.
   • Fix: Refactor LESS files to avoid circular imports or use ~"less" to break cycles:

     @import ~"less/components/button"; // Note the ~
     

4. Prod Mode Surprises

   • Gotcha: force_compile: true in prod will recompile on every request, hurting performance.
   • Fix: Use force_compile: false in prod and pre-compile assets in your deployment script:

     # Example deployment step
     cd %kernel.project_dir%
     php bin/console cypress:less:compile --env=prod
     

Debugging Tips

1. Enable Verbose Logging Add to config/packages/dev/monolog.yaml:

   handlers:
       cypress_less_elephant:
           type: stream
           path: "%kernel.logs_dir%/less_elephant.log"
           level: debug
   

2. Check Compilation Status Use the console command to validate projects:

   php bin/console cypress:less:status
   

3. Clear Cache on Config Changes After modifying cypress_less_elephant config, clear the cache:

   php bin/console cache:clear
   

Extension Points

1. Custom Compilers Implement CypressLab\LessElephantBundle\Compiler\CompilerInterface for custom logic (e.g., minification):

   namespace App\Compiler;
   
   use CypressLab\LessElephantBundle\Compiler\CompilerInterface;
   
   class MinifierCompiler implements CompilerInterface {
       public function compile(string $source, string $destination): bool {
           // Add minification logic (e.g., using YUI Compressor)
           return file_put_contents($destination, $minifiedCss);
       }
   }
   

   Register in config/services.yaml:

   services:
       App\Compiler\MinifierCompiler:
           tags: ['cypress_less_elephant.compiler']
   

2. Event Listeners Hook into compilation events (e.g., log changes or trigger notifications):

   namespace App\EventListener;
   
   use CypressLab\LessElephantBundle\Event\LessCompilationEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class LessCompilationLogger implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               LessCompilationEvent::NAME => 'onLessCompilation',
           ];
       }
   
       public function onLessCompilation(LessCompilationEvent $event) {
           if ($event->isCompiled()) {
               \Log::info('LESS compiled: ' . $event->getProject());
           }
       }
   }
   

3. Environment-Specific Configs Use Symfony’s environment variables to switch configs:

   # config/packages/dev/cypress_less_elephant.yaml
   cypress_less_elephant:
       less_projects: *dev_projects
   
   # config/packages/prod/cypress_less_elephant.yaml
   cypress_less_elephant:
       less_projects: *prod_projects
       force_compile: false
   

   Define imports in config/packages/imports.yaml:

   imports:
       - { resource: 'dev/cypress_less_elephant.yaml', ignore_errors: true }
       - { resource: 'prod/cypress_less_elephant.yaml', ignore_errors: true }