Configuration

The config layers, and every key the framework reads.

Updated

Layers

Config merges in this order, later wins:

  1. phlat/config.jsonc, the framework's defaults, with every key explained in comments
  2. site/config.jsonc (or site/config.json), your site
  3. site/data/env.json, this deployment's secrets and overrides (gitignored)
  4. site/data/env.cli.json, merged on top for CLI runs only (gitignored)

Read a key with dot notation, in code or in a template:

$app->config->get('images.quality');
$app->config->get('analytics', []);

site/config.jsonc can hold any key your site needs, such as analytics or themes. An addon keeps its own settings under its addons.{id} entry and reads them with $app->addonConfig('phlat/dash', 'key'), or {addon('phlat/dash', 'key')} in Latte.

Keys

Key Default Meaning
url none The site origin, such as https://example.com. When set, only its host answers: a request for any other host (www, an IP, a forged Host header) is redirected to it. An https url also redirects plain http requests and sends Strict-Transport-Security, so set it in production $app->origin() returns it for absolute URLs, and the OIDC addon registers its callbacks on it. Leave it out in development, or set it in env.json per deployment
date.timezone UTC The site's time zone for display. Stored timestamps are always UTC
cache on Set false to turn off every cache: fragments, {cache} regions, kept pages and the headers that let a browser keep a response. Watch the caches in Clockwork's Cache panel. See Caching
debug false Show exception details on error pages, recompile templates when they change and turn on Clockwork
auth.password false Allow sign-in with a username and password. Off, the login form and profile password form refuse them, so a site with no other sign-in method cannot be entered. Set it to true when users have passwords
auth.login /@users/login Where a signed-out visitor is sent when a page needs a permission
app.key none The site's encryption key, made by phlat key:generate and kept in env.json. Values the CMS encrypts, such as one-time code secrets, can't be read without it
pagination.limit 20 Children per page for paginate(). A view overrides it under its own pagination key. 0 means no limit
session.expire 86400 Seconds of inactivity before a session ends. 0 leaves it to PHP. Activity is recorded at most once a minute
fieldtype.code.theme one-dark-pro The Phiki theme code fields highlight with. A field's theme option or ->highlight($theme) overrides it per render. Highlighted output is cached by its code, language and theme
images.quality 80 Default encode quality, overridden by quality=
images.max 0 Scale an uploaded image down so neither side passes this many pixels. 0 keeps uploads as they are, and animated GIFs are never resized. A view overrides it under its own images key
images.font none The font file a draw() text layer uses when it names none, as {uuid}:{name}
images.presets none Named option strings for src(). See Images
images.drawings none Named draw layers for draw() and drawLayers(). See Images
options.{key} none A visitor option: a list of allowed string values, the first the default. See Routing
files.cache public, max-age=3600 Cache-Control for public files
files.cache_max_bytes 5000000 A file larger than this is sent no-store
files.allowed common images, pdf, mp4, webm, mp3, zip Extensions an upload may have
files.max_bytes 0 The largest upload in bytes. 0 leaves it to the server's own limit
uuid.length 8 Length of a new uuid, from 8 to 16
date.format F j, Y The default date format, in PHP date() syntax
git.message {objecttype}/{type}:{action}({path}) History's commit message. See History
email.default none The DSN $app->email() sends through, such as smtp://user:pass@host:587. Without it $app->email() throws. email.{name} adds more transports
addons.source none The git base phlat addons:install creator/name resolves against, such as ssh://[email protected]
addons.{id} see the file enabled and the addon's own settings. See Addons

Secrets belong in site/data/env.json, which stays out of git and survives redeploys with the rest of site/data/.