Compassomator Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require asoc/compassomator-bundle
   

   Ensure Ruby and Compass (gem install compass) are installed globally.

2. Configure Bundles For each bundle, create a Resources/config.rb with:

   css_dir = "public/css"
   sass_dir = "sass"
   

   Place SCSS files in Resources/sass/ and ensure Resources/public/css/ is in .gitignore.

3. Reference CSS in Twig Use Assetic to include generated CSS:

   {% stylesheets '@BundleName/Resources/public/css/foo.css' %}
       <link rel="stylesheet" href="{{ asset_url }}">
   {% endstylesheets %}
   

4. Compile Once Run the compiler:

   php app/console compassomator:compile
   

   Then dump Assetic assets:

   php app/console assetic:dump
   

First Use Case: Cross-Bundle Asset Resolution

Use @BundleName notation in SCSS to reference assets from other bundles:

@import '@AnotherBundle/sass/variables.scss';
background-image: bundle-public('@AnotherBundle/images/hero.jpg');

The bundle-public function resolves paths dynamically.

Implementation Patterns

Workflow Integration

1. Development Workflow

   • Use compassomator:watch for live CSS updates:

     php app/console compassomator:watch
     

   • Run Assetic in watch mode separately if manage_assetic: false:

     php app/console assetic:dump --watch
     

2. CI/CD Pipeline

   • Compile in CI:

     php app/console compassomator:compile && php app/console assetic:dump --no-debug
     

   • Cache compiled CSS in app/cache/compassomator for performance.

3. Bundle Isolation

   • Each bundle’s config.rb defines its own sass_dir and css_dir, ensuring modularity.
   • Avoid global SCSS conflicts by scoping variables with @BundleName prefixes.

4. Assetic Integration

   • Configure Assetic to output to web/bundles/ (default) or override in config.yml:

     assetic:
         assets:
             YourBundle_css:
                 inputs:
                     - '@YourBundle/Resources/public/css/foo.css'
                 filters: [cssrewrite]
     

Advanced Patterns

1. Dynamic Imports Use bundle-public for dynamic asset paths in SCSS:

   .icon {
     background-image: bundle-public('@IconBundle/images/#{ $icon-name }.png');
   }
   

2. Environment-Specific Configs Override config.rb per environment (e.g., Resources/config_dev.rb) and reference it in compassomator:compile:

   php app/console compassomator:compile --env=dev --config=config_dev.rb
   

3. Custom Compass Importers Extend the bundle’s importer logic by subclassing CompassomatorImporter (see src/ASoC/CompassomatorBundle/Importer/CompassomatorImporter.php).

Gotchas and Tips

Pitfalls

1. Cache Conflicts

   • cache:clear triggers compassomator:compile, which may cause delays. Disable auto-compile in config.yml:

     asoc_compassomator:
         auto_compile_on_cache_clear: false
     

2. Path Resolution Failures

   • Ensure @BundleName notation matches the exact bundle namespace (case-sensitive).
   • Verify bundle-public paths use forward slashes (/), even on Windows.

3. Assetic Mismatches

   • If CSS files disappear after assetic:dump, check:
     • Assetic’s output path in config.yml matches the bundle’s css_dir.
     • No typos in Twig stylesheets paths.

4. Ruby/Gem Dependencies

   • Compass may fail if Ruby’s PATH isn’t set. Use bundle exec or set COMPASS_BIN in config.rb:

     COMPASS_BIN = '/usr/local/bin/compass'
     

Debugging Tips

1. Logs and Cache

   • Check logs for errors:

     php app/console compassomator:logs
     

   • Inspect raw Compass output in app/cache/compassomator/compass.log.

2. Dry Runs Test path resolution with:

   php app/console compassomator:compile --dry-run
   

3. Compass Config Validation Validate config.rb syntax:

   compass validate Resources/config.rb
   

Extension Points

1. Custom Importers Override the importer to support additional notations (e.g., @ThemeName):

   // src/ASoC/CompassomatorBundle/Importer/CustomImporter.php
   class CustomImporter extends CompassomatorImporter {
       public function resolve($path) {
           // Add custom logic here
           return parent::resolve($path);
       }
   }
   

   Register it in services.yml:

   asoc_compassomator.importer:
       class: ASoC\CompassomatorBundle\Importer\CustomImporter
   

2. Post-Compile Hooks Extend the compiler to run additional tasks (e.g., CSS linting):

   // src/ASoC/CompassomatorBundle/DependencyInjection/Compiler/PostCompilePass.php
   class PostCompilePass implements CompilerPassInterface {
       public function process(ContainerBuilder $container) {
           $definition = $container->findDefinition('asoc_compassomator.compiler');
           $definition->addMethodCall('addPostCompileCallback', [[$this, 'lintCss']]);
       }
   }
   

3. Environment Variables Use environment variables in config.rb for dynamic paths:

   css_dir = ENV['CSS_DIR'] || "public/css"
   

Pro Tips

• Atomic CSS Workflow: Use compassomator:watch with --no-assetic for rapid iteration, then manually run assetic:dump once stable.
• Bundle Autoloading: Ensure bundles are autoloaded in composer.json:

  "autoload": {
      "psr-4": {
          "ASoC\\CompassomatorBundle\\": "vendor/asoc/compassomator-bundle/src"
      }
  }
  

• Docker Integration: Mount app/cache/compassomator as a volume to persist compiled CSS across container restarts.