SCSCompiler

MMO\client · 1 symbol · generated 30 Sep 2026

class

SCSCompiler

Compiles Simple CSS (.scs) into css.

class MMO\client\SCSCompiler extends MMO\core\classes\aModule

Namespace: MMO\client
Extends: aModule
See: docs/SimpleCSS.md for the language reference.

Simple CSS is a small compile-time layer over css: compile-time variables (`@let`), design tokens (`@theme`, emitted as css custom properties), reusable styles (`@style` / `@use`), functions (`@fn`), components and variants, nesting, responsive blocks (`@screen`), conditions, loops, explicit ordering (`@order`) and an explicitly authorized php bridge (`php::name()`, `context::name`). Every file is a namespace, named after itself, and a reference to another file names it -- so reading `@use lib::center`, `lib::step(2)` or `$lib::gutter` tells you which file declares them: ```css Unlike @see DartSass, nothing is shelled out: the whole pipeline is pure php, so it runs anywhere the framework runs. ### Compiling ```php $css = SCSCompiler::Shared()->compileText('@let $s = 16px;' . PHP_EOL . '.card {padding: $s;}')->css(); ``` ### The php bridge A php function is **never** callable from a stylesheet unless the application explicitly authorizes it: ```php SCSCompiler::Shared() ->allowFunction('php::round', 'round') ->allowContextFunction('php::cardPadding', \App\Css\Functions::cardPadding(...)); ``` ```css .card {padding: php::cardPadding()} ``` A context function additionally receives the current [`EvaluationContext`](https://mmoframework.fr/documentation/mmo.client/php/scs/EvaluationContext.md#evaluationcontext) -- the injected context, the resolved selector, the scope and the source position.

Index

	allowImports
	componentSelector
	context
	emitThemes
	errorTemplate
	indent
	minify
	optimize
	paths
	registry
	resolveThemeValues
	screens
	sourceMap
	strictFunctions
	themeSelector
	variantSelector
	varPrefix
	allowContextFunction($name, $callable)	Authorize a php callable that also receives the current `EvaluationContext` (the injected context, the resolved selector, the scope and the source position) as its first argument.
	allowFunction($name, $callable)	Authorize a php callable, so stylesheets may call it as `php::name(...)`.
	compile($filename, $src, $context, $options)	Compile a .scs file into a .css file.
	compileFile($src, $context, $options)	Compile a .scs file.
	compileText($source, $context, $options, $filename)	Compile a .scs source.
	createCompiler($context, $options)
	DefaultConfig() static
	evaluate($expression, $context, $selector)	Evaluate a single scs expression, with no css generated.
	registry()
	renderError($filename, $errors)	Render a compilation error as css, so the browser shows it.
	setContext($path, $value)	Add a value to the context every compilation starts with.
	__wakeup()

Properties17

allowImports

bool $allowImports

Type: bool

componentSelector

string $componentSelector

Type: string

context

array $context

Type: array

emitThemes

bool $emitThemes

Type: bool

errorTemplate

string $errorTemplate

Type: string

indent

string $indent

Type: string

minify

bool $minify

Type: bool

optimize

bool $optimize

Type: bool

paths

array $paths

Type: array

registry

#[MMO\core\attributes\Serialize(false)] protected ?MMO\client\scs\PhpFunctionRegistry $registry = null

Type: null | PhpFunctionRegistry

resolveThemeValues

bool $resolveThemeValues

Type: bool

screens

array $screens

Type: array

sourceMap

string|bool $sourceMap

Type: string | bool

strictFunctions

bool $strictFunctions

Type: bool

themeSelector

string $themeSelector

Type: string

variantSelector

string $variantSelector

Type: string

varPrefix

string $varPrefix

Type: string

Methods12

allowContextFunction($name, $callable)

SCSCompiler.php:190

Authorize a php callable that also receives the current EvaluationContext (the injected context, the resolved selector, the scope and the source position) as its first argument.

function allowContextFunction(string $name, callable $callable): static

$name	string
$callable	callable	function(EvaluationContext $context, ...$args): mixed
returns	static

SCSCompiler::Shared()->allowContextFunction('php::cardPadding', function (EvaluationContext $c) { return (($c->compilation()->get('density') ?? 1) * 8) . 'px'; });

allowFunction($name, $callable)

SCSCompiler.php:174

Authorize a php callable, so stylesheets may call it as php::name(...).

function allowFunction(string $name, callable $callable): static

> Only expose deterministic, side effect free functions: they run at *compile* time, with whatever > arguments the stylesheet chooses.

$name	string	the name visible inside scs, ex: `php::round`
$callable	callable	the actual php callable
returns	static

SCSCompiler::Shared()->allowFunction('php::round', 'round');

compile($filename, $src, $context, $options)

SCSCompiler.php:253

Compile a .scs file into a .css file.

function compile(string $filename, string $src, array $context = [], array $options = []): ?MMO\client\scs\Result

On failure the error is logged and written into the target as a visible css message, so a broken stylesheet never silently serves the previous css (same behaviour as [`DartSass::compile`](https://mmoframework.fr/documentation/mmo.client/php/DartSass.md#dartsass-compile)).

$filename	string	the css file to write
$src	string	the .scs source file
$context = []	array
$options = []	array
returns	null \| `Result`	null when the compilation failed

compileFile($src, $context, $options)

SCSCompiler.php:235

Compile a .scs file.

function compileFile(string $src, array $context = [], array $options = []): MMO\client\scs\Result

$src	string
$context = []	array
$options = []	array
returns	`Result`
throws		when the file does not exist

compileText($source, $context, $options, $filename)

SCSCompiler.php:223

Compile a .scs source.

function compileText( string $source, array $context = [], array $options = [], string $filename = '<scs>' ): MMO\client\scs\Result

$source	string
$context = []	array	values injected for this compilation, read as `context::name`
$options = []	array	per-compilation overrides (`minify`, `varPrefix`, `screens`, ...)
$filename = '<scs>'	string	the source name, used by `@import` resolution and error messages
returns	`Result`
throws		when the source does not compile

$result = SCSCompiler::Shared()->compileText($scs, ['density' => 2]); echo $result->css();

createCompiler($context, $options)

SCSCompiler.php:314

protected function createCompiler(array $context, array $options): MMO\client\scs\Compiler

$context	array	per-compilation context values, merged over `$context`
$options	array	per-compilation option overrides
returns	`Compiler`	a compiler configured with this module's options

DefaultConfig()

staticSCSCompiler.php:110

static function DefaultConfig(): array

returns

array

evaluate($expression, $context, $selector)

SCSCompiler.php:290

Evaluate a single scs expression, with no css generated.

function evaluate(string $expression, array $context = [], ?string $selector = null): MMO\client\scs\Value

This is what lets an application share a calculation with its stylesheet (`the` spec, 48B.6).

$expression	string	ex: `php::calculatePadding()`
$context = []	array
$selector = null	null \| string	the selector context-aware php functions should see
returns	`Value`

SCSCompiler::Shared()->evaluate('php::calculatePadding()', ['density' => 2], '.card');

registry()

SCSCompiler.php:159

function registry(): MMO\client\scs\PhpFunctionRegistry

returns PhpFunctionRegistry the php callables stylesheets are allowed to call

renderError($filename, $errors)

SCSCompiler.php:300

Render a compilation error as css, so the browser shows it.

function renderError(string $filename, array|string $errors): string

$filename	string
$errors	array \| string
returns	string

setContext($path, $value)

SCSCompiler.php:202

Add a value to the context every compilation starts with.

function setContext(string $path, mixed $value): static

$path	string	a dotted path, ex: `design.spacing.md`
$value	mixed
returns	static

SCSCompiler::Shared()->setContext('density', 2);

__wakeup()

SCSCompiler.php:133

function __wakeup(): void

returns

void

Inherited members (47)

Constants	Declared by	Description
`ALERT`	iLogLevel	Alert: Action must be taken immediately.
`ALL`	iLogLevel	Mask for all
`ALL_PLUS`	iLogLevel	debug everything
`BACKTRACE`	iLogLevel
`CRITICAL`	iLogLevel	Critical: Critical conditions.
`DEBUG`	iLogLevel	Debug: Detailed debug information.
`DEEP`	iLogLevel	debug everything with arguments
`EMERGENCY`	iLogLevel	Emergency: System is unusable.
`ERROR`	iLogLevel	Error: Runtime errors that do not require immediate action but should typically be logged and monitored.
`ERROR_PLUS`	iLogLevel	Mask for all error
`FATAL`	iLogLevel	Mask for all fatal error
`INFO`	iLogLevel	Info: Interesting events.
`INFO_PLUS`	iLogLevel	Mask for all errors/warning/notices/info
`MEMORY`	iLogLevel	include backtrace object
`NOTICE`	iLogLevel	Notice: Normal but significant events.
`NOTICE_PLUS`	iLogLevel	Mask for all errors/warning/notices/info
`TRACE`	iLogLevel	include backtrace as origins
`WARNING`	iLogLevel	Warning: Exceptional occurrences that are not errors.
`WARNING_PLUS`	iLogLevel	Mask for all errors and warnings

	Properties	Declared by	Description
	`verbosity`	aModule

Methods	Declared by	Description
`alert($message, $context)`	aModule	Action must be taken immediately.
`backtraces($message, $context)`	aModule	Force-log a message at INFO level together with a full stack trace/memory snapshot (`iLogLevel::BACKTRACE`), bypassing the verbosity mask entirely (any non-zero verbosity is enough to trigger it).
`Configure($config)`	aModule	Merge $config into this module's configuration in the shared `Configuration`.
`critical($message, $context)`	aModule	Critical conditions. No-op if CRITICAL is currently filtered out by the verbosity mask.
`debug($message, $context)`	aModule	Detailed debug information.
`debugName()`	aModule	Human-readable identifier used as the default `{origin}` in this instance's log messages.
`emergency($message, $context)`	aModule	System is unusable. No-op if EMERGENCY is currently filtered out by the verbosity mask.
`error($message, $context)`	aModule	Runtime errors that do not require immediate action but should typically be logged and monitored.
`getVerbosity()`	aModule
`info($message, $context)`	aModule	Interesting events. No-op if INFO is currently filtered out by the verbosity mask.
`Instantiate($config)`	aModule	(Re)create the shared instance immediately, configured with $config merged into the class's existing config.
`IsShared()`	aModule
`log($level, $message, $context)`	aModule	Logs with an arbitrary level.
`notice($message, $context)`	aModule	Normal but significant events.
`offsetExists($key)`	aModule	\ArrayAccess::offsetExists -- tells whether $key is a declared property at all, regardless of whether it is currently readable/writable through array access.
`offsetGet($key)`	aModule	\ArrayAccess::offsetGet -- reads a property directly, unless it has a `#[Serialize(serialize: 'methodName')]` attribute, in which case that zero-argument method is called instead (e.g.
`offsetSet($key, $value)`	aModule	\ArrayAccess::offsetSet -- sets a property directly, unless it has a `#[Serialize(unserialize: 'methodName')]` attribute, in which case that method is called with $value instead (e.g.
`offsetUnset($key)`	aModule	\ArrayAccess::offsetUnset -- equivalent to `$module[$key] = null`.
`serialize($path, $serializer)`	aModule	\MMO\core\interfaces\iSerializable::serialize -- exports every property (via
`setVerbosity($verb)`	aModule	Set the current verbosity mask, replacing whatever it was before.
`Shared()`	aModule	Get the shared instance, creating (and configuring) it on first call.
`testVerbosity($level)`	aModule	Test whether a given level (or set of levels) is currently enabled by this instance's verbosity mask.
`traitUnshare($serialize)`	aModule	Remove the shared instance, so the next `Shared()` call creates a fresh one.
`unserialize($data, $path, $instances)`	aModule	\MMO\core\interfaces\iSerializable::unserialize -- merges $data onto `DefaultConfig`, runs it through the (possibly overridden) constructor, then applies each resulting value to its property (via
`Unshare($serialize)`	aModule	Like `tSingleton::Unshare`, but also disconnects this module's instance from every event it was listening to (via `Event::DisconnectListeners`) before dropping it.
`warning($message, $context)`	aModule	Exceptional occurrences that are not errors.
`__construct($config)`	aModule	protected constructor, so it is not possible to do `new Module(...)` called by the serialization process just before being injected with data.