Compass Elephant Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require cypresslab/compass-elephant
   

   Ensure compass is installed system-wide (which compass should return a path).

2. Basic Usage:

   use CompassElephant\CompassProject;
   
   $project = new CompassProject('/path/to/compass');
   if (!$project->isInitialized()) {
       $project->init(); // Runs `compass create`
   }
   if (!$project->isClean()) {
       $project->compile(); // Runs `compass compile`
   }
   

3. First Use Case: Integrate into a Laravel task (e.g., app/Console/Commands/CompileCompass.php) to automate Sass compilation during deployment or local development.

Implementation Patterns

Core Workflows

1. Project Initialization:

   $project = new CompassProject('/path/to/project', 'my-project', null, 'finder');
   $project->init(); // Auto-creates `config.rb` if `$autoInit = true` (default).
   

2. Conditional Compilation:

   if (!$project->isClean()) {
       $project->compile();
   }
   

   • isClean() uses Symfony’s Finder (default) to check file timestamps or falls back to compass compile --dry-run (deprecated in v0.3.1+).

3. Custom Configurations:

   $project = new CompassProject(
       '/path/to/project',
       'my-project',
       new CompassBinary('/custom/path/to/compass'), // Override binary path
       'finder',
       'config_prod.rb' // Custom config file
   );
   

Laravel Integration Tips

• Artisan Command:

  namespace App\Console\Commands;
  use CompassElephant\CompassProject;
  
  class CompileCompass extends Command
  {
      protected $signature = 'compass:compile';
      protected $description = 'Compile Sass assets using Compass';
  
      public function handle()
      {
          $project = new CompassProject(resource_path('sass'));
          $project->compile();
          $this->info('Compass compilation complete.');
      }
  }
  

  Register in app/Console/Kernel.php:

  protected $commands = [
      Commands\CompileCompass::class,
  ];
  

• Service Provider: Bind the project to Laravel’s container for dependency injection:

  public function register()
  {
      $this->app->singleton('compass', function () {
          return new CompassProject(resource_path('sass'));
      });
  }
  

• Event Listeners: Trigger compilation after file changes (e.g., using laravel-echo or filesystem events):

  use Illuminate\Filesystem\Events\FileChanged;
  
  public function handle(FileChanged $event)
  {
      if (str_contains($event->path, 'resources/sass')) {
          app('compass')->compile();
      }
  }
  

• Environment-Specific Configs: Use Laravel’s config system to switch between config.rb files:

  $configFile = config('compass.config_file');
  $project = new CompassProject(resource_path('sass'), null, null, 'finder', $configFile);
  

Gotchas and Tips

Pitfalls

1. Deprecated Dry-Run Method:

   • The native staleness checker (using --dry-run) was removed in v0.3.1 due to Compass 1.x changes. Always use 'finder' for reliability.

2. File Permissions:

   • Ensure the web server user (e.g., www-data) has read/write access to the project directory. Use:

     chmod -R 755 /path/to/compass
     chown -R www-data:www-data /path/to/compass
     

3. Compass Binary Path:

   • If which compass fails, explicitly set the binary path:

     $project = new CompassProject('/path/to/project', null, new CompassBinary('/usr/local/bin/compass'));
     

4. Auto-Initialization:

   • $autoInit = true (default) will run compass create on empty directories. Disable with $autoInit = false if you manage config.rb manually.

5. Symfony Finder Limitations:

   • The finder method may miss changes in dynamically generated Sass files. For complex projects, consider running compass compile unconditionally during deployments.

6. Outdated Package:

   • Last release was 2014. Test thoroughly in your environment, especially if using newer Compass versions (e.g., 1.0+).

Debugging

• Check Compass Output: Wrap compile() in a try-catch to log errors:

  try {
      $project->compile();
  } catch (\Exception $e) {
      Log::error('Compass compile failed: ' . $e->getMessage());
  }
  

• Verify Config.rb: Ensure config.rb is valid Ruby. Use compass validate config.rb to test manually.

• Logs: Enable verbose output by setting the COMPASS_VERBOSE environment variable:

  putenv('COMPASS_VERBOSE=true');
  $project->compile();
  

Extension Points

1. Custom Staleness Checker: Implement CompassElephant\StalenessCheckerInterface for advanced logic:

   class CustomStalenessChecker implements StalenessCheckerInterface
   {
       public function isClean(CompassProject $project)
       {
           // Custom logic (e.g., check Git status)
           return true;
       }
   }
   

   Pass it to the constructor:

   $project = new CompassProject('/path', null, null, new CustomStalenessChecker());
   

2. Pre/Post Compilation Hooks: Extend CompassElephant\CompassProject to add callbacks:

   class ExtendedCompassProject extends CompassProject
   {
       public function compile()
       {
           $this->beforeCompile();
           parent::compile();
           $this->afterCompile();
       }
   
       protected function beforeCompile() { /* ... */ }
       protected function afterCompile() { /* ... */ }
   }
   

3. Laravel Mix Integration: Use the package to pre-compile Sass before Laravel Mix processes CSS:

   // webpack.mix.js
   mix.postCss('resources/css/app.css', 'public/css', [
       require('postcss-import'),
       require('tailwindcss'),
   ]);
   

   Run compass:compile in a custom webpack hook or via Artisan.

Configuration Quirks

• Environment Variables: CompassElephant respects these variables:

  • COMPASS (binary path)
  • COMPASS_CONFIG (config file name)
  • COMPASS_ENV (e.g., production for environment-specific configs).

• Laravel Config: Store Compass settings in config/compass.php:

  return [
      'path' => resource_path('sass'),
      'config_file' => env('COMPASS_CONFIG', 'config.rb'),
      'auto_init' => env('COMPASS_AUTO_INIT', true),
  ];
  

  Access via config('compass.path').