Compass Elephant Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require cypresslab/compass-elephant-bundle
   

2. Enable the Bundle Add to config/bundles.php:

   return [
       // ...
       MatteoSister\CompassElephantBundle\MatteoSisterCompassElephantBundle::class => ['all' => true],
   ];
   

3. Configure in config/packages/matteo_sister_compass_elephant.yaml

   matteo_sister_compass_elephant:
       projects:
           - '%kernel.project_dir%/path/to/compass/project'
       output_dir: '%kernel.project_dir%/web/css'
   

4. First Use Case: Auto-Compile on Request Place your .scss files in the configured Compass project directory. The bundle will automatically compile them to CSS on every request (or cache the compiled output if configured).

Where to Look First

• Bundle Configuration: config/packages/matteo_sister_compass_elephant.yaml
• Project Structure: Ensure your Compass project (.scss files, config.rb) is correctly referenced in projects.
• Output Directory: Verify output_dir points to a writable directory (e.g., web/css).
• Symfony Cache: Clear cache after setup:

  php bin/console cache:clear
  

First Compilation Test

1. Add a test .scss file (e.g., styles.scss) with:

   @import "partials/header";
   body { background: #fff; }
   

2. Access any route in your Symfony app. The bundle will compile the SCSS to CSS in output_dir.
3. Verify the generated CSS file in the browser’s dev tools or via:

   ls -la %kernel.project_dir%/web/css
   

Implementation Patterns

Workflow: Integrating Compass into Symfony

1. Project Organization

   • Place Compass projects in a dedicated directory (e.g., src/Compass/).
   • Example structure:

     /src/Compass/
       /project1/
         config.rb
         styles.scss
         partials/
       /project2/
         ...
     

   • Configure in config/packages/matteo_sister_compass_elephant.yaml:

     matteo_sister_compass_elephant:
         projects:
             - '%kernel.project_dir%/src/Compass/project1'
             - '%kernel.project_dir%/src/Compass/project2'
         output_dir: '%kernel.project_dir%/web/build/css'
     

2. Asset Management

   • Use Symfony’s asset() helper to reference compiled CSS:

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

   • For dynamic asset paths, use the MatteoSisterCompassElephantBundle service to fetch the output path:

     $compass = $container->get('matteo_sister_compass_elephant');
     $cssPath = $compass->getOutputPath('project1', 'styles.css');
     

3. Development vs. Production

   • Development: Enable auto-compilation on every request (default).
   • Production: Disable auto-compilation and pre-compile assets:

     # config/packages/matteo_sister_compass_elephant.yaml
     matteo_sister_compass_elephant:
         auto_recompile: false  # Disable auto-compilation
     

     Pre-compile manually:

     php bin/console matteo-sister:compass:compile
     

4. Sprite Generation

   • Configure config.rb in your Compass project:

     # config.rb
     sprite_dir = 'images/sprites'
     sprite_image_path = '../web/images/sprites.png'
     sprite_image_width = 2048
     sprite_image_height = 2048
     

   • Reference sprites in SCSS:

     @import "sprites";
     .icon { background: sprite-url('icon-name'); }
     

5. Integration with Webpack Encore

   • Use the bundle alongside Encore for JavaScript:
     • Compile SCSS via CompassElephant.
     • Process JS via Webpack.
     • Merge outputs in web/build/.

Advanced Patterns

1. Custom Compass Configurations

   • Override config.rb per project by naming it config.local.rb and placing it in the project root. The bundle will use this file if it exists.

2. Event-Driven Compilation

   • Listen to the compass.elephant.compile event to trigger custom logic:

     // src/EventListener/CompassCompileListener.php
     namespace App\EventListener;
     
     use MatteoSister\CompassElephantBundle\Event\CompileEvent;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     
     class CompassCompileListener implements EventSubscriberInterface
     {
         public static function getSubscribedEvents()
         {
             return [
                 'compass.elephant.compile' => 'onCompile',
             ];
         }
     
         public function onCompile(CompileEvent $event)
         {
             // Log or notify when a project compiles
             \Log::info(sprintf('Compiling %s', $event->getProject()));
         }
     }
     

3. Caching Strategies

   • Leverage Symfony’s cache system to avoid recompiling unchanged files:

     matteo_sister_compass_elephant:
         cache_dir: '%kernel.cache_dir%/compass'
     

   • Clear cache when dependencies change:

     php bin/console cache:clear --env=prod
     

4. Multi-Environment Configs

   • Use environment variables or separate config files for dev/prod:

     # config/packages/dev/matteo_sister_compass_elephant.yaml
     matteo_sister_compass_elephant:
         auto_recompile: true
         log_level: debug
     

Gotchas and Tips

Pitfalls

1. Outdated Compass Version

   • The bundle was designed for Compass 0.x/1.x. Modern Compass (2.x+) may require adjustments or a forked version.
   • Fix: Pin Compass to a compatible version in composer.json:

     "compass": "^1.0"
     

2. Permission Issues

   • Compass needs write access to output_dir. Ensure the web server user (e.g., www-data) has permissions:

     chmod -R 775 %kernel.project_dir%/web/css
     chown -R www-data:www-data %kernel.project_dir%/web/css
     

3. Auto-Compilation Overhead

   • Auto-compiling on every request can slow down development. Use auto_recompile: false in production and pre-compile assets.

4. Missing Dependencies

   • Compass requires Ruby and Node.js. Ensure they are installed and in PATH:

     ruby -v  # Should show Ruby 2.x
     node -v  # Should show Node.js 10.x+
     

   • Fix: Install dependencies via:

     sudo apt-get install ruby nodejs  # Debian/Ubuntu
     

5. Stale Cache Issues

   • If changes aren’t reflected, clear the Compass cache:

     rm -rf %kernel.cache_dir%/compass
     php bin/console cache:clear
     

6. Symfony 4+ Compatibility

   • The bundle was written for Symfony 2. Modern Symfony versions may require autoload adjustments.
   • Fix: Add this to composer.json:

     "autoload": {
         "psr-4": {
             "MatteoSister\\CompassElephantBundle\\": "vendor/cypresslab/compass-elephant-bundle"
         }
     }
     

Debugging Tips

1. Enable Verbose Logging Configure in config/packages/matteo_sister_compass_elephant.yaml:

   matteo_sister_compass_elephant:
       log_level: debug
   

   Check logs in var/log/dev.log.

2. Check Compass Output Run Compass manually to debug:

   compass compile --no-line-comments --force
   

3. Validate Config.rb Ensure config.rb is valid Ruby. Test it with:

   ruby -c config.rb
   

4. Symfony Debug Toolbar Use the Profiler to inspect Compass events and compilation status.

Extension Points

1. Custom Compilation Commands Extend the bundle’s compiler by implementing MatteoSister\CompassElephantBundle\Compiler\CompilerInterface and register it as a service.

2. Pre/Post-Compile Hooks Use the compass.elephant.pre_compile and compass.elephant.post_compile events to add logic before/after compilation.

3. Custom Asset Helpers Create