ThemeConfigurator

MMO\client · 1 symbol · generated 5 Oct 2026

class

ThemeConfigurator

Reads the theme's token layer, lets an application change any value in it, and writes the result back as Simple CSS.

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

Namespace: MMO\client
Extends: aModule
See: apply writes the json, writes the .scs, then asks Theme to recompile the stylesheet. In dev mode the target is also rebuilt whenever a source file becomes more recent than it (isUpToDate), so a token added to the library is never hidden by a stale generated copy.

### What it configures The theme is `.scs`, so "what can be customised" is not a hand written list: it is every value the token sources declare. The configurator parses them ([`$sources`](https://mcp.mmoframework.fr/documentation/mmo.client/php/ThemeConfigurator.md#themeconfigurator-sources) -- `tokens.scs` and `dark.scs` by default) and exposes, as one flat model: | in the source | what the model calls it | editable | |----------------------------------------|--------------------------------------|----------| | `@let $brand = (s500: #2F62F0, ...)` | `tokens:let::brand.s500` | yes | | `@let $ink = #0E1730` | `tokens:let::ink` | yes | | `@theme { color {bg: $palette.n50} }` | `tokens:theme::color.bg` | yes | | `@theme dark { ... }` | `tokens:theme:dark:color.bg` | yes | | `--mmo-shadow-sm` inside an `@style` | `dark:style:dark-tokens:--mmo-shadow-sm` | yes | | `@config varPrefix = "mmo-"` | `tokens:config::varPrefix` | **no** | `@config` is shown but locked: it is a compiler setting, not a theme value -- renaming the custom property prefix would leave every compiled element referencing `var(--mmo-*)` while the document declares something else, and nothing on the page would have a colour any more. ### How a change is applied An override is stored as the *expression* the user wrote, against the entry's key, in [`$config`](https://mcp.mmoframework.fr/documentation/mmo.client/php/ThemeConfigurator.md#themeconfigurator-config) (json). From there [`generate`](https://mcp.mmoframework.fr/documentation/mmo.client/php/ThemeConfigurator.md#themeconfigurator-generate) parses each source, substitutes the overridden expressions into the ast and prints the whole thing back ([`Printer`](https://mcp.mmoframework.fr/documentation/mmo.client/php/scs/Printer.md#printer)) into [`$target`](https://mcp.mmoframework.fr/documentation/mmo.client/php/ThemeConfigurator.md#themeconfigurator-target) -- a single `.scs` file the application's stylesheet imports **last**: ```css Printing the sources rather than emitting a list of literals is what keeps the derivations intact: a token written `bg: $palette.n50` stays that expression, so changing `$palette.n50` moves every token derived from it. Only the entries someone actually changed become literals. ### Regenerating

$configurator = ThemeConfigurator::Shared(); $configurator->apply(['tokens:let::brand.s500' => '#8B5CF6']); foreach ($configurator->getModel()['sections'] as $section) {...}

Index

	MAX_LENGTH
	config
	enabled
	labels
	model
	overrides
	sources
	target
	varPrefix
	apply($overrides)	Store a new configuration, regenerate the token layer, and recompile the application's css.
	build()	Write `$target` from the stored overrides, without touching the configuration.
	DefaultConfig() static
	Dig($values, $path) static
	Filename($file) static
	generate($overrides)	The generated token layer: every source, printed back with the overrides substituted into its ast.
	getConfigFile($resolve)
	getModel($reload)	The whole customizable surface, read from the sources.
	getOverrides()
	getResolvedValues($overrides)	What every entry would really be worth under a candidate configuration.
	getSources()
	getTarget($resolve)
	isEnabled()
	isUpToDate()
	MapOf($node) static
	preview($overrides)	Compile a candidate token layer without writing anything.
	printExpression($key, $entry, $value)	Parse one submitted value the way the source parses the entry it replaces, and print it back.
	readStatement($statement, $namespace, $printer)	The entries one top-level statement declares.
	reject($key, $node)	Refuse the two things a value must never reach for, whatever an application authorized for its own stylesheets: the php bridge, and the compilation context.
	replacement($key, $kind, $overrides)	Parse one stored override back into the ast node that replaces the source's own.
	reset()	Drop every override and rebuild: the theme goes back to what the sources declare.
	resolve()	Fill in what only a compilation knows: the value each token really ends up with once the expressions are evaluated.
	resolveWith($entries, $source)
	Short($file) static
	substitute($statement, $namespace, $overrides)	Replace, in place, the value nodes of a statement whose entry is overridden.
	TypeOf($entry) static	What kind of control an entry deserves: this is a hint for the interface, never something the compiler reads -- a value the model calls a colour is still just an expression.
	validate($overrides)	Validate a set of overrides against the model.
	ValueOf($statement) static	The single value node a synthetic snippet declared.
	variableName($path)
	__wakeup()

Constants1

MAX_LENGTH

const MAX_LENGTH = 512

Properties8

config

protected string $config

Type: string

enabled

protected bool $enabled = false

Type: bool

It is off by default because turning it on is a decision about the *stylesheet*: the generated token layer only reaches the page if the application's own stylesheet imports it ([`$target`](https://mcp.mmoframework.fr/documentation/mmo.client/php/ThemeConfigurator.md#themeconfigurator-target)), and [`Theme`](https://mcp.mmoframework.fr/documentation/mmo.client/php/Theme.md#theme) keeps that file current only for an application that says it wants one.

labels

protected array $labels = […17 items]

Type: array

model

protected ?array $model = null

Type: null | array

overrides

protected ?array $overrides = null

Type: null | array

sources

protected array $sources

Type: array

target

protected string $target

Type: string

varPrefix

protected string $varPrefix = ''

Type: string

Methods30

apply($overrides)

ThemeConfigurator.php:783

Store a new configuration, regenerate the token layer, and recompile the application's css.

function apply(array $overrides): array

Nothing is kept if the result does not compile: the previous configuration and the previous generated file are put back, so a theme that cannot be built never replaces one that could.

$overrides	array	entry key => expression, an empty value dropping the override
returns	array	`['overrides' => [...], 'css' => the compiled stylesheet, 'generated' => the .scs written]`
throws		when the configurator is disabled
throws		when an override is not valid
throws		when the theme, or the application's stylesheet, does not compile

build()

ThemeConfigurator.php:766

Write $target from the stored overrides, without touching the configuration.

function build(): void

This is the repair path: it is what the dev-mode job runs when a source file has changed under a generated copy, and what creates the file the first time -- an application whose stylesheet imports a target that does not exist yet does not compile at all.

returns

void

DefaultConfig()

staticThemeConfigurator.php:108

static function DefaultConfig(): array

returns

array

Dig($values, $path)

staticThemeConfigurator.php:540

protected static function Dig(array $values, array $path): ?MMO\client\scs\Value

$values	array	the compile-time variables of a compilation
$path	array	`['brand', 's500']`
returns	null \| Value

Filename($file)

staticThemeConfigurator.php:155

protected static function Filename(string $file): string

$file	string	a configured path
returns	string	the file, with its placeholders resolved and its `..` folded away -- these paths are read back by a human, in the generated file's header and in every error this module reports

generate($overrides)

ThemeConfigurator.php:613

The generated token layer: every source, printed back with the overrides substituted into its ast.

function generate(?array $overrides = null): string

$overrides = null	null \| array	the overrides to apply, defaulting to the stored ones
returns	string	the `.scs` source, ready to be written into `$target`
throws		when a source is missing

getConfigFile($resolve)

ThemeConfigurator.php:142

function getConfigFile(bool $resolve = true): string

$resolve = true	bool
returns	string

getModel($reload)

ThemeConfigurator.php:335

The whole customizable surface, read from the sources.

function getModel(bool $reload = false): array

$reload = false	bool	true to parse the sources again rather than reuse what this request already read
returns	array	`['sources' => [...], 'sections' => [...], 'entries' => [key => entry]]`, where a section is `['key', 'label', 'source', 'kind', 'entries' => [key, ...]]` and an entry is `['key', 'label', 'name', 'kind', 'section', 'source', 'base', 'value', 'resolved', 'type', 'variable', 'overridden', 'editable']`

getOverrides()

ThemeConfigurator.php:181

function getOverrides(): array

returns

array

the stored overrides: entry key => the expression that replaces the source's own

getResolvedValues($overrides)

ThemeConfigurator.php:489

What every entry would really be worth under a candidate configuration.

function getResolvedValues(array $overrides): array

An expression says nothing on its own -- `$brand.s500` is a colour only once the maps are evaluated, and moving a map moves every token derived from it. This is how an interface shows the *result* of a change it has not saved yet.

$overrides	array
returns	array	entry key => the value the compiler produced for it
throws		when an override is not valid

getSources()

ThemeConfigurator.php:146

function getSources(): array

returns

array

the source files, resolved

getTarget($resolve)

ThemeConfigurator.php:143

function getTarget(bool $resolve = true): string

$resolve = true	bool
returns	string

isEnabled()

ThemeConfigurator.php:141

function isEnabled(): bool

returns

bool

isUpToDate()

ThemeConfigurator.php:162

function isUpToDate(): bool

returns bool true when $target exists and is more recent than every source and than $config

MapOf($node)

staticThemeConfigurator.php:554

protected static function MapOf(MMO\client\scs\nodes\Node $node): ?MMO\client\scs\nodes\MapNode

$node	Node
returns	null \| MapNode	the map a `@let` declares, null when it declares anything else

preview($overrides)

ThemeConfigurator.php:747

Compile a candidate token layer without writing anything.

function preview(array $overrides): array

This is the preview: the generated file *is* the token layer, so compiling it alone produces exactly the `:root` rule and the dark theme's rules, and nothing else -- a stylesheet a page can append to its head to see the theme it is about to save.

$overrides	array
returns	array	`['css' => the token layer's css, 'resolved' => [entry key => value]]`
throws		when an override does not parse
throws		when the resulting token layer does not compile

printExpression($key, $entry, $value)

ThemeConfigurator.php:248

Parse one submitted value the way the source parses the entry it replaces, and print it back.

protected function printExpression(string $key, array $entry, string $value): string

$key	string
$entry	array	the model entry being overridden
$value	string	the submitted expression
returns	string	the expression, as this package would have written it
throws		when it does not parse, or reaches outside what a value may name

readStatement($statement, $namespace, $printer)

ThemeConfigurator.php:396

The entries one top-level statement declares.

protected function readStatement( MMO\client\scs\nodes\Node $statement, string $namespace, MMO\client\scs\Printer $printer ): Generator

$statement	Node
$namespace	string	the source's namespace, which is its own file name
$printer	Printer
returns	Generator

reject($key, $node)

ThemeConfigurator.php:302

Refuse the two things a *value* must never reach for, whatever an application authorized for its own stylesheets: the php bridge, and the compilation context. Both are for code the application wrote.

protected function reject(string $key, MMO\client\scs\nodes\Node $node): void

$key	string
$node	Node
returns	void
throws

replacement($key, $kind, $overrides)

ThemeConfigurator.php:711

Parse one stored override back into the ast node that replaces the source's own.

protected function replacement(string $key, string $kind, array $overrides): ?MMO\client\scs\nodes\Node

The stored text was printed from an ast that [`validate`](https://mcp.mmoframework.fr/documentation/mmo.client/php/ThemeConfigurator.md#themeconfigurator-validate) had already checked, so this re-parses this package's own output -- but it is parsed in the entry's context all the same, because that is what decides whether `16px -4px` is two lengths or a subtraction.

$key	string
$kind	string
$overrides	array
returns	null \| Node	null when this entry carries no override
throws		when the stored value no longer parses (a hand edited json)

reset()

ThemeConfigurator.php:837

Drop every override and rebuild: the theme goes back to what the sources declare.

function reset(): array

returns array apply

resolve()

ThemeConfigurator.php:473

Fill in what only a compilation knows: the value each token really ends up with once the expressions are evaluated. A failed compilation is not fatal here -- the model still describes the sources, it simply shows the expressions instead of the values they produce.

protected function resolve(): void

returns

void

resolveWith($entries, $source)

ThemeConfigurator.php:498

protected function resolveWith(array $entries, string $source): array

$entries	array	the model's entries, which say what to look for
$source	string	a generated token layer
returns	array	entry key => resolved value, empty when the source does not compile

Short($file)

staticThemeConfigurator.php:530

protected static function Short(string $file): string

$file	string
returns	string	the file, relative to the application's base path when it lives under it

substitute($statement, $namespace, $overrides)

ThemeConfigurator.php:661

Replace, in place, the value nodes of a statement whose entry is overridden.

protected function substitute( MMO\client\scs\nodes\Node $statement, string $namespace, array $overrides ): void

$statement	Node	a statement of a freshly parsed source -- never a shared ast
$namespace	string
$overrides	array
returns	void

TypeOf($entry)

staticThemeConfigurator.php:570

What kind of control an entry deserves: this is a hint for the interface, never something the compiler reads -- a value the model calls a colour is still just an expression.

protected static function TypeOf(array $entry): string

$entry	array
returns	string	`color`, `length`, `number`, `duration`, `easing`, `font`, `shadow` or `text`

validate($overrides)

ThemeConfigurator.php:210

Validate a set of overrides against the model.

function validate(array $overrides): array

Every value is re-parsed *in the context of the entry it replaces* -- a theme token as a theme token, a map entry as a map entry -- and then printed back from the ast. What is stored is that printed form, never the text the request carried: an expression that cannot be parsed is refused, and one that can cannot carry anything the parser did not put in the tree (no stray brace closing the `@theme` block, no second declaration smuggled after a `;`).

$overrides	array	entry key => expression, an empty value dropping the override
returns	array	the sanitized overrides
throws		on an unknown key, a locked entry, or an expression that does not parse

ValueOf($statement)

staticThemeConfigurator.php:285

The single value node a synthetic snippet declared.

protected static function ValueOf(?MMO\client\scs\nodes\Node $statement): ?MMO\client\scs\nodes\Node

The snippet is written so that the submitted text is the only value in it. Anything the parser managed to read *beyond* that value -- a second token because the text carried a `;` or a newline, a second declaration, a rule -- means the text was not one value, and the whole override is refused rather than silently truncated to its first term.

$statement	null \| Node	the only statement of the parsed snippet
returns	null \| Node	the value node, null when the snippet declared anything else than exactly one value

variableName($path)

ThemeConfigurator.php:600

protected function variableName(string $path): string

The prefix is the one *these sources* compile with, not the compiler's own default: `tokens.scs` sets it with `@config varPrefix = "mmo-"`, and that is an entry of this very model ([`readStatement`](https://mcp.mmoframework.fr/documentation/mmo.client/php/ThemeConfigurator.md#themeconfigurator-readstatement)), so the name shown next to a token is the name the page really carries.

$path	string	a token's dotted path
returns	string	the css custom property it is emitted as

__wakeup()

ThemeConfigurator.php:116

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.