Scssphp Compass Laravel Package

Getting Started

Minimal Setup

1. Installation Add to composer.json:

   "require": {
       "leafo/scssphp": "^dev-master",
       "leafo/scssphp-compass": "^dev-master"
   }
   

   Run composer update.

2. First Compilation

   require 'vendor/autoload.php';
   
   $scss = new \scssc();
   $compass = new \scss_compass($scss);
   
   $result = $scss->compile('@import "compass"; @include border-radius(5px);');
   file_put_contents('output.css', $result);
   

3. Key Files to Review

   • vendor/leafo/scssphp-compass/src/scss_compass.php (core class)
   • vendor/leafo/scssphp-compass/compass/ (pre-extracted Compass SCSS)

Implementation Patterns

Workflow Integration

1. Preprocessing Pipeline

   // Typical Laravel asset compilation (e.g., in a service provider)
   public function boot()
   {
       $scss = new \scssc();
       $compass = new \scss_compass($scss);
   
       // Override default import paths if needed
       $scss->setImportPaths([base_path('resources/assets/scss'), __DIR__.'/compass']);
   
       // Compile all SCSS files
       $files = glob(base_path('resources/assets/scss/*.scss'));
       foreach ($files as $file) {
           $output = $scss->compile(file_get_contents($file));
           file_put_contents(public_path("css/{$file}.css"), $output);
       }
   }
   

2. Dynamic Compilation (e.g., Blade Directives)

   // In a Blade directive (e.g., `compileScss`)
   Blade::directive('scss', function ($expression) {
       $scss = new \scssc();
       $compass = new \scss_compass($scss);
       return "<?php echo \$scss->compile(?) ?? ''; ?>";
   });
   
   // Usage in Blade:
   @scss('@import "compass"; @include breakpoint($small) { ... }')
   

3. Configuration Management Store Compass-specific settings in config/scss.php:

   return [
       'compass' => [
           'enabled' => env('SCSS_COMPASS_ENABLED', true),
           'custom_functions' => [
               'my-custom-mixin' => 'path/to/mixin.scss',
           ],
       ],
   ];
   

Gotchas and Tips

Common Pitfalls

1. Version Mismatches

   • The package bundles a static snapshot of Compass SCSS. If you update leafo/scssphp-compass, run:

     php vendor/bin/scssphp-compass-extract
     

   • Tip: Pin the package version in composer.json to avoid surprises:

     "leafo/scssphp-compass": "1.0.0"
     

2. Import Path Conflicts

   • Compass relies on specific import paths (e.g., compass/utilities/). If your project has overlapping paths:

     $scss->setImportPaths([
         __DIR__.'/compass', // scssphp-compass path
         base_path('resources/assets/scss'), // Custom paths
     ]);
     

   • Debug Tip: Use $scss->getImportPaths() to inspect the resolved paths.

3. Performance Overhead

   • Compass adds ~300+ built-in mixins/functions, increasing compilation time.
   • Optimization: Cache compiled CSS aggressively (e.g., Laravel Mix or filemtime checks).

4. Missing Features

   • No built-in Sprockets support (unlike Ruby Compass). Use scssc->addImportPath() for custom assets.
   • Workaround: Pre-process assets with Laravel Mix before passing to scssphp.

Debugging Tips

1. Enable Verbose Output

   $scss->setErrorFormat(\scssc::ERROR_FORMAT_DETAILED);
   $scss->setPrecision(10); // For debugging precision issues
   

2. Check for Deprecated Compass Features

   • Some Compass 1.x features (e.g., @extend) may behave differently in scssphp. Test thoroughly.

3. Fallback for Critical Errors

   try {
       $result = $scss->compile($source);
   } catch (\scss_compass_error $e) {
       // Fallback to vanilla SCSS
       $scss->removeImportPath(__DIR__.'/compass');
       $result = $scss->compile($source);
   }
   

Extension Points

1. Custom Compass Functions Add your own mixins/functions by extending scss_compass:

   class CustomCompass extends \scss_compass {
       public function __construct(\scssc $scss) {
           parent::__construct($scss);
           $this->addFunction('my-mixin', function($args) {
               return $this->scss->compile("@include my-logic($args);");
           });
       }
   }
   

2. Override Compass SCSS Replace the bundled Compass files by:

   $scss->setImportPaths([__DIR__.'/custom-compass-path']);
   

   • Warning: Ensure compatibility with scssphp's parser.

3. Integrate with Laravel Eloquent Store compiled CSS in the database:

   // In a model observer
   $model->observing(function($model) {
       if ($model->isDirty('scss_code')) {
           $scss = new \scssc();
           $compass = new \scss_compass($scss);
           $model->css_output = $scss->compile($model->scss_code);
           $model->save();
       }
   });