detain / phlix-plugin-sample-theme
Reference ui-theme plugin for Phlix — two token-map themes registered through ThemeSourceInterface.
Package info
github.com/detain/phlix-plugin-sample-theme
Type:phlix-plugin
pkg:composer/detain/phlix-plugin-sample-theme
Requires
- php: >=8.3
- detain/phlix-shared: ^0.21
- psr/container: ^1.1 || ^2.0
Requires (Dev)
- phpstan/phpstan: ^2.2
- phpunit/phpunit: ^10.0
- squizlabs/php_codesniffer: ^4.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-19 15:34:25 UTC
README
A complete, installable ui-theme plugin — the reference for shipping a
theme to the Phlix SPA. Fork it, rename it, change the token values —
Renaming your fork enumerates every identifier the
rename touches.
phlix-plugin-sample-theme/
├── composer.json # PSR-4 autoload for the entry class
├── composer.lock # COMMITTED — the S440 gate audits the whole lock
├── plugin.json # manifest: type "ui-theme", entry FQCN
├── CHANGELOG.md # release history; version markers carry git coords
├── LICENSE # MIT — the copyright line is a fork-rename target
├── .gitignore # hygiene excludes — composer.lock deliberately NOT ignored
├── .github/workflows/test.yml # CI; the composer-audit leg is the LAST job (guard-pinned)
├── scripts/
│ └── security-audit-check.php # the S440 gate — whole-lock audit, capable of failing
├── src/SampleThemePlugin.php # LifecycleInterface + ThemeSourceInterface
├── dev-stubs/ # host-only contracts, for THIS repo's CI only
├── tests/
│ ├── bootstrap.php
│ ├── SampleThemePluginTest.php # payload laws: counts, grammar, contrast, aliases
│ └── SecurityAuditCheckTest.php # guard: pins the gate script + workflow against neutering
├── phpunit.xml
├── phpstan.neon
└── phpcs.xml # tool configs (scripts/ exclusions are documented in both)
Four of those artifacts exist because the estate requires a theme to ship its
own gate: scripts/security-audit-check.php, its guard test, the committed
lock, and the audit-last workflow are what a fork must KEEP, not just rename.
Installing it
The supported route: the plugin catalog
The Phlix server installs plugins from a catalog (plugins.json). A catalog
entry pins an exact commit (ref) and the sha256 of that commit's tarball
(artifactSha256), and the server verifies those bytes before it extracts
anything. Without a pin, PluginLoader::install() refuses outright — that is a
deliberate default-deny, not a bug to work around.
Admin UI — Admin → Plugins (/app/admin/plugins), find Sample Theme,
press Install, then flip its switch to enable it. (The page posts the
catalog entry's repo URL to POST /api/v1/admin/plugins/install; the server
matches that URL against the catalog and supplies the pin itself.)
CLI — the same thing, from the server root:
php bin/phlix plugin:install https://github.com/detain/phlix-plugin-sample-theme php bin/phlix plugin:enable phlix-plugin-sample-theme php bin/phlix plugin:list
Two details that are easy to get wrong:
- Pass the repository URL, not the plugin name.
pinFor()will match a barephlix-plugin-sample-themeagainst the catalog and find the pin, but the source string itself is then handed to the installer unchanged, andphlix-plugin-sample-themeis not something it can download. TherepoURL is rewritten to…/archive/<pinned-ref>.tar.gz; the name is not. - No environment override is needed.
PHLIX_PLUGINS_ALLOW_UNVERIFIED=1exists for un-pinned sources. A catalog entry is pinned, so it is not required — if you find yourself reaching for it, the catalog entry is the thing that is wrong.
A local build, for developing your own theme
While you are iterating on a fork there is no catalog entry yet. Build a
tarball and install it over file://, which is exempt from the pin requirement
because the bytes are already yours:
tar --exclude=vendor --exclude=.git -czf /tmp/my-theme.tar.gz phlix-plugin-my-theme/ php bin/phlix plugin:install file:///tmp/my-theme.tar.gz php bin/phlix plugin:enable phlix-plugin-my-theme
A .zip works identically. The archive may have a single top-level directory
(the shape git archive and GitHub's codeload produce) — the installer lifts
its contents up automatically.
What does not work: a bare directory
# WRONG — this has never worked, in any version.
php bin/phlix plugin:install examples/plugins/phlix-plugin-sample-theme
Unsupported plugin source extension for examples/plugins/phlix-plugin-sample-theme
— expected .zip, .tar.gz, .tgz, or .json.
SourceUrlResolver::normalize() passes a plain path through unchanged, and
HttpInstaller::fetchInto() dispatches on the extension. A directory has none,
so it falls through to that throw. Pack it first (above). The host does have a
installFromDirectory() entry point, but no CLI command or admin route is wired
to it — it is used by the integration tests.
How registration works
There is no manifest theme key and no onEnable() wiring. The entry class
implements Phlix\Theming\ThemeSourceInterface, and PluginLoader::enable()
registers it off the instanceof — the same one-arm capability pattern the
metadata- and subtitle-source plugins use. Excerpt, not a template: the
three LifecycleInterface methods are elided here (the theme has nothing to
do in any of them) — paste the complete class from src/SampleThemePlugin.php,
never this sketch:
final class SampleThemePlugin implements LifecycleInterface, ThemeSourceInterface { public function themeSourceName(): string { return 'sample-theme'; } public function providedThemes(): array { return [[ 'id' => 'sample-dusk', 'name' => 'Sample Dusk', 'dark' => true, 'extends' => 'midnight', 'tokens' => ['--bg' => '#05060a', /* … */], ]]; } }
Disabling the plugin deregisters exactly the ids it contributed. The manifest's
"type": "ui-theme" is documentation for humans and for the admin UI's category
label — the loader never reads it. A class that implements the interface is
registered whatever its manifest says; a class that does not implement it is not
registered however it is labelled.
The two rules a theme must obey
-
Keys must be on
Phlix\Theming\ThemeTokenAllowlist— the 53 semantic colour tokens of@phlix/tokens/src/css/colors.css. Layout tokens (density, spacing, radius, shadow, motion) are not settable: a theme recolours the UI, it never moves it. -
Values must be a hex colour,
rgb()/rgba()/hsl()/hsla()over numeric arguments, a bare number,transparent, orcurrentColor— in full.var(--x),url(…),;,}and every other CSS construct are rejected by having no production in the grammar, not by a blocklist.⚠ This is the trap. The built-in themes are written as
var()chains in colors.css, so copying a value straight out of that file gives youvar(--amber-500)— which the validator refuses. A plugin ships literals. This repo'stestNoTokenValueCarriesACssConstructTheHostGrammarRejectsis the guard against re-introducing one.
A payload that breaks either rule fails the whole plugin enable. Registration is all-or-nothing and never silent.
Allowlisted ≠ read: why this sample sets 28 tokens, not 53
Setting a custom property nothing reads is a no-op. Thirteen of the 53
allowlisted names are --color-* aliases the host's S228 finding named dead,
on a shared census (first measured 2026-08-04 from the shipped SPA;
re-censused 2026-09-05 across every repo's var() surface — phlix-server's
ThemeTokenAllowlist records it): twelve have zero var() consumers
estate-wide, and the thirteenth — --color-primary — is read by exactly
one surface, the dev-only preview page phlix-ui/src/dev/swatches.html,
which ships to no client. The thirteen:
--color-primary --color-surface-hover --color-error-bg
--color-primary-hover --color-surface-elevated --color-success-bg
--color-primary-active --color-surface-active --color-warning-bg
--color-text-secondary --color-border-subtle --color-info-bg
--color-text-subtle
This sample omits all thirteen on purpose, and a test keeps them omitted. The
nine aliases that are still read — --color-bg, --color-surface,
--color-text, --color-text-muted, --color-border and the four status
aliases — are set wherever the corresponding modern token is overridden.
If you fork this plugin, keep that habit: re-hue through the six semantic
--accent* tokens and the surface/text/border ramps, and only add an alias you
can point at a real var() consumer.
Two of those tokens carry inverse roles that are constantly confused —
including by sibling themes in this estate's own cohort.
--accent-text is the accent hue used as foreground: text and icons
painted on --bg/--surface, so it must clear AA body contrast (4.5:1) there.
--text-on-accent is the ink used on accent fills: button labels and
selected states, read against the accent, not against the page. They are never
equal — making --accent-text the on-fill value renders accent-on-accent text
at ≈1:1 (one green-hued theme family shipped exactly that bug as focus text and
initials).
What the two sample themes demonstrate
| Theme | extends |
Point |
|---|---|---|
sample-dusk |
midnight (built-in) |
The base is applied by mechanism: the SPA sets data-theme="midnight" — whose real values then come from its bundled stylesheet — and layers these tokens over it with el.style.setProperty(). The server does know midnight's map and publishes it in the list; the wire just never flattens chains — tokens is always the theme's own map. Status colours are intentionally not overridden, so they fall through from the base. |
sample-dusk-high-contrast |
sample-dusk (plugin) |
A plugin→plugin chain: no stylesheet knows the base, so the SPA merges it from data. Only the LIST endpoint (GET /api/v1/themes) carries every link, which is why the SPA reads the list and never /themes/{id}. |
Seeing it in the SPA
- Install and enable the plugin — a fresh install lands disabled.
GET /api/v1/themes(authenticated) now lists five themes: the three built-ins plus these two, each withbuiltIn,sourceand its owntokensmap.- Settings → Appearance shows five swatches; picking one applies it live and caches the resolved token map so the next page load paints it with no flash.
If the picker still shows three, the plugin is installed but not enabled, or the
worker has not re-attached it — php bin/phlix plugin:list tells you which.
Renaming your fork
Every identifier a cloner must change, in the order a grep finds them. A fork
that renames only the display name is still sample-theme to the host — and
item 7 makes that variant dangerous, not cosmetic.
- composer.json —
name(detain/phlix-plugin-sample-theme),homepage,description,keywords. - plugin.json —
name. This is the stringphp bin/phlix plugin:enable(anddisable/uninstall) take as its argument; the server's install directory is derived from it. - plugin.json —
entryFQCN (Phlix\\PluginSampleTheme\\SampleThemePlugin). It must move together with items 4 and 6 or the loader'sclass_exists($manifest->entry)fails at enable. - Namespace
Phlix\PluginSampleTheme— insrc/andtests/, and the string embedded inscripts/security-audit-check.php(@packageand the docblock cite of the guard test at :102/:115) — the guard test reads the script's own text, so the rename must land in both. - autoload-dev namespace
Phlix\PluginSampleTheme\Tests(composer.json). - Class name and files —
SampleThemePlugininsrc/SampleThemePlugin.phpandtests/SampleThemePluginTest.php(PSR-4 requires class↔filename agreement). SOURCE_NAME(src/SampleThemePlugin.php:102, currently'sample-theme') — the rename that fails silently. Read the note below before you skip it.- Theme ids and display names —
sample-dusk,sample-dusk-high-contrast,Sample Dusk,Sample Dusk (High Contrast). "Sample" is placeholder copy: shipping it means users pick "Sample Dusk" from your server's appearance picker. Ids collide loudly (see below); the display name is pure branding, so change both. (The admin plugin list's title — "Sample Theme" in the walkthrough above — lives in neither: it is minted when the catalog curates your repo into phlix-plugins'plugins.json, so expect to change it there, at curation, not here.) - The S440 guard token —
S440SAMPTHEMEGATEX6B2intests/SecurityAuditCheckTest.php(constant, equality assertion, and the "Lane token:" header line). Every theme repo in the estate was minted a unique token when the guard was propagated; a fork mints its own too — it identifies your lane in CI logs. - Housekeeping — regenerate
composer.lock(composer update, never hand-edit), theLICENSEcopyright line together with the@copyrightfile headers it mirrors (both name the same holder — keep them in step), this README's title and URLs, and anything in.github/workflows/that names the repo.
Why item 7 is the dangerous one. ThemeSourceRegistry keys provenance by
source name, and re-registering a name replaces the previous contribution
(drop-then-add, never append — phlix-server/src/Theming/ThemeSourceRegistry.php:41).
Two enabled plugins both named sample-theme therefore silently delete each
other's themes whenever either enables. Duplicate theme ids at least fail
loudly: registration throws "… is already registered by …" (:121). The quiet
failure mode is exactly the identifier "Fork it, rename it" would never prompt
you to touch, which is why it is spelled out here.
The fork-inverse of "Keep it constant across versions." The docblock above
SOURCE_NAME tells the reference plugin to never change it — that law
applies to a fork after its one mandatory rename: change it once, when you
fork, and then keep that value constant forever, because users already
installed under it and disable/uninstall remove exactly its ids.
Developing
composer install vendor/bin/phpunit vendor/bin/phpstan analyse -c phpstan.neon # level 9 vendor/bin/phpcs --standard=phpcs.xml # PSR-12
dev-stubs/ holds minimal copies of the two host contracts
(Phlix\Shared\Plugin\LifecycleInterface, which ships in detain/phlix-shared,
and Phlix\Theming\ThemeSourceInterface, which ships in no Composer package
at all — it is declared by the server). tests/bootstrap.php loads each only
when the real one is absent, and phpstan.neon picks them up via
scanDirectories. They exist so this repo's CI can run standalone; they are
never used inside a real server, where the host supplies both.
Licence
MIT, matching the rest of the Phlix plugin/interop surface. (Phlix's applications are MPL-2.0; plugins, clients and interop libraries are MIT.)