Site settings and theme switch

What this covers

Scriptor's site-wide configuration: the title in the browser tab, the language the editor speaks, which theme renders the frontend, the admin path, cache duration, log level, and which plugins are enabled. None of these live in an editor form. The Settings sidebar entry is a read-only landing page that points at the config files; this topic covers the keys you actually edit.

Walkthrough

Step 1: Find the two config files

Scriptor reads its configuration from two files under data/settings/:

  • scriptor-config.php: the defaults shipped with Scriptor. Open it to see every available setting documented in PHPDoc comments alongside its default value. Do not edit this file directly: a future Scriptor upgrade will overwrite it.
  • custom.scriptor-config.php: the override file the Scriptor install ships as _custom.scriptor-config.php. Rename it (drop the leading underscore) to start using it. Anything you put here merges over the defaults; an upgrade leaves it alone.

The Settings sidebar entry (/editor/settings/) is an informational page that names both files and reminds you about the rename.

Step 2: Edit the override file, not the defaults

Open data/settings/custom.scriptor-config.php in your editor. The shipped scaffold looks roughly like:

<?php
return [
    // Override defaults from scriptor-config.php here.
];

Add the keys you want to change. The most common ones are listed below; for the complete list, read the PHPDoc in scriptor-config.php.

Step 3: Change the keys you need

The keys that operators change most often:

site_name: the site title

'site_name' => 'Acme Inc.',

Used by themes for the browser tab, the <title> tag, the default Open Graph site name. Theme-dependent in exactly how it shows up.

lang: editor language

'lang' => 'de_DE',  // default 'en_US'

Sets the language the editor UI is rendered in. Available languages live under editor/lang/; the directory listing is the authoritative list. Adding a new language is a developer task (drop a new xx_YY.php next to the existing ones and translate the keys).

theme_path: the active theme

'theme_path' => 'mytheme/',

The directory under themes/ that contains the active theme's template.php and friends. The trailing slash is required. Changing this is the one-line theme switch: edit the file, reload, the frontend renders through the new theme.

For installing a new theme, see docs/themes.md in the Scriptor repo.

admin_path: the editor URL prefix

'admin_path' => 'admin/',  // default 'editor/'

What URL the editor lives at. The default /editor/ is fine for most sites; some operators rename it for security-through- obscurity (a bot that scans for /wp-admin or /editor will not guess /secret-back-door). The trailing slash is required.

markup_cache_time: frontend cache duration

'markup_cache_time' => 3600,  // seconds; default is a very large value

How long the rendered page HTML is cached. The default is several years (cache busts on page save). Setting this lower shortens the cache window if your theme generates content that changes outside of page edits.

logging.level: log verbosity

'logging' => [
    'level' => 'debug',  // default 'info'
],

Levels follow PSR-3: debug, info, notice, warning, error, critical, alert, emergency. Logs land in data/logs/; see Logs and troubleshooting for where to look first.

plugins.disabled: disable a plugin without uninstalling

'plugins' => [
    'disabled' => [
        'bigins\\ScriptorMarkdownPages\\Plugin',
    ],
],

Each entry is a plugin's fully-qualified class name (the same string the Plugins module shows under "Plugin"). A disabled plugin stays in vendor/; the editor just skips its register() hook. Useful for bisecting a suspected plugin bug without touching Composer.

Step 4: Save the override file and reload

Save custom.scriptor-config.php. The next request reads the new values; no restart is needed for most keys. Two exceptions:

  • PHP OPcache (in production): if you have OPcache enabled with validate_timestamps=0, you need to reset OPcache for the new config to take effect. php -r "opcache_reset();" or restart PHP-FPM.
  • Docker: bind-mounted config files reload normally; baked-in config files require a container rebuild. The Docker container layout in the Scriptor docs explains which is which.

What to check after

  • site_name change: the new title appears in the browser tab and in the <title> HTML.
  • lang change: reload the editor; the sidebar labels and buttons are in the new language.
  • theme_path change: reload the frontend; the page renders through the new theme (different chrome, possibly different CSS).
  • admin_path change: the old URL returns 404; the new URL shows the login form.
  • plugins.disabled change: reload the editor; the plugin no longer appears in the sidebar (if it contributed any items), and the Plugins module's row for that plugin moves to the "Disabled" section.

Troubleshooting

I changed site_name but the browser tab still shows the old one

Hard-reload the browser (Ctrl-Shift-R / Cmd-Shift-R). The tab title comes from the rendered HTML, which is cached by markup_cache_time. If you want the change to take effect immediately, save a page in the editor to bust the cache.

lang change has no effect

Either the language file does not exist, or the language code is wrong. Look in editor/lang/ for a file matching the value you set (e.g. de_DE.php for 'lang' => 'de_DE'). The code is case-sensitive.

Site is broken after a theme switch

The new theme is missing required files or has a syntax error. Switch back to the working theme by changing theme_path back to its previous value. Then look at the new theme's files: themes/<name>/template.php is required; themes/<name>/page.php is the typical page template; check the new theme's README for what else it needs.

My override is ignored

Three usual causes:

  1. The file is still named _custom.scriptor-config.php. Rename it (drop the leading underscore). Scriptor does not load the underscored scaffold.
  2. The file does not return an array. The first non-comment line has to be return [...];. A file without return yields null and the override is empty.
  3. Syntax error. Open the file with php -l data/settings/custom.scriptor-config.php; it reports the line. Fix and retry.

See also