README

По-русски

Features

• Sass and SCSS compilation to CSS
• @use, @forward, @import, built-in Sass modules, and modern color functions
• Optional source maps and rule splitting
• PSR-3 logging for @debug, @warn, and @error
• PSR-16 support for caching compiled files

Installation via Composer

composer require bugo/scss-php

Usage examples

Compiling from a string

<?php

require __DIR__ . '/vendor/autoload.php';

use Bugo\SCSS\Compiler;
use Bugo\SCSS\Syntax;

$compiler = new Compiler();

// SCSS
$scss = <<<'SCSS'
@use 'sass:color';

$color: red;
body {
  color: $color;
}
footer {
  background: color.adjust(#6b717f, $red: 15);
}
SCSS;

$css = $compiler->compileString($scss);

var_dump($css);

// Sass
$sass = <<<'SASS'
@use 'sass:color';

$color: red;
body
  color: $color;
footer
  background: color.adjust(#6b717f, $red: 15);
SASS;

$css = $compiler->compileString($sass, Syntax::SASS);

var_dump($css);

Compiling from a file

<?php

require __DIR__ . '/vendor/autoload.php';

use Bugo\SCSS\Compiler;
use Bugo\SCSS\CompilerOptions;
use Bugo\SCSS\Loader;
use Bugo\SCSS\Style;

$compiler = new Compiler(
    options: new CompilerOptions(style: Style::COMPRESSED, sourceMapFile: 'assets/app.css.map'),
    loader: new Loader(['styles/']),
);

$css = $compiler->compileFile(__DIR__ . '/assets/app.scss');

file_put_contents(__DIR__ . '/assets/app.css', $css);

echo "CSS compiled!\n";

If sourceMapFile is set, the compiler writes the source map itself and appends a sourceMappingURL comment to the returned CSS.

Caching compiled files with PSR-16

CachingCompiler caches only compileFile(). It tracks every loaded dependency and invalidates the cache if any imported or used file changes.

<?php

require __DIR__ . '/vendor/autoload.php';

use Bugo\SCSS\Cache\CachingCompiler;
use Bugo\SCSS\Cache\TrackingLoader;
use Bugo\SCSS\Compiler;
use Bugo\SCSS\CompilerOptions;
use Bugo\SCSS\Loader;
use Bugo\SCSS\Style;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;

$options = new CompilerOptions(
    style: Style::COMPRESSED,
    sourceMapFile: __DIR__ . '/assets/app.css.map',
);

$trackingLoader = new TrackingLoader(new Loader([__DIR__ . '/styles']));
$compiler = new Compiler($options, $trackingLoader);
$cache = new Psr16Cache(new FilesystemAdapter(namespace: 'scss', directory: __DIR__ . '/var/cache/scss'));

$cachedCompiler = new CachingCompiler(
    $compiler,
    $cache,
    $trackingLoader,
    $options,
);

$css = $cachedCompiler->compileFile(__DIR__ . '/assets/app.scss');

file_put_contents(__DIR__ . '/assets/app.css', $css);

Notes:

• Pass the same TrackingLoader instance to both Compiler and CachingCompiler.
• compileString() is delegated directly and is not cached.
• psr/simple-cache is included by this package, but you still need a PSR-16 cache implementation such as symfony/cache, Laravel cache, or another compatible backend.

CompilerOptions reference

Logging @debug, @warn, @error with any PSR-3 logger

<?php

require __DIR__ . '/vendor/autoload.php';

use Bugo\SCSS\Compiler;
use Monolog\Formatter\LineFormatter;
use Monolog\Handler\StreamHandler;
use Monolog\Logger;

$formatter = new LineFormatter("[%datetime%] %level_name%: %message%\n");

$handler = new StreamHandler('php://stdout');
$handler->setFormatter($formatter);

$logger = new Logger('sass');
$logger->pushHandler($handler);

// Inject logger in constructor
$compiler = new Compiler(logger: $logger);

$scss = <<<'SCSS'
@debug "Build started";
@warn "Using deprecated token";
// @error "Fatal style issue";

.button {
  color: red;
}
SCSS;

$css = $compiler->compileString($scss);
echo $css;

Notes:

• @debug -> $logger->debug(...)
• @warn -> $logger->warning(...)
• @error -> $logger->error(...) and compilation throws Bugo\SCSS\Exceptions\SassErrorException

Comparison with other packages

See the benchmark.md file for results.

benchmark.php includes both the regular bugo/scss-php compiler and a separate bugo/scss-php+cache scenario so you can compare repeated compileFile() runs with warm cache hits.

Found a bug?

Paste the problematic code into the sandbox, then send:

• the sandbox link
• the actual result from this package
• the expected result

Want to add something?

Don't forget to test and tidy up your code before submitting a pull request.

Additional resources

• https://sass-lang.com/documentation/
• https://github.com/sass/sass
• https://tc39.es/ecma426/
• https://evanw.github.io/source-map-visualization/