Scssphp Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require armin/scssphp-bundle
   

   Symfony Flex will auto-configure the bundle.

2. Define a basic SCSS asset in config/packages/scssphp.yaml:

   scssphp:
       enabled: true
       assets:
           "css/app.css":
               src: "assets/scss/app.scss"
   

3. Reference the compiled CSS in Twig:

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

4. Verify in dev mode:

   • Refresh the page; the bundle auto-compiles SCSS on demand.
   • Check the Profiler Toolbar under "SCSSPHP" for compilation status.

Implementation Patterns

Workflow: Local Development

1. Edit SCSS files (assets/scss/*.scss) and save.

2. Auto-reload: The bundle recompiles changed files on request (no Node.js needed).

3. Debug: Use the Profiler Toolbar to inspect:

   • Compilation errors (with line numbers).
   • Build timings and source map details.
   • Variable overrides (e.g., Bootstrap theme colors).

4. Configuration Overrides:

   • Variables: Override SCSS variables per environment (e.g., primary: '#0066cc').

     scssphp:
         assets:
             "css/app.css":
                 variables:
                     $primary: "#0066cc"
     

   • Import Paths: Add paths for libraries (e.g., Bootstrap):

     importPaths:
         - "vendor/twbs/bootstrap/scss"
     

5. Output Styles:

   • Use outputStyle: expanded for debugging, compressed for production.
   • Enable sourceMap: true for browser debugging (requires appendTimestamp: true).

6. CLI Compilation:

   • Manually compile all assets:

     php bin/console scssphp:compile
     

   • Force non-interactive mode (e.g., CI/CD):

     php bin/console scssphp:compile all -n
     

Gotchas and Tips

Pitfalls

1. Caching Issues:

   • In production, disable autoUpdate and use the CLI command to avoid runtime compilation:

     scssphp:
         enabled: true
         autoUpdate: false  # Disable auto-reload in prod
     

   • Clear the cache after manual CLI compilation:

     php bin/console cache:clear
     

2. Source Map Paths:

   • If using sourceMap: true, ensure the generated .map files are accessible via asset():

     <link href="{{ asset('css/app.css') }}" rel="stylesheet">
     <!-- Source map (if enabled) -->
     <script src="{{ asset('css/app.css.map') }}"></script>
     

3. Variable Scope:

   • Variables in scssphp.yaml override defaults but do not merge with SCSS file variables.
   • Use !default in SCSS files to preserve fallback values:

     $primary: #ff0000 !default;
     

4. Symlink Conflicts:

   • If using outputFolder: public, ensure the target directory exists (e.g., mkdir -p public/css).

Debugging Tips

1. Profiler Panel:

   • Click the SCSSPHP toolbar entry to see:
     • Errors: Line numbers and context.
     • Build Logs: Timings and file changes.
   • Hover over the entry to see the last compiled timestamp.

2. CLI Verbosity:

   • Add -v for detailed output:

     php bin/console scssphp:compile -v
     

3. Environment-Specific Configs:

   • Use %kernel.environment% to toggle features:

     scssphp:
         enabled: "%env(bool:SCSSPHP_ENABLED)%"
     

Extension Points

1. Custom Formatters:

   • Extend ScssPhp\ScssPhp\Formatter\FormatterInterface and inject via dependency injection.

2. Pre/Post-Compile Hooks:

   • Subscribe to the scssphp.compile event in a service:

     use Symfony\Component\EventDispatcher\GenericEvent;
     
     public function onScssCompile(GenericEvent $event) {
         $asset = $event->getArgument('asset');
         // Modify $asset['variables'] or $asset['src'] here
     }
     

   • Register the listener in services.yaml:

     services:
         App\EventListener\ScssListener:
             tags:
                 - { name: kernel.event_listener, event: scssphp.compile, method: onScssCompile }
     

3. Asset Discovery:

   • Dynamically load assets from a database or API by implementing a custom AssetLoader.