bugo/sass-embedded-php

A lightweight PHP bridge for the official Node.js Sass embedded package

0.8 2026-03-22 05:25 UTC

Requires

• php: ^8.2
• composer-plugin-api: ^2.0
• symfony/process: ^7.4|^8.0

Requires (Dev)

• bugo/scss-benchmark-utils: dev-main
• composer/composer: *
• friendsofphp/php-cs-fixer: ^3.94
• mikey179/vfsstream: ^1.6
• mockery/mockery: dev-bugfix/spy-generics
• pestphp/pest: ^3.8|^4.4
• rector/rector: ^2.3

MIT

• Bugo

• scss php
• sass php
• scss compiler
• sass compiler

README

По-русски

PHP wrapper for sass-embedded (Dart Sass via Node.js).

Allows compiling SCSS/SASS to CSS through PHP using Node.js and npm.

Requirements

• PHP >= 8.2
• Node.js >= 18

Installation via Composer

composer require bugo/sass-embedded-php

Usage examples

Compiling SCSS file

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

use Bugo\Sass\Compiler;

$compiler = new Compiler();

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

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

echo "CSS compiled!\n";

Compiling SCSS from string

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

use Bugo\Sass\Compiler;

$compiler = new Compiler();

$scss = '$color: red; body { color: $color; }';
$css = $compiler->compileString($scss);

echo $css;

Compiling string with options

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

use Bugo\Sass\Compiler;
use Bugo\Sass\Options;

$compiler = new Compiler();

$scss = <<<'SCSS'
$color: #3498db;
$font-size: 14px;

body {
  font-size: $font-size;
  color: $color;
}
SCSS;

$compiler->setOptions(new Options(
    style: 'compressed',
    sourceMapPath: 'inline',
));

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

echo $css;

Catching compilation errors

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

use Bugo\Sass\Exception;
use Bugo\Sass\Compiler;

$compiler = new Compiler();

$scss = <<<'SCSS'
$color: #e74c3c;
.foo { color: $color; }
SCSS;

try {
    echo $compiler->compileString($scss);
} catch (Exception $e) {
    echo "Compilation error: " . $e->getMessage();
}

Compiling SCSS file with change checking

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

use Bugo\Sass\Exception;
use Bugo\Sass\Compiler;

$compiler = new Compiler();

try {
    $done = $compiler->compileFileAndSave(
        __DIR__ . '/assets/style.scss',
        __DIR__ . '/assets/style.css',
    );

    if ($done) {
        echo "CSS recompiled and saved.\n";
    } else {
        echo "No changes detected, skipped compilation.\n";
    }
} catch (Exception $e) {
    echo "Compilation error: " . $e->getMessage();
}

This method automatically checks if the source file has been modified since the last compilation and only compiles and saves if changes are detected.

Compiling file with source maps and compressed output

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

use Bugo\Sass\Compiler;
use Bugo\Sass\Options;

$compiler = new Compiler();

$compiler->setOptions(new Options(
    style: 'compressed',
    includeSources: true,
    sourceMapPath: __DIR__ . '/assets/',
));

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

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

echo "CSS compiled with source map!\n";

Compiling string with inline source map

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

use Bugo\Sass\Compiler;
use Bugo\Sass\Options;

$compiler = new Compiler();

$compiler->setOptions(new Options(
    sourceMapPath: 'inline',
    includeSources: true,
));

$css = $compiler->compileString('$color: red; body { color: $color; }');

echo $css;

Options

Paths to bridge.js and Node are specified only through the constructor:

$compiler = new Compiler('/path/to/bridge.js', '/path/to/node');

Option	Type	Description	Possible values	Default
syntax	string	Input syntax	'scss' for SCSS, 'indented' or 'sass' for SASS	scss
style	string	Output style	'compressed' or 'expanded'	expanded
optimizeCss	bool	Enables post-processing and minification via Lightning CSS	true or false	true
includeSources	bool	Include source code in map	true or false	false
loadPaths	array	Array of paths for searching Sass imports	['./libs', './node_modules']	[]
quietDeps	bool	Suppresses warnings from dependencies	true or false	false
silenceDeprecations	array	Suppresses warnings about specific deprecations	['import', 'color-functions']	[]
verbose	bool	Enables verbose output of messages	true or false	false
removeEmptyLines	bool	Removes extra empty lines in non-compressed output	true or false	false
sourceMapPath	string	inline, URL, directory, or file path for source map		disabled
url	string	Sets the source URL used by Sass and source maps	file or HTTP(S) URL	auto in compileFile(), unset in compileString()
sourceFile	string	Sets the virtual source filename for bridge processing	e.g. style.scss	internal bridge default
streamResult	bool	Returns large compilation results as chunks	true or false	false

Options are passed only as an Options object, either for the entire compiler or for a specific method call:

use Bugo\Sass\Options;

$compiler->setOptions(new Options(
    syntax: 'indented',
    style: 'compressed',
    optimizeCss: true,
    sourceMapPath: '/out/style.map',
));

$css = $compiler->compileString($scss, new Options(
    style: 'compressed',
    optimizeCss: false,
    sourceMapPath: 'inline',
));

All available options in Options default to null, which means the option was not explicitly set. The Default column describes the effective compiler behavior in that case.