Repository navigation
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.
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.
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.
#[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.
#[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 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 maskedAn unknown key throws UnknownSetting, with near matches in the message.
⚠️ Never writeuse Blink\Config;in a file that also readsCONFIG::. PHP matches class aliases without regard to case, so the import captures everyCONFIG::in the file and hands it to the registry. Write\Blink\Configin full there.
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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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 |
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 |