Skip to content

Configuration

Belikhun edited this page Sep 15, 2026 · 3 revisions

⚙️ Configuration

A setting is a typed static property on a config class. That is what an application reads, and it stays the shortest way to read one:

CONFIG::$DB_HOST;

Around those properties is a registry that knows what each setting is for, which environment variable fills it, and which ones must never be printed. That is what lets a module ship settings of its own, config:list describe them, and the environment fill them without guessing at names.

Declaring settings

config.define.php declares the application's class and config.php sets the values. Both live in the project root:

// config.define.php
class CONFIG extends CoreConfig {
	#[FromEnv("BILLING_ENDPOINT")]
	public static string $BILLING_ENDPOINT = "https://billing.example.com";
}
// config.php
CONFIG::$APP_NAME = "My Site";
CONFIG::$DEBUG = false;
CONFIG::$DB_DRIVER = "MySQLi";

Commit config.define.php. config.php is in the default .gitignore, and secrets belong in the environment rather than in either.

A module ships its own class instead of adding to the application's, and lists it in config():

namespace App\Billing;

use Blink\Attribute\FromEnv;
use Blink\Attribute\Secret;

class BillingConfig {
	const PREFIX = "billing";

	#[FromEnv("BILLING_ENDPOINT")]
	public static string $ENDPOINT = "https://billing.example.com";

	#[FromEnv("BILLING_KEY")]
	#[Secret]
	public static string $API_KEY = "";

	/**
	 * Seconds to wait on the billing API before giving up.
	 */
	#[FromEnv("BILLING_TIMEOUT")]
	public static int $TIMEOUT = 10;
}
class BillingModule extends Module {
	public function config(): array {
		return array( BillingConfig::class );
	}
}

Read it the same way as blink's own:

BillingConfig::$ENDPOINT;

const PREFIX is what the setting is addressed by elsewhere: billing.endpoint. Without one, the class name supplies it, so BillingConfig would become billing anyway. Blink's own settings are blink.

Module config classes are registered before any module is defined, so a setting is readable from the first line of define() onwards.

The environment

Blink reads the process environment, then layers an env file from the project root on top. CONFIG::$ENV names the file: default reads .env, anything else reads {name}.env. That one setting comes from the process environment as APP_ENV, since the file cannot say which file to read.

APP_DEBUG=false
DB_HOST=db.internal
DB_PORT=3306
DB_PASS=secret
TERRA_PATHS=/srv/shared/layers,/srv/app/layers

A setting is only filled from the environment when it carries #[FromEnv], and the attribute names the variable:

#[FromEnv("DB_HOST")]
public static string $DB_HOST = "127.0.0.1";

Naming the variable rather than matching on the property is deliberate. Nearly every Linux shell exports LANG as something like en_US.UTF-8, and a framework that matched by name alone would hand that to CONFIG::$LANG on every deployment. Blink binds the settings that plausibly collide to prefixed names instead: APP_LANG, APP_DEBUG, APP_TIMEZONE, APP_NAME, APP_ENV.

The value is converted to the property's declared type, so text from an env file fills an int or a bool correctly:

Declared Accepts
string anything scalar
int a whole number
float any number
bool 1, true, yes, on, and their opposites; empty is false
array JSON, or a comma-separated list

A value the type cannot take is reported against the setting that rejected it, naming the variable it came from, rather than becoming a TypeError several frames away:

Blink\Config\Exception\InvalidSettingValue: Setting blink.db_port needs a whole number.
  Environment variable DB_PORT carries not-a-port.

Precedence is defaults, then config.php, then the environment. config:list shows which one each value came from.

Secrets

#[FromEnv("DB_PASS")]
#[Secret]
public static string $DB_PASS = "";

A secret works exactly as it did, and its value is masked everywhere blink displays configuration: config:list, the error page's Config and Environments contexts, and anything else reading a setting for display. An error report is reachable by anyone holding its id, so this matters more than it looks.

Environment variables blink knows nothing about are masked by name: anything containing PASS, SECRET, TOKEN, CREDENTIAL, PRIVATE, SALT or KEY.

Directories

#[PathProperty]
public static string $FILES_ROOT = DATA_ROOT . "/files";

The directory is created when the section is registered, so nothing later has to check, and config:check reports it when it cannot be written to.

Reading by name

Reading the property is shorter and the one to prefer. Config is for when the name is not known until runtime: a console argument, a listing, a template.

use Blink\Config;

Config::get("billing.endpoint");
Config::get("billing.endpoint", $fallback);
Config::set("billing.timeout", 30);

Config::has("billing.endpoint");
Config::setting("billing.endpoint") -> description;
Config::section("billing") -> settings();
Config::display();              // every setting, secrets masked

An unknown key throws UnknownSetting, with near matches in the message.

⚠️ Never write use Blink\Config; in a file that also reads CONFIG::. PHP matches class aliases without regard to case, so the import captures every CONFIG:: in the file and hands it to the registry. Write \Blink\Config in full there.

From the console

php core/blink config:list
php core/blink config:list billing
php core/blink config:list --changed
php core/blink config:list --env --describe
php core/blink config:list --reveal
php core/blink config:check

config:list shows every setting with its type, value, where the value came from and which variable fills it. --changed narrows it to what differs from blink's defaults, which is usually the interesting part of a deployment.

config:check separates what is wrong from what is only worth mentioning. A problem is a directory blink cannot write to, and it will fail the first time something needs it; config:check exits 1 when it finds one. A note is an empty secret, which may simply be one this deployment has no use for — a SQLite site has no DB_PASS to set — so notes never fail the command. --quiet leaves them out.

Worth running after a deploy.

Blink's settings

Application

Setting Default Env Meaning
$APP_NAME "My Web App" APP_NAME Shown wherever the site names itself
$APP_VERSION "1.0.0" APP_VERSION Bump on deploy; feeds the cache version
$ENV "default" APP_ENV¹ Which env file is read
$DEBUG true APP_DEBUG Error pages carry the trace and context
$MODULES [] The application's modules, in boot order
$TIMEZONE "UTC" APP_TIMEZONE The timezone PHP runs in
$LANG "en" APP_LANG The default language
$W_MODE true The sticker on the error page

¹ From the process environment only.

Database

Setting Default Env
$DB_DRIVER "MySQLi" DB_DRIVER
$DB_HOST "127.0.0.1" DB_HOST
$DB_PORT 0 DB_PORT
$DB_USER "" DB_USER
$DB_PASS "" DB_PASS 🔒
$DB_NAME "" DB_NAME
$DB_PATH BASE_PATH . "/db" DB_PATH

$DB_PORT at 0 leaves the port to the driver.

Paths

Setting Default
$ROUTES_ROOT BASE_PATH . "/routes"
$TEMPLATES_ROOT BASE_PATH . "/templates"
$FILES_ROOT DATA_ROOT . "/files"
$CACHE_ROOT DATA_ROOT . "/caches"
$ERRORS_ROOT DATA_ROOT . "/errors"
$AUTOLOAD [ "App\\" => BASE_PATH . "/classes" ]
$INCLUDES [ BASE_PATH . "/includes", BASE_PATH . "/classes" ]
$LANGS blink's lang, then the application's

See Autoload for the last two.

Files

Setting Default Env Meaning
$FILE_STORE "local" FILE_STORE Which store holds content
$FILE_HASH "sha256" What content is addressed by
$FILE_SHARD_DEPTH 2 Directory levels the local store nests under
$FILE_PERMISSIONS 0644 Mode files are created with
$IMAGE_ALLOW png, jpg, webp, gif, tif, jpeg, bmp Extensions UploadedFile::image() accepts
$IMAGE_SIZE 6291456 Largest accepted image, in bytes

See Files.

Sessions

Setting Default Env
$SESSION_LIFETIME 86400 SESSION_LIFETIME
$TOKEN_LIFETIME 86400 TOKEN_LIFETIME
$REVERSE_PROXY false REVERSE_PROXY

Turn $REVERSE_PROXY on only behind a proxy you control: it makes blink trust X-Forwarded-For, which anyone can send.

Subsystems

Setting Default Env See
$TERRA_AUTO_APPLY true TERRA_AUTO_APPLY Terra
$TERRA_WAIT 10 TERRA_WAIT
$TERRA_PATHS [] TERRA_PATHS
$TICKER_STORE "database" TICKER_STORE Ticker
$TICKER_QUEUE "default" TICKER_QUEUE
$TICKER_RETRY_AFTER 90 TICKER_RETRY_AFTER
$LIGHTRAIL_QUEUE "lightrail" LIGHTRAIL_QUEUE Lightrail
$LIGHTRAIL_TRAIL true LIGHTRAIL_TRAIL
$TRACE_RETENTION_DAYS 365 TRACE_RETENTION_DAYS Trace
$TRACE_PURGE_BATCH 5000
$LOCK_STORE "database" LOCK_STORE Lock
$CLI_MEMORY_LIMIT "512M" CLI_MEMORY_LIMIT Console

Constants

Defined by setup.php before configuration is read, so they can be used in a default:

Constant Is
BASE_PATH The project root
CORE_ROOT Where blink itself lives
APP_ROOT The application root; the same as BASE_PATH
DATA_ROOT BASE_PATH . "/data"
VENDOR_ROOT BASE_PATH . "/vendor"
BLINK_IS_CLI Whether this is a console run

Clone this wiki locally