Sass Bundle

https://github.com/symfonycasts/sass-bundle
Admin
Sass Bundle is a Symfony bundle that enables seamless Sass support with AssetMapper, automatically...
Tokens:16,058
Snippets:249
Trust Score:8.1
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Get binary name example

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBinary.md

Demonstrates retrieving the filename of the binary archive for the current system.

```php
$binary = new SassBinary('/tmp/sass');
$name = $binary->getBinaryName();
// May return "dart-sass-1.69.7-linux-x64.tar.gz"
```

--------------------------------

### Download executable example

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBinary.md

Demonstrates manually triggering the download of the Sass binary.

```php
$binary = new SassBinary('/var/sass-download');
$binary->downloadExecutable();
```

--------------------------------

### Unknown Platform Exception Example

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

Example of the exception message thrown when the operating system is not recognized.

```text
Exception: Unknown platform or architecture (OS: freebsd, Machine: x86_64).
```

--------------------------------

### Platform/Architecture Not Supported Exception Examples

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

Examples of exception messages thrown when the host platform or architecture is not supported by the binary.

```text
Exception: No matching machine found for Darwin platform (Machine: ppc64).
Exception: No matching machine found for Linux platform (Machine: riscv64).
Exception: No matching machine found for Windows platform (Machine: arm).
```

--------------------------------

### Execute Sass process example

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBinary.md

Demonstrates creating and running a Sass process with specific arguments.

```php
$binary = new SassBinary('/tmp/sass-download');
$process = $binary->createProcess(['input.scss', '--output=output.css']);
$process->run();
```

--------------------------------

### Basic Sass File Example

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Create a Sass file with variables and basic styling. This file will be processed by the bundle.

```scss
/* assets/styles/app.scss */

$red: #fc030b;

body {
  background: $red;
}
```

--------------------------------

### Example RuntimeException

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/PreAssetsCompileEventListener.md

An example of the exception thrown when Sass compilation fails.

```text
RuntimeException: Error compiling sass: "Error: expected '{'.
  on line 5 of app.scss"
```

--------------------------------

### CSS File Not Found Exception

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

Example of the RuntimeException thrown when a pre-compiled CSS file is missing.

```text
RuntimeException: The file /project/var/sass/app-a1b2c3d4e5.output.css 
doesn't exist, run php bin/console sass:build
```

--------------------------------

### Install PHP Zip Extension Commands

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

Commands to install the required PHP zip extension on various operating systems.

```bash
# Ubuntu/Debian
sudo apt-get install php-zip

# macOS
brew install php@8.2-zip  # or appropriate version

# Windows
# Uncomment extension=zip in php.ini
```

--------------------------------

### Command Execution Examples

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuildCommand.md

Standard usage patterns for the sass:build command, including single-run, watch mode, and verbose output.

```bash
# Single build (runs once, outputs CSS, exits)
php bin/console sass:build

# Watch mode (runs continuously until interrupted)
php bin/console sass:build --watch

# Verbose mode (displays detailed build command)
php bin/console sass:build -v
```

--------------------------------

### runBuild(bool $watch)

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuilder.md

Executes the Sass build process. Returns a started Process instance.

```APIDOC
## runBuild(bool $watch)

### Description
Executes the Sass build process. Returns immediately with a Process instance that has been started but not waited on.

### Parameters
- **watch** (bool) - Required - If true, runs in watch mode (infinite process until terminated); if false, runs once and exits

### Returns
- **Symfony\Component\Process\Process** - A started Process instance

### Example
```php
$process = $builder->runBuild(false);
$process->wait();
```
```

--------------------------------

### Get binary name method

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBinary.md

Defines the method signature for retrieving the platform-specific binary filename.

```php
public function getBinaryName(): string
```

--------------------------------

### Verbose Output Example

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuildCommand.md

The output displayed when running the command with the -v flag, showing the underlying Sass command.

```text
Note: Executing Sass (pass -v to see more details).
  Command:
    /path/to/dart-sass/sass input.scss:output.css --style=expanded --source-map
```

--------------------------------

### Invalid Sass Option Exception Example

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

Example of the exception message thrown when an unrecognized option is provided.

```text
InvalidArgumentException: Invalid option "invalid_opt". 
Available options are: "charset", "embed_source_map", "embed_sources", 
"error_css", "load_path", "quiet", "quiet_deps", "source_map", 
"stop_on_error", "style", "trace".
```

--------------------------------

### Get Public Filesystem Path

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassPublicPathAssetPathResolver.md

Retrieves the filesystem path for public assets, ensuring .scss extensions are transformed to .css.

```php
public function getPublicFilesystemPath(): string
```

```php
$resolver = new SassPublicPathAssetPathResolver($innerResolver);

$filesystemPath = $resolver->getPublicFilesystemPath();
// Returns filesystem path like "/var/www/public/assets"
```

--------------------------------

### Duplicate Configuration Path Error

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

Example of a configuration error caused by duplicate entries in the root_sass array.

```yaml
symfonycasts_sass:
    root_sass:
        - assets/styles/app.scss
        - assets/styles/app.scss  # Duplicate!
```

--------------------------------

### Sass Compilation Error Examples

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

Examples of error messages returned by the Sass compiler during asset compilation.

```text
Error: expected '{'.
  on line 5 of app.scss

Error: Undefined variable.
  $color is undefined
  on line 10 of variables.scss

Error: Invalid CSS after "...": expected expression, was "{".
  on line 15 of component.scss
```

--------------------------------

### Configure Sass Build Worker

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Configure the Symfony CLI to automatically start the Sass build worker when the development server starts.

```yaml
# .symfony.local.yaml
workers:
    # ...
    sass:
        cmd: ['symfony', 'console', 'sass:build', '--watch']
```

--------------------------------

### Sass Relative Path Limitation Example

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Demonstrates the limitation with url() paths in Sass files. Paths must be relative to the root .scss file, not the current file.

```scss
/* assets/styles/app.scss */
import 'tools/base';
```

```scss
/* assets/styles/tools/base.scss */
.splash {
    /* This SHOULD work, but doesn't */
    background-image: url('../../images/login-bg.png');

    /* This DOES work: it's relative to app.scss */
    background-image: url('../images/login-bg.png');
}
```

--------------------------------

### Sass Directory Not Found Exception

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

Example of the Exception thrown when a glob pattern references a non-existent base directory.

```text
Exception: Could not find Sass directory: "/project/nonexistent" 
(from "/project/nonexistent/**/*.scss")
```

--------------------------------

### Error Scenario Output

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuildCommand.md

Example of console output when a Sass compilation error occurs.

```bash
$ php bin/console sass:build
Error compiling sass: "Error: expected '{'.
  on line 5 of app.scss
```

--------------------------------

### Import Bootswatch Sass Theme via Composer

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Install a Bootswatch theme using Composer and import it along with Bootstrap's core Sass files. Replace '[theme]' with your desired Bootswatch theme name.

```terminal
composer require thomaspark/bootswatch
```

```scss
@import '../../vendor/thomaspark/bootswatch/dist/[theme]/variables';
@import '../../vendor/twbs/bootstrap/scss/bootstrap';
```

--------------------------------

### Console Error Output

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/PreAssetsCompileEventListener.md

Example of the error message displayed in the console when compilation fails due to a syntax error.

```bash
$ php bin/console asset-map:compile

RuntimeException: Error compiling sass: "Error: Undefined variable.
  $undefined-color is undefined
  on line 15 of component.scss"
```

--------------------------------

### Resolve Sass input paths

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassFileHelper.md

Expands file paths, directories, or glob patterns into a list of absolute file paths. Automatically excludes Sass partials starting with an underscore.

```php
$helper = new SassFileHelper();

// Single file
$files = $helper->resolveSassInput('assets/styles/app.scss');
// Returns: ['/project/assets/styles/app.scss']

// Directory (recursive)
$files = $helper->resolveSassInput('assets/styles');
// Returns: ['/project/assets/styles/app.scss', '/project/assets/styles/theme.scss', ...]

// Glob pattern
$files = $helper->resolveSassInput('assets/**/*.scss', '/project');
// Returns: all matching files, excluding _*.scss files

// Relative to base dir
$files = $helper->resolveSassInput('styles/app.scss', '/project');
// Returns: ['/project/styles/app.scss']
```

--------------------------------

### Import Bootstrap Sass via Composer

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Install Bootstrap Sass using Composer and import it into your main Sass file. Note the use of the deprecated @import directive for Bootstrap versions prior to 6.

```terminal
composer require twbs/bootstrap
```

```scss
/* Override some Bootstrap variables */
$red: #FB4040;

@import '../../vendor/twbs/bootstrap/scss/bootstrap';
```

--------------------------------

### Execute ProcessInterface subprocess

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/types.md

Demonstrates running a build process and handling output or errors.

```php
$process = $builder->runBuild(false);
$process->wait(function ($type, $buffer) {
    echo $buffer;
});

if (!$process->isSuccessful()) {
    echo $process->getErrorOutput();
}
```

--------------------------------

### PHP Configuration Alternative

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/configuration.md

Configures the bundle using a PHP closure instead of YAML.

```php
use Symfony\Config\SymfonycastsSassConfig;

return static function (SymfonycastsSassConfig $config) {
    $config
        ->rootSass(['assets/styles/app.scss'])
        ->searchForBinary(true)
        ->binary(null);
    
    $config->sassOptions()
        ->style('expanded')
        ->sourceMap(true)
        ->embedSourceMap(true)
        ->loadPath(['assets/vendor']);
};
```

--------------------------------

### Download executable method

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBinary.md

Defines the method signature for manual binary download.

```php
public function downloadExecutable(): void
```

--------------------------------

### Environment-Specific YAML Configuration

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/configuration.md

Demonstrates splitting configuration across shared, development, and production files.

```yaml
symfonycasts_sass:
    root_sass:
        - assets/styles/app.scss
```

```yaml
symfonycasts_sass:
    sass_options:
        style: expanded
        source_map: true
        embed_source_map: true
```

```yaml
symfonycasts_sass:
    sass_options:
        style: compressed
        source_map: false
```

--------------------------------

### Execute asset compilation

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassCssCompiler.md

Demonstrates the compilation process and error handling when the CSS file is missing.

```php
$compiler = new SassCssCompiler(
    ['assets/styles'],
    'var/sass',
    '/project',
    $sassBuilder
);

try {
    $css = $compiler->compile(
        $originalContent,
        $asset,
        $assetMapper
    );
    // $css now contains the compiled CSS
} catch (RuntimeException $e) {
    // CSS file not found; ensure sass:build was run first
}
```

--------------------------------

### View Project File Structure

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/INDEX.md

Displays the directory layout of the documentation workspace.

```text
/workspace/home/output/
├── README.md                    # Entry point
├── OVERVIEW.md                  # Architecture & overview
├── INDEX.md                     # This file
├── configuration.md             # Config reference
├── types.md                     # Type definitions
├── errors.md                    # Error catalog
└── api-reference/               # Class documentation
    ├── SassBinary.md
    ├── SassBuilder.md
    ├── SassFileHelper.md
    ├── SassBuildCommand.md
    ├── SassCssCompiler.md
    ├── SassPublicPathAssetPathResolver.md
    ├── PreAssetsCompileEventListener.md
    └── SymfonycastsSassBundle.md
```

--------------------------------

### Complete YAML Configuration

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/configuration.md

Defines all available configuration options for the bundle in a single YAML file.

```yaml
symfonycasts_sass:
    root_sass:
        - assets/styles/app.scss
        - assets/themes/**/*.scss
    binary: null
    search_for_binary: true
    sass_options:
        style: expanded
        charset: true
        source_map: true
        embed_source_map: '%kernel.debug%'
        embed_sources: false
        load_path:
            - assets/vendor
            - node_modules
        quiet: false
        quiet_deps: false
        stop_on_error: false
        trace: false
```

--------------------------------

### SassBuilder::__construct

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuilder.md

Initializes the SassBuilder with input paths, output directory, and compiler configuration.

```APIDOC
## __construct

### Description
Initializes a new instance of the SassBuilder to manage Sass compilation processes.

### Signature
`public function __construct(array $sassPaths, string $cssPath, string $projectRootDir, ?string $binaryPath = null, bool $searchForBinary = true, bool|array $sassOptions = [])`

### Parameters
- **sassPaths** (array<string>) - Required - Array of Sass input file paths or glob patterns.
- **cssPath** (string) - Required - Output directory for compiled CSS files.
- **projectRootDir** (string) - Required - Project root directory used as base for relative paths.
- **binaryPath** (?string) - Optional - Custom path to Sass binary.
- **searchForBinary** (bool) - Optional - Whether to search for Sass binary in system PATH.
- **sassOptions** (bool|array) - Optional - Sass compiler options.
```

--------------------------------

### SassBinary::__construct

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBinary.md

Initializes the SassBinary manager with the specified download directory and optional dependencies.

```APIDOC
## public function __construct(string $binaryDownloadDir, ?string $binaryPath = null, ?SymfonyStyle $output = null, ?HttpClientInterface $httpClient = null): void

### Description
Initializes the SassBinary instance. If a custom binary path is not provided, the bundle will automatically handle downloading the appropriate binary for the current platform.

### Parameters
- **binaryDownloadDir** (string) - Required - Directory where the Sass binary will be downloaded and stored
- **binaryPath** (?string) - Optional - Custom path to an existing Sass binary
- **output** (?SymfonyStyle) - Optional - Console output handler for progress messages
- **httpClient** (?HttpClientInterface) - Optional - Custom HTTP client for downloads
```

--------------------------------

### Verify asset support usage

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassCssCompiler.md

Demonstrates how to check if the compiler supports a specific MappedAsset.

```php
$compiler = new SassCssCompiler(
    ['assets/styles'],
    'var/sass',
    '/project',
    $sassBuilder
);

$asset = new MappedAsset('assets/styles/app.scss');
if ($compiler->supports($asset)) {
    // This compiler will handle app.scss
}
```

--------------------------------

### Generate build options

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuilder.md

Convert configuration settings into a list of CLI arguments for the Sass executable.

```php
$builder = new SassBuilder(
    ['app.scss'],
    'var/sass',
    '/project',
    null,
    true,
    ['style' => 'compressed', 'source_map' => true]
);

$options = $builder->getBuildOptions(['watch' => true]);
// Returns: ['--style=compressed', '--source-map', '--watch']
```

--------------------------------

### Configure console output

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuilder.md

Attach a SymfonyStyle instance to the builder to handle progress and status messaging.

```php
$io = new SymfonyStyle($input, $output);
$builder->setOutput($io);
$builder->runBuild(false)->wait();
```

--------------------------------

### Initialize SassCssCompiler constructor

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassCssCompiler.md

Defines the required parameters for instantiating the compiler service.

```php
public function __construct(
    array $scssPaths,
    string $cssPathDirectory,
    string $projectDir,
    SassBuilder $sassBuilder
)
```

--------------------------------

### getBuildOptions(array $options = [])

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuilder.md

Generates CLI arguments from configured Sass options.

```APIDOC
## getBuildOptions(array $options = [])

### Description
Generates CLI arguments from configured Sass options. Merges default options, instance options, and provided options.

### Parameters
- **options** (array<string, bool|array|string>) - Optional - Additional options to merge

### Returns
- **array<string>** - Command-line arguments for Sass executable
```

--------------------------------

### Service Hierarchy and Dependencies

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/OVERVIEW.md

Visual representation of the bundle's class hierarchy and registered services.

```text
SymfonycastsSassBundle (Bundle)
└── SymfonycastsSassExtension (handles configuration)
    
Services registered:
├── SassBuilder
│   ├── creates → SassBinary
│   ├── uses → SassFileHelper
│   └── executes → Process
│
├── SassBuildCommand (console command)
│   └── uses → SassBuilder
│
├── SassCssCompiler (AssetMapper compiler)
│   └── uses → SassBuilder
│
├── SassPublicPathAssetPathResolver (path decorator)
│   └── decorates → PublicAssetsPathResolverInterface
│
└── PreAssetsCompileEventListener (event listener)
    └── uses → SassBuilder
```

--------------------------------

### Configure the bundle via YAML

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SymfonycastsSassBundle.md

Define Sass settings using YAML configuration files.

```yaml
symfonycasts_sass:
    root_sass:
        - assets/styles/app.scss
```

```yaml
symfonycasts_sass:
    root_sass:
        - assets/styles/app.scss
        - assets/themes/**/*.scss
    binary: null  # null to auto-download, or provide custom path
    search_for_binary: true
    sass_options:
        style: expanded
        charset: true
        source_map: true
        embed_source_map: '%kernel.debug%'
        load_path:
            - assets/vendor
        quiet: false
        quiet_deps: false
```

--------------------------------

### Create Sass process

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBinary.md

Defines the method signature for creating a process instance.

```php
public function createProcess(array $args): Process
```

--------------------------------

### Interact with SymfonyStyle console

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/types.md

Initializes and uses SymfonyStyle for formatted console output.

```php
$io = new SymfonyStyle($input, $output);
$io->note('Building Sass...');
$io->writeln('Done!');
```

--------------------------------

### Configure Root Sass File

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Set the main Sass source file using the root_sass option. Defaults to 'assets/styles/app.scss'.

```yaml
# config/packages/symfonycasts_sass.yaml
symfonycasts_sass:
    root_sass: 'assets/styles/app.scss'
```

--------------------------------

### Dump Sass Bundle Configuration

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Use this command to view the complete configuration for the symfonycasts_sass bundle.

```terminal
php bin/console config:dump symfonycasts_sass
```

--------------------------------

### Register the bundle in Symfony

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SymfonycastsSassBundle.md

Add the bundle to the application configuration to enable it.

```php
return [
    // ...
    Symfonycasts
SassBundle
SymfonycastsSassBundle::class => ['all' => true],
];
```

--------------------------------

### Run Sass Build and Asset Compilation

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Execute the sass:build command before asset-map:compile during deployment to ensure the built Sass file is available.

```terminal
php bin/console sass:build
php bin/console asset-map:compile
```

--------------------------------

### Execute Sass builds

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuilder.md

Run the Sass build process in either single-run or watch mode using the runBuild method.

```php
$builder = new SassBuilder(
    ['assets/styles/app.scss'],
    'var/sass',
    '/project',
    null,
    true
);

// Single build
$process = $builder->runBuild(false);
$process->wait(function ($type, $buffer) {
    echo $buffer;
});

// Watch mode
$watchProcess = $builder->runBuild(true);
$watchProcess->wait(function ($type, $buffer) {
    echo $buffer;
});
```

--------------------------------

### Sass Build Process Data Flow

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/OVERVIEW.md

Step-by-step execution flow for the Sass build process from configuration to CLI execution.

```text
Configuration (config/packages/symfonycasts_sass.yaml)
    ↓
SymfonycastsSassExtension loads services
    ↓
SassBuilder initialized with:
  - root_sass paths
  - css output directory
  - sass_options
    ↓
runBuild(watch: bool) called
    ↓
SassFileHelper::resolveSassInput() expands paths/globs
    ↓
SassBuilder::getScssCssTargets() generates input:output pairs
    ↓
SassBuilder::getBuildOptions() converts options to CLI flags
    ↓
SassBinary::createProcess() creates Process with full command
    ↓
SassBinary::downloadExecutable() (if needed, once per system)
    ↓
Dart Sass CLI executed:
  sass {input}:{output} {options}
    ↓
CSS generated in var/sass/{name}-{hash}.output.css
    ↓
Watch mode: process remains running, waits for changes
Single run: process exits after compilation
```

--------------------------------

### Build and Watch Sass Changes

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Run this command to build your Sass files and watch for changes. The --watch flag enables live compilation.

```terminal
php bin/console sass:build --watch
```

--------------------------------

### Valid Sass Options List

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

A list of valid configuration options for the Sass builder.

```text
charset, embed_source_map, embed_sources, error_css, 
load_path, quiet, quiet_deps, source_map, stop_on_error, 
style, trace
```

--------------------------------

### SassBinary::downloadExecutable

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBinary.md

Manually triggers the download of the Sass binary for the current platform.

```APIDOC
## public function downloadExecutable(): void

### Description
Manually downloads the appropriate Sass binary for the current platform and architecture. This is called automatically by createProcess() if needed.

### Example
```php
$binary = new SassBinary('/var/sass-download');
$binary->downloadExecutable();
```
```

--------------------------------

### Configure the bundle via PHP

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SymfonycastsSassBundle.md

Use the container configurator to set up Sass options in older Symfony versions.

```php
return static function (ContainerConfigurator $container): void {
    $container->extension('symfonycasts_sass', [
        'root_sass' => ['assets/styles/app.scss'],
        'search_for_binary' => true,
        'sass_options' => [
            'style' => 'expanded',
            'source_map' => true,
        ],
    ]);
};
```

--------------------------------

### Configure root_sass paths

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/configuration.md

Define input Sass files, directories, or glob patterns for compilation.

```yaml
symfonycasts_sass:
    root_sass:
        - assets/styles/app.scss
```

```yaml
symfonycasts_sass:
    root_sass:
        - assets/styles/app.scss
        - assets/styles/theme.scss
```

```yaml
symfonycasts_sass:
    root_sass:
        - assets/styles/**/*.scss
```

--------------------------------

### Construct SassBinary instance

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBinary.md

Defines the constructor signature for initializing the binary manager.

```php
public function __construct(
    string $binaryDownloadDir,
    ?string $binaryPath = null,
    ?SymfonyStyle $output = null,
    ?HttpClientInterface $httpClient = null
): void
```

--------------------------------

### Configuring Multiple Input Paths

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/README.md

Use glob patterns to include multiple Sass files or directories in the configuration.

```yaml
symfonycasts_sass:
    root_sass:
        - assets/styles/app.scss
        - assets/themes/**/*.scss
        - vendor/components/*/style.scss
```

--------------------------------

### Build Sass Assets

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/OVERVIEW.md

Executes a one-time build of Sass files using the Symfony console command.

```bash
php bin/console sass:build
```

--------------------------------

### Check asset support

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassCssCompiler.md

Defines the method signature for determining if an asset is handled by the compiler.

```php
public function supports(MappedAsset $asset): bool
```

--------------------------------

### Resolve Public Path

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassPublicPathAssetPathResolver.md

Resolves a logical asset path to a public URL path, converting .scss extensions to .css.

```php
public function resolvePublicPath(string $logicalPath): string
```

```php
$resolver = new SassPublicPathAssetPathResolver($innerResolver);

// Input: "assets/styles/app.scss"
// Inner resolver returns: "/assets/app-abc123.scss"
// Output: "/assets/app-abc123.css"

$publicPath = $resolver->resolvePublicPath('assets/styles/app.scss');
// Returns: "/assets/app-abc123.css" (with hash from inner resolver)
```

--------------------------------

### setOutput(SymfonyStyle $output)

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuilder.md

Sets the console output handler for displaying build progress.

```APIDOC
## setOutput(SymfonyStyle $output)

### Description
Sets the console output handler for displaying build progress and status messages.

### Parameters
- **output** (SymfonyStyle) - Required - Symfony console style output handler
```

--------------------------------

### Configure search_for_binary

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/configuration.md

Control whether the bundle searches the system PATH for the Sass binary.

```yaml
symfonycasts_sass:
    search_for_binary: true   # Search PATH first
```

```yaml
symfonycasts_sass:
    search_for_binary: false  # Always download
```

--------------------------------

### compile(string $content, MappedAsset $asset, AssetMapperInterface $assetMapper)

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassCssCompiler.md

Compiles the Sass file by reading the pre-compiled CSS output file and returning its content.

```APIDOC
## compile(string $content, MappedAsset $asset, AssetMapperInterface $assetMapper)

### Description
Retrieves the compiled CSS content for a given Sass asset. This method expects the CSS output file to have been generated by a prior build step.

### Parameters
- **content** (string) - Required - The original file content.
- **asset** (MappedAsset) - Required - The asset being compiled.
- **assetMapper** (AssetMapperInterface) - Required - The asset mapper context.

### Returns
- **string** - The compiled CSS content.

### Throws
- **RuntimeException** - Thrown if the expected compiled CSS file does not exist.
```

--------------------------------

### SassBuilder Constructor Definition

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuilder.md

Defines the parameters required to initialize the SassBuilder, including input paths, output directory, and compiler options.

```php
public function __construct(
    array $sassPaths,
    string $cssPath,
    string $projectRootDir,
    ?string $binaryPath = null,
    bool $searchForBinary = true,
    bool|array $sassOptions = []
): void
```

--------------------------------

### SassBinary::createProcess

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBinary.md

Creates a Symfony Process instance configured to run the Sass binary with the provided arguments.

```APIDOC
## public function createProcess(array $args): Process

### Description
Creates a Symfony Process instance configured to run the Sass binary with the given arguments. It automatically triggers a download if the binary is missing.

### Parameters
- **args** (array<string>) - Required - Command-line arguments to pass to the Sass executable

### Returns
- **Process** (Symfony\Component\Process\Process) - A configured Process instance ready to execute

### Example
```php
$binary = new SassBinary('/tmp/sass-download');
$process = $binary->createProcess(['input.scss', '--output=output.css']);
$process->run();
```
```

--------------------------------

### getPublicFilesystemPath()

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassPublicPathAssetPathResolver.md

Returns the filesystem path for public assets, transforming .scss extensions to .css if present.

```APIDOC
## getPublicFilesystemPath()

### Description
Returns the filesystem path for public assets. Also transforms .scss extensions to .css.

### Returns
- **string** - Filesystem path to the public assets directory, with .scss replaced by .css if present

### Throws
- **Exception** - If the decorated resolver does not implement getPublicFilesystemPath() method
```

--------------------------------

### Configure Root Sass Files with Glob Patterns

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Use glob patterns within the root_sass option to include multiple Sass files from different directories.

```yaml
symfonycasts_sass:
    root_sass:
        - '%kernel.project_dir%/assets/scss/app.scss'
        - '%kernel.project_dir%/assets/lib/*.scss'
        - '%kernel.project_dir%/assets/admin/**/*.scss'
```

--------------------------------

### Define CLI Options Array

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/types.md

Represents an array of command-line options for the Sass executable.

```php
[
    '--style=compressed',
    '--source-map',
    '--embed-sources',
    '--load-path=assets/vendor',
    '--load-path=node_modules',
    '--watch',
]
```

--------------------------------

### SassBinary::getBinaryName

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBinary.md

Determines the correct binary filename for the current platform and architecture.

```APIDOC
## public function getBinaryName(): string

### Description
Determines the correct binary filename for the current platform and architecture using PHP_OS and php_uname('m').

### Returns
- **string** - The filename of the binary archive (e.g., dart-sass-1.69.7-linux-x64.tar.gz)
```

--------------------------------

### Decorator Pattern Workflow

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassPublicPathAssetPathResolver.md

Conceptual representation of the decorator chain intercepting and transforming asset paths.

```php
// Before: Direct Sass path
$path = 'assets/styles/app.scss'

// During: Decorator chain
// 1. SassPublicPathAssetPathResolver
// 2. Inner resolver (default implementation)

// After: CSS path
$path = '/assets/app-a1b2c3d4e5.css'
```

--------------------------------

### Bundle File Organization

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/OVERVIEW.md

Visual representation of the directory structure within the src/ directory of the bundle.

```text
src/
├── SymfonycastsSassBundle.php           # Main bundle class
├── SassBinary.php                       # Binary download/execution
├── SassBuilder.php                      # Compilation orchestration
├── SassFileHelper.php                   # Path resolution
├── Command/
│   └── SassBuildCommand.php             # CLI command
├── AssetMapper/
│   ├── SassCssCompiler.php              # AssetMapper integration
│   └── SassPublicPathAssetPathResolver.php # Path transformation
├── Listener/
│   └── PreAssetsCompileEventListener.php # Auto-compile hook
└── DependencyInjection/
    └── SymfonycastsSassExtension.php    # Configuration/services
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/PreAssetsCompileEventListener.md

Common commands used during the development workflow involving AssetMapper and Sass.

```bash
# During development
php bin/console asset-map:compile

# Or with AssetMapper in watch mode
php bin/console asset-map:watch

# Manual build if needed (runs the same build)
php bin/console sass:build --watch
```

--------------------------------

### Generate deterministic CSS filenames

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuilder.md

Create a hash-suffixed output filename based on the input SCSS file path.

```php
$cssPath = SassBuilder::guessCssNameFromSassFile(
    '/project/assets/styles/app.scss',
    '/project/var/sass'
);
// Returns: '/project/var/sass/app-a1b2c3d4e5.output.css'
```

--------------------------------

### Specify Sass Binary Path

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Manually set the path to the Sass binary if the bundle cannot detect it automatically. Omitting this option allows the bundle to search or download the binary.

```yaml
symfonycasts_sass:
    binary: 'node_modules/.bin/sass'
```

--------------------------------

### Running Sass Build Commands

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/README.md

Execute Sass compilation via the Symfony console.

```bash
php bin/console sass:build
```

```bash
php bin/console sass:build --watch
```

--------------------------------

### Constructor Definition

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/PreAssetsCompileEventListener.md

The constructor requires an instance of SassBuilder, which is typically injected via the service container.

```php
public function __construct(SassBuilder $sassBuilder)
```

--------------------------------

### Define Build Target Array

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/types.md

Represents an array of input-to-output mappings for the Sass CLI.

```php
[
    '/project/assets/styles/app.scss:/project/var/sass/app-a1b2c3d4e5.output.css',
    '/project/assets/styles/theme.scss:/project/var/sass/theme-f6g7h8i9j0.output.css',
]
```

--------------------------------

### Resolve SCSS targets

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuilder.md

Retrieve an array of source-to-destination file mappings for the Sass CLI.

```php
$builder = new SassBuilder(
    ['assets/styles/app.scss'],
    'var/sass',
    '/project'
);

$targets = $builder->getScssCssTargets();
// Returns: ['/project/assets/styles/app.scss:/project/var/sass/app-a1b2c3d4e5.output.css']
```

--------------------------------

### Programmatic Sass Compilation

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/README.md

Instantiate the SassBuilder and execute a build process manually within PHP code.

```php
$builder = new SassBuilder(
    ['assets/styles/app.scss'],
    'var/sass',
    '/project'
);

$process = $builder->runBuild(false);
$process->wait(function ($type, $buffer) {
    echo $buffer;
});
```

--------------------------------

### Event Lifecycle Flow

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/PreAssetsCompileEventListener.md

Visual representation of the event sequence during asset compilation.

```text
PreAssetsCompileEvent dispatched
    ↓
PreAssetsCompileEventListener invoked
    ↓
SassBuilder::runBuild(false) executed
    ↓
All SCSS files compiled to CSS
    ↓
Asset compilation proceeds
    ↓
SassCssCompiler reads pre-compiled CSS
```

--------------------------------

### Access MappedAsset properties

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/types.md

Shows the structure of a MappedAsset within a compilation method.

```php
public function compile(string $content, MappedAsset $asset, AssetMapperInterface $assetMapper): string
{
    // $asset->sourcePath = '/project/assets/styles/app.scss'
    // $asset->logicalPath = 'assets/styles/app.scss'
}
```

--------------------------------

### Watch Mode Options

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuildCommand.md

The --watch or -w flag enables continuous monitoring of Sass files for changes.

```bash
php bin/console sass:build --watch
php bin/console sass:build -w
```

--------------------------------

### Configure SassOptions array

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/types.md

Maps PHP snake_case option names to Sass compiler values, where null values are skipped.

```php
$sassOptions = [
    'style' => 'compressed',
    'source_map' => true,
    'embed_source_map' => false,
    'load_path' => ['assets/vendor', 'node_modules'],
    'quiet' => null,  // Skipped
];
```

--------------------------------

### supports(MappedAsset $asset)

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassCssCompiler.md

Determines whether the compiler should handle a specific asset based on configured Sass input paths.

```APIDOC
## supports(MappedAsset $asset)

### Description
Checks if the provided asset is a Sass file that should be handled by this compiler. It compares the asset's source path against the configured Sass input paths.

### Parameters
- **asset** (MappedAsset) - Required - The asset being processed by AssetMapper.

### Returns
- **bool** - Returns true if the asset is a configured Sass input file, false otherwise.
```

--------------------------------

### Generate deterministic filename hashes

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassFileHelper.md

Creates a unique filename by appending a 10-character SHA1 hash derived from the normalized file path.

```php
$hashed = SassFileHelper::hashFilename('app');
// Returns: 'app-a1b2c3d4e5'

$hashed = SassFileHelper::hashFilename('/project/assets/app.scss');
// Returns: '/project/assets/app-a1b2c3d4e5.scss' (approximately)
```

--------------------------------

### Configure Multiple Root Sass Files

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

The root_sass option supports an array of paths to specify multiple source Sass files.

```yaml
symfonycasts_sass:
    root_sass:
        - '%kernel.project_dir%/assets/scss/app.scss'
```

--------------------------------

### Register Additional Sass Load Paths

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Provide additional load paths to resolve modules using the load_path option, enabling alternative ways to use libraries like Bootstrap.

```yaml
# config/packages/symfonycasts_sass.yaml
symfonycasts_sass:
    sass_options:
        load_path:
```

--------------------------------

### Debug Sass Build Issues

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/OVERVIEW.md

Uses verbose mode to inspect the underlying Sass command execution for troubleshooting.

```bash
# See full Sass command being executed
php bin/console sass:build -v

# Check for option errors
# See errors.md for details
```

--------------------------------

### Resolve Sass file patterns safely

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

Wrap file resolution in a try-catch block to handle exceptions caused by invalid or nonexistent directory paths.

```php
try {
    $helper = new SassFileHelper();
    $files = $helper->resolveSassInput('nonexistent/**/*.scss');
} catch (Exception $e) {
    // Handle missing directory
    echo "Path error: " . $e->getMessage();
}
```

--------------------------------

### Configure Sass Output Options

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/OVERVIEW.md

Sets specific Sass compiler options such as output style and source map generation.

```yaml
symfonycasts_sass:
    sass_options:
        style: compressed
        source_map: false
```

--------------------------------

### Define PSR-4 Autoloading

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SymfonycastsSassBundle.md

The bundle follows PSR-4 standards for class loading.

```text
Symfonycasts\SassBundle\* => src/
```

--------------------------------

### Root Configuration Node Structure

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/configuration.md

Defines the base configuration keys available for the bundle under the symfonycasts_sass node.

```yaml
symfonycasts_sass:
    root_sass: [...]
    binary: null
    search_for_binary: true
    sass_options: {...}
```

--------------------------------

### Define the SymfonycastsSassBundle class

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SymfonycastsSassBundle.md

The main bundle class that registers the Sass integration by returning the extension.

```php
class SymfonycastsSassBundle extends Bundle
{
    protected function createContainerExtension(): ?ExtensionInterface
    {
        return new SymfonycastsSassExtension();
    }
}
```

--------------------------------

### guessCssNameFromSassFile(string $sassFile, string $outputDirectory)

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuilder.md

Generates a deterministic output CSS filename from an input SCSS filename.

```APIDOC
## guessCssNameFromSassFile(string $sassFile, string $outputDirectory)

### Description
Generates a deterministic output CSS filename from an input SCSS filename using a hash-suffixed name.

### Parameters
- **sassFile** (string) - Required - Path to the SCSS input file
- **outputDirectory** (string) - Required - Output directory where CSS will be written

### Returns
- **string** - Absolute path to the output CSS file
```

--------------------------------

### Configure Custom Sass Binary

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/OVERVIEW.md

Overrides the automatic binary detection by specifying a custom path to the Sass executable.

```yaml
symfonycasts_sass:
    binary: /usr/local/bin/sass
    search_for_binary: false
```

--------------------------------

### Normalize file paths

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassFileHelper.md

Converts all backslashes in a path to forward slashes to ensure consistency across different operating systems.

```php
$normalized = SassFileHelper::normalizePath('C:\\Users\\Project\\file.scss');
// Returns: 'C:/Users/Project/file.scss'
```

--------------------------------

### Configure sass_options

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/configuration.md

Set compiler-specific flags for the Dart Sass CLI.

```yaml
symfonycasts_sass:
    sass_options:
        style: expanded
        source_map: true
        embed_source_map: true
        embed_sources: true
```

```yaml
symfonycasts_sass:
    sass_options:
        style: compressed
        source_map: false
```

```yaml
symfonycasts_sass:
    sass_options:
        quiet: true
        quiet_deps: true
```

```yaml
symfonycasts_sass:
    sass_options:
        load_path:
            - assets/vendor
            - node_modules
```

```yaml
symfonycasts_sass:
    sass_options:
        style: 'expanded'
        embed_source_map: '%kernel.debug%'
```

--------------------------------

### Import Bootstrap in Sass

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Import Bootstrap into your main Sass file after configuring the include paths. Ensure the Bootstrap Sass files are accessible.

```scss
@import 'bootstrap';
```

--------------------------------

### resolvePublicPath(string $logicalPath)

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassPublicPathAssetPathResolver.md

Resolves a logical asset path to a public URL path, transforming .scss extensions to .css.

```APIDOC
## resolvePublicPath(string $logicalPath)

### Description
Resolves a logical asset path to a public URL path. Transforms .scss paths to .css paths by delegating to the inner resolver and then rewriting the extension.

### Parameters
- **logicalPath** (string) - Required - Logical asset path (e.g., assets/styles/app.scss)

### Returns
- **string** - Public asset path with .scss replaced by .css if applicable
```

--------------------------------

### Manual Sass Build Recovery

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

Commands to manually trigger the Sass build or asset compilation process.

```bash
# Run manual Sass build
php bin/console sass:build

# Or retry asset compilation (which should auto-run Sass build)
php bin/console asset-map:compile
```

--------------------------------

### Construct SassPublicPathAssetPathResolver

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassPublicPathAssetPathResolver.md

The constructor requires an instance of PublicAssetsPathResolverInterface to delegate path resolution tasks.

```php
public function __construct(
    PublicAssetsPathResolverInterface $decorator
)
```

--------------------------------

### Handle Sass compilation errors

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

Check the process status after running a build and catch RuntimeException to identify compilation failures.

```php
try {
    $process = $builder->runBuild(false);
    $process->wait();
    
    if (!$process->isSuccessful()) {
        echo "Sass error: " . $process->getErrorOutput();
    }
} catch (RuntimeException $e) {
    // Asset compilation errors from listener
    echo "Build error: " . $e->getMessage();
}
```

--------------------------------

### Validate SassBuilder configuration options

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

Use a try-catch block to handle InvalidArgumentException when passing unsupported options to the SassBuilder constructor.

```php
try {
    $builder = new SassBuilder(
        $paths,
        $cssPath,
        $projectDir,
        null,
        true,
        ['invalid_opt' => true]  // Will throw InvalidArgumentException
    );
} catch (InvalidArgumentException $e) {
    // Handle invalid option
    echo "Config error: " . $e->getMessage();
}
```

--------------------------------

### Migrate deprecated embed_sourcemap

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/configuration.md

Update configuration to use the new sass_options structure.

```yaml
# Old (deprecated)
symfonycasts_sass:
    embed_sourcemap: true

# New
symfonycasts_sass:
    sass_options:
        embed_source_map: true
```

--------------------------------

### Symfony Integration Commands

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuildCommand.md

Commands to interact with the registered console command within a Symfony application.

```bash
php bin/console sass:build      # Interactive
php bin/console help sass:build # View help
```

--------------------------------

### Correcting Sass Option Usage

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/errors.md

Comparison between incorrect and correct usage of Sass builder options.

```php
// Wrong
['stylesheet' => 'compressed']  // ✗ Invalid

// Correct
['style' => 'compressed']  // ✓ Valid
```

--------------------------------

### getScssCssTargets()

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassBuilder.md

Resolves all input SCSS files to input:output target pairs.

```APIDOC
## getScssCssTargets()

### Description
Resolves all input SCSS files to input:output target pairs suitable for passing to the Sass CLI. Expands glob patterns and directories to concrete file paths and generates deterministic output filenames.

### Returns
- **array<string>** - Array of target specifications in format source:destination
```

--------------------------------

### Compile Sass asset

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/SassCssCompiler.md

Defines the method signature for compiling Sass content into CSS.

```php
public function compile(
    string $content,
    MappedAsset $asset,
    AssetMapperInterface $assetMapper
): string
```

--------------------------------

### Configure Sass CLI Options

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Customize Dart Sass CLI options such as output style, load paths, and source map generation.

```yaml
# config/packages/symfonycasts_sass.yaml
symfonycasts_sass:
    sass_options:
        # The output style for the compiled CSS files: expanded or compressed. Defaults to expanded.
        # style: expanded

        # Emit a @charset or BOM for CSS with non-ASCII characters. Defaults to true in Dart Sass.
        # charset: true

        # Register additional load paths. Defaults to empty array.
        # load_path: []

        # Whether to generate source maps. Defaults to true when "kernel.debug" is true.
        # source_map: true

        # Embed source file contents in source maps. Defaults to false.
        # embed_sources:

        # Embed source map contents in CSS. Defaults to false.
        # embed_source_map:

        # Don't print warnings. Defaults to false.
        # quiet:

        # Don't print deprecated warnings for dependencies. Defaults to false.
        # quiet_deps:

        # Don't compile more files once an error is encountered. Defaults to false.
        # stop_on_error:

        # Print full Dart stack traces for exceptions. Defaults to false.
        # trace:
```

--------------------------------

### Invoke Method Definition

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/api-reference/PreAssetsCompileEventListener.md

The __invoke method handles the PreAssetsCompileEvent to trigger the Sass build process.

```php
public function __invoke(PreAssetsCompileEvent $preAssetsCompileEvent): void
```

--------------------------------

### Define Sass File Resolution Result

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/types.md

Represents an array of absolute paths resolved from glob patterns or directories, excluding partials.

```php
[
    '/project/assets/styles/app.scss',
    '/project/assets/styles/theme.scss',
    '/project/assets/vendor/bootstrap.scss',
]
```

--------------------------------

### Injecting Sass Services

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/README.md

Access core bundle services via the service container in controllers or other services.

```php
// In services or controllers
$builder = $container->get('sass.builder');        // SassBuilder
$command = $container->get('sass.command.build');  // SassBuildCommand
$compiler = $container->get('sass.css_asset_compiler');      // SassCssCompiler
```

--------------------------------

### Define SassPaths array

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/types.md

Represents an array of Sass input file paths, directory paths, or glob patterns.

```php
$sassPaths = [
    'assets/styles/app.scss',
    'assets/styles/theme.scss',
    'assets/vendor/*.scss',
];
```

--------------------------------

### Asset Compilation Data Flow

Source: https://github.com/symfonycasts/sass-bundle/blob/main/_autodocs/OVERVIEW.md

Sequence of operations during AssetMapper compilation involving the Sass compiler and path resolver.

```text
AssetMapper compilation requested
    ↓
PreAssetsCompileEvent dispatched
    ↓
PreAssetsCompileEventListener::__invoke()
    ↓
SassBuilder::runBuild(false) → one-time build
    ↓
CSS files compiled to var/sass/
    ↓
AssetMapper iterates over assets
    ↓
For each asset:
  SassCssCompiler::supports(asset) → check if SCSS
    ↓ if yes
  SassCssCompiler::compile() reads pre-compiled CSS
    ↓
SassPublicPathAssetPathResolver::resolvePublicPath()
  .scss → .css transformation
    ↓
Asset mapped with CSS reference
    ↓
Final asset output with correct paths
```

--------------------------------

### Link Sass File in Template

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Link your Sass file directly in your Twig template. The bundle will handle the compilation to CSS.

```html+twig
{# templates/base.html.twig #}

{% block stylesheets %}
    <link rel="stylesheet" href="{{ asset('styles/app.scss') }}">
{% endblock %}
```

--------------------------------

### Exclude Sass Files from AssetMapper

Source: https://github.com/symfonycasts/sass-bundle/blob/main/doc/index.rst

Configure AssetMapper to exclude Sass source files from being copied to the public directory during deployment. Ensure main SCSS files are not excluded.

```yaml
# config/packages/asset_mapper.yaml
framework:
    asset_mapper:
        paths:
            - assets/
        excluded_patterns:
            - '**/assets/styles/**/_*.scss'
```
Tokens:
Raw