respondage_vanilla/variants/build.php

265 lines
12 KiB
PHP
Raw Normal View History

<?php
/**
* Build a thin client variant of this theme (respondage_vanilla).
*
* A variant is a separate LimeSurvey theme that extends this mother theme
* (<extends> in its config.xml). LimeSurvey then inherits ALL files
* (views, css, js, images, options page) from the mother theme, so any
* change made here in a file automatically applies to every variant.
*
* Only config.xml is generated per variant: it is a copy of this mother
* config.xml in which ONLY the house-style option values (colors, fonts,
* font sizes/colors/weights, logo files) listed in variants/<name>.json
* are replaced, plus the metadata (name/title/description/extends).
* The <engine> section is emptied except <optionspage>, so engine settings
* (css framework, packages, view/files directories, template editor) are
* inherited from the mother. The <files> section is kept as-is: LimeSurvey
* resolves each listed file in the variant first and then in the mother,
* so the mother's css/js keep loading until the variant ships its own file
* with the same name (which then replaces the mother's file). This mirrors
* what LimeSurvey itself does when you "extend" a theme in the theme editor.
*
* Usage:
* php variants/build.php <variantName> [definitions-dir]
*
* The definitions (variants/<variantName>.json) contain confidential client
* house-style values and are NOT kept in this (public) repository - see
* .gitignore. Store them in the private variants repository or locally, and
* point this script at that folder via the optional second argument or the
* RESPONDAGE_VARIANTS_DIR environment variable.
*
* Standard layout in that definitions dir per client:
* <variantName>.json house-style option values + fontOptions + files_add
* <variantName>/files/... client assets (logos, fonts in files/fonts/)
* <variantName>/css/... client css (e.g. css/variant.css with @font-face)
* The <variantName>/ folder is copied into the generated theme automatically.
*
* Example:
* php variants/build.php <client> /path/to/private-variants
*
* Optional keys in the variant json:
* "files_add": {"css": ["css/variant.css"], "js": []} extra files shipped by the
* variant, appended to the <files> list of the generated config.xml
* "fontOptions": [{"value": "my_custom_font", "label": "My Custom Font"}] custom fonts,
* appended to the "Custom (this theme)" optgroup of the font dropdown
*
* Output:
* ../<variantName>/config.xml (next to this theme, in upload/themes/survey)
*
* After running this script, upload the variant folder to
* upload/themes/survey/ and (re)install or reset the theme in LimeSurvey
* (Theme options -> reset), so the new config.xml is imported into the DB.
*
* If an option key in the json no longer exists in the mother config.xml,
* the script fails loudly, so drift between mother and variant is caught
* at build time instead of silently rendering wrong values.
*/
if (PHP_SAPI !== 'cli') {
fwrite(STDERR, "This script must be run from the command line.\n");
exit(1);
}
$variantName = isset($argv[1]) ? trim($argv[1]) : '';
if ($variantName === '' || !preg_match('/^[a-z0-9_]+$/i', $variantName)) {
fwrite(STDERR, "Usage: php variants/build.php <variantName> [definitions-dir]\n");
fwrite(STDERR, " <variantName> must match an existing <definitions-dir>/<variantName>.json file.\n");
fwrite(STDERR, " Default definitions-dir: the variants/ folder next to this script, or RESPONDAGE_VARIANTS_DIR.\n");
exit(1);
}
$motherDir = dirname(__DIR__); // .../themes/survey/respondage_vanilla
$themesDir = dirname($motherDir); // .../themes/survey
$motherConfig = $motherDir . DIRECTORY_SEPARATOR . 'config.xml';
$definitionsDir = $argv[2] ?? (getenv('RESPONDAGE_VARIANTS_DIR') ?: __DIR__);
$definitionFile = rtrim($definitionsDir, '/\\') . DIRECTORY_SEPARATOR . $variantName . '.json';
foreach ([$motherConfig, $definitionFile] as $f) {
if (!is_file($f)) {
fwrite(STDERR, "Required file not found: $f\n");
exit(1);
}
}
$definition = json_decode(file_get_contents($definitionFile), true);
if (!is_array($definition)) {
fwrite(STDERR, "Invalid JSON in $definitionFile\n");
exit(1);
}
$doc = new DOMDocument();
$doc->preserveWhiteSpace = false;
$doc->formatOutput = true;
if (!$doc->load($motherConfig)) {
fwrite(STDERR, "Could not parse mother config: $motherConfig\n");
exit(1);
}
$xpath = new DOMXPath($doc);
$motherName = (string) $xpath->query('//metadata/name')->item(0)->textContent;
// --- metadata: identify the variant, point extends to the mother theme ---
function setMetadata(DOMXPath $xpath, DOMDocument $doc, string $tag, string $value): void
{
$node = $xpath->query("//metadata/$tag")->item(0);
if ($node === null) {
$node = $doc->createElement($tag);
$xpath->query('//metadata')->item(0)->appendChild($node);
}
$node->textContent = $value;
}
/** Recursively copy a directory (used for the variant's own assets). */
function copyDirRecursive(string $src, string $dst): void
{
if (!is_dir($dst)) {
mkdir($dst, 0775, true);
}
$dir = opendir($src);
while (($entry = readdir($dir)) !== false) {
if ($entry === '.' || $entry === '..') {
continue;
}
$s = $src . DIRECTORY_SEPARATOR . $entry;
$d = $dst . DIRECTORY_SEPARATOR . $entry;
if (is_dir($s)) {
copyDirRecursive($s, $d);
} else {
copy($s, $d);
}
}
closedir($dir);
}
setMetadata($xpath, $doc, 'name', $definition['name'] ?? $variantName);
setMetadata($xpath, $doc, 'title', $definition['title'] ?? ucfirst($variantName));
if (isset($definition['description'])) {
setMetadata($xpath, $doc, 'description', $definition['description']);
}
setMetadata($xpath, $doc, 'extends', $motherName);
setMetadata($xpath, $doc, 'lastUpdate', date('Y-m-d H:i:s'));
// --- empty the <engine> section except <optionspage>: inherited from the mother ---
// (same as TemplateManifest::deleteEngineInDom() does when extending a theme in LimeSurvey)
$engineNode = $xpath->query('//engine')->item(0);
if ($engineNode !== null) {
foreach (iterator_to_array($engineNode->childNodes) as $child) {
if ($child instanceof DOMElement && $child->nodeName !== 'optionspage') {
$engineNode->removeChild($child);
} elseif ($child instanceof DOMComment) {
$engineNode->removeChild($child);
}
}
}
// --- extra files shipped by the variant itself ---
// In the variant json: "files_add": {"css": ["css/variant.css"], "js": []}
// They are appended to the <files> list. The mother's files keep loading until the
// variant ships a file with the same name; from that moment it replaces the mother's
// file (LimeSurvey "add" also means "replace" for identical paths).
if (!empty($definition['files_add'])) {
$filesNode = $xpath->query('//files')->item(0);
if ($filesNode === null) {
fwrite(STDERR, "No <files> section found in mother config\n");
exit(1);
}
foreach (['css', 'js', 'print_css'] as $type) {
$values = $definition['files_add'][$type] ?? [];
if (empty($values)) {
continue;
}
$typeNode = $xpath->query('//files/' . $type)->item(0);
if ($typeNode === null) {
$typeNode = $doc->createElement($type);
$filesNode->appendChild($typeNode);
}
foreach ((array) $values as $file) {
$add = $doc->createElement('add');
$add->appendChild($doc->createTextNode((string) $file));
$typeNode->appendChild($add);
}
}
}
// --- custom fonts of the variant, added to the font dropdown ---
// In the variant json: "fontOptions": [{"value": "my_custom_font", "label": "My Custom Font"}]
// The font files themselves live in the variant's files/fonts/ and the @font-face +
// body.font-<value> rule in a css file shipped by the variant (see files_add, e.g.
// css/variant.css with src: url('../files/fonts/my-custom-font.woff2')).
// data-font-package stays "websafe": LimeSurvey only knows the core font packages
// (application/config/fonts.php), and "websafe" is the neutral one, so no missing
// package is requested. The real font is loaded by the variant's own css.
if (!empty($definition['fontOptions'])) {
$optgroup = $xpath->query('//options/font/dropdownoptions/optgroup[@label="Custom (this theme)"]')->item(0);
if ($optgroup === null) {
fwrite(STDERR, "No <optgroup label=\"Custom (this theme)\"> found in the font dropdown of the mother config.xml\n");
exit(1);
}
foreach ((array) $definition['fontOptions'] as $font) {
if (empty($font['value']) || empty($font['label'])) {
fwrite(STDERR, "Each entry in 'fontOptions' needs 'value' and 'label'\n");
exit(1);
}
$value = preg_replace('/[^a-z0-9_]/i', '_', (string) $font['value']);
$option = $doc->createElement('option');
$option->setAttribute('class', 'font-' . $value);
$option->setAttribute('value', $value);
$option->setAttribute('data-font-package', 'websafe');
$option->appendChild($doc->createTextNode((string) $font['label']));
$optgroup->appendChild($option);
}
}
// --- options: replace only the house-style values listed in the json ---
if (!empty($definition['options']) && !is_array($definition['options'])) {
fwrite(STDERR, "'options' in $definitionFile must be an object of optionName => value\n");
exit(1);
}
$optionsNode = $xpath->query('//options')->item(0);
if ($optionsNode === null) {
fwrite(STDERR, "No <options> section found in mother config\n");
exit(1);
}
foreach (($definition['options'] ?? []) as $key => $value) {
$matches = $xpath->query('//options/' . $key);
if ($matches->length === 0) {
fwrite(STDERR, "Option '$key' from $definitionFile does not exist in the mother config.xml.\n");
fwrite(STDERR, "Remove it from the json or rename it there; the mother theme changed.\n");
exit(1);
}
$option = $matches->item(0);
// Replace only the text value, keep child elements (e.g. <dropdownoptions> of the font option)
foreach (iterator_to_array($option->childNodes) as $child) {
if ($child instanceof DOMText) {
$option->removeChild($child);
}
}
$option->insertBefore($doc->createTextNode((string) $value), $option->firstChild);
}
// --- write the variant config ---
$variantDir = $themesDir . DIRECTORY_SEPARATOR . $variantName;
if (!is_dir($variantDir) && !mkdir($variantDir, 0775, true)) {
fwrite(STDERR, "Could not create directory: $variantDir\n");
exit(1);
}
if (!is_dir($variantDir . DIRECTORY_SEPARATOR . 'files')) {
mkdir($variantDir . DIRECTORY_SEPARATOR . 'files', 0775, true);
}
$out = $variantDir . DIRECTORY_SEPARATOR . 'config.xml';
$doc->save($out);
// --- copy the variant's own assets (fonts, css, images) from the definitions dir ---
// Standard layout in the private variants repo: <definitionsDir>/<variantName>/
// with e.g. files/fonts/*.woff2, files/*.png, css/variant.css. Everything in that
// folder is copied into the generated theme, so a client-specific font or css is
// part of the variant by default (no manual copying needed).
$variantAssets = rtrim($definitionsDir, '/\\') . DIRECTORY_SEPARATOR . $variantName;
if (is_dir($variantAssets)) {
copyDirRecursive($variantAssets, $variantDir);
echo "Copied variant assets: $variantAssets -> $variantDir\n";
}
echo "Variant '$variantName' built: $out\n";
echo 'Options overridden: ' . (empty($definition['options']) ? '(none)' : implode(', ', array_keys($definition['options']))) . "\n";
echo "Remember: upload the folder to upload/themes/survey/ and reset the theme in LimeSurvey.\n";