Less Elephant Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cypresslab/less-elephant:^1.0.0
   

   Ensure lessc (LESS compiler binary) is installed on your *nix system.

2. First Use Case: Compile a single .less file to .css:

   use Cypresslab\LessElephant\LessProject;
   
   $project = new LessProject(
       __DIR__ . '/path/to/less/files',
       'styles.less',
       __DIR__ . '/path/to/output/styles.css'
   );
   
   if (!$project->isClean()) {
       $project->compile();
   }
   

3. Key Files:

   • vendor/cypresslab/less-elephant/src/ – Core classes.
   • vendor/cypresslab/less-elephant/tests/ – Usage examples in tests.

Implementation Patterns

Workflows

1. Project Initialization:

   • Pass root LESS directory, input .less file, and output .css path.
   • Optionally override project name or LessBinary path:

     $project = new LessProject(
         '/less/src',
         'main.less',
         '/css/output.css',
         'my-project',
         new LessBinary('/custom/lessc')
     );
     

2. Compile on Demand:

   if (!$project->isClean()) { // Checks file timestamps via Symfony Finder
       $project->compile();     // Uses Symfony Process to run `lessc`
   }
   

3. Batch Processing:

   • Loop through multiple LESS files:

     $projects = [
         new LessProject('/src', 'file1.less', '/output/file1.css'),
         new LessProject('/src', 'file2.less', '/output/file2.css'),
     ];
     
     foreach ($projects as $project) {
         if (!$project->isClean()) $project->compile();
     }
     

4. Symfony Integration:

   • Use LessElephantBundle for dependency injection:

     # config.yml
     less_elephant:
         projects:
             default:
                 src: '%kernel.project_dir%/assets/less'
                 input: 'main.less'
                 output: '%kernel.project_dir%/web/css/main.css'
     

   • Trigger compilation in a controller or event listener:

     $this->get('less_elephant.project_manager')->compile('default');
     

Integration Tips

• Asset Pipeline: Hook into Laravel’s assets:compile or view.compiled events.
• Watch Mode: Combine with inotifywait (Linux) or nodemon (cross-platform) for live reloading.
• Cache Busting: Append file hashes to output paths:

  $outputPath = $project->getOutputPath() . '?v=' . filemtime($project->getInputPath());
  

Gotchas and Tips

Pitfalls

1. Binary Path Assumptions:

   • Defaults to lessc in $PATH. Explicitly set path if missing:

     $project = new LessProject(..., ..., ..., ..., new LessBinary('/usr/local/bin/lessc'));
     

2. File Permissions:

   • Ensure PHP user (e.g., www-data) has write access to output directories:

     chmod -R 775 /path/to/output
     chown -R www-data:www-data /path/to/output
     

3. Symfony Finder Quirks:

   • isClean() may return false if LESS files are symlinked (timestamp mismatches).
   • Exclude files from staleness checks:

     $project->setFinder(function (Finder $finder) {
         $finder->exclude('vendor');
     });
     

4. LESS Compiler Errors:

   • compile() throws RuntimeException on failure. Catch and log:

     try {
         $project->compile();
     } catch (\RuntimeException $e) {
         Log::error($e->getMessage());
     }
     

Debugging

• Verbose Output: Enable Symfony Process logging:

  $project->setVerbose(true); // Shows `lessc` command output
  

• Dry Runs: Test without writing files:

  $project->compile(true); // Dry run (no file writes)
  

Extension Points

1. Custom Compilation Logic: Override LessProject::compile() to add pre/post-processing:

   class CustomLessProject extends LessProject {
       protected function compile($dryRun = false) {
           // Pre-compile steps (e.g., minification)
           parent::compile($dryRun);
           // Post-compile steps (e.g., CSS optimization)
       }
   }
   

2. Plugin System: Extend LessBinary to support custom LESS plugins:

   class PluginLessBinary extends LessBinary {
       public function __construct($binaryPath) {
           parent::__construct($binaryPath);
           $this->addPlugin('--plugin=path/to/plugin.less');
       }
   }
   

3. Event Dispatching: Use Laravel’s events to trigger actions on compile:

   event(new LessCompiled($project->getOutputPath()));
   

Performance

• Disable Staleness Checks: For static sites, bypass isClean() and force recompilation:

  $project->setClean(false); // Force recompile
  

• Parallel Compilation: Use parallel package to compile multiple projects concurrently:

  \Parallel::run(function () use ($projects) {
      foreach ($projects as $project) {
          if (!$project->isClean()) $project->compile();
      }
  });