php-cooper-config

Config
in package

FinalYes

The application's configuration: a CASC document loaded with Cooper, once, at startup, and read through this class afterwards -- the PHP counterpart of the Elixir `cooper_config` and the Praxis `cooper_prx`.

Eager only

// public/index.php, bin/console, a worker's entry point -- first thing
JOetjen\CooperConfig\Config::load();

// anywhere afterwards
$port = Config::get('http.port', 8080);

Configuration arrives; it is not asked for. load() reads the whole document, resolves it, converts it (see Convert), and stores it for the process. Nothing is ever loaded on first access: reading before load() ran is a NotLoadedError saying where the call goes. A document that does not load stops the program at its first line, with the reason, instead of at whichever request first reads a broken setting -- and a configuration that is never half there is one no code has to defend against.

PHP being shared-nothing, "once" is once per request for PHP-FPM, and once per process for a long-running worker. The compiled cache (see CompiledCache, on by default) is what makes per-request loading cheap.

Options

  • path (string) -- the document; relative to root. Default config/config.casc. A missing default document loads an empty configuration (a project with nothing to configure yet); a missing path given explicitly is a ConfigError.
  • root (string, an existing directory) -- the project root. Default: the Composer root package's directory (ProjectRoot).
  • compiledCache (bool|string, default true) -- false turns the compiled cache off, a string is the directory to keep it in instead of <root>/var/cache/cooper-config.
  • Cooper's own load options, passed through: env, dotenv, dotenvEnv, dotenvFiles, dotenvDir, dotenvOverride, resolvers, tags, importSchemes, modules, cache (see JOetjen\Cooper\Cooper). modules also resolves a cooper-secrets class name.

An unknown option is an \InvalidArgumentException listing the supported ones. .env files are Cooper's to find: it reads them from the project root (the Composer root package's directory) wherever the process started -- public/, for a web request -- or from dotenvDir. Nothing here changes the working directory.

Reading

A path is a dotted string ('database.host') or a list of segments (['hosts', 'example.com'], for a key holding a dot). An empty path or segment is an \InvalidArgumentException.

Table of Contents

Constants

DEFAULT_PATH  : mixed = 'config/config.casc'
The document's default location, relative to the project root.

Properties

$config  : array<string|int, mixed>|null
$report  : LoadReport|null

Methods

all()  : array<string|int, mixed>
The whole configuration.
get()  : mixed
The value at `$path`, or `$default` when nothing is there. A present `nil` is a value, not an absence.
has()  : bool
Whether anything -- `nil` included -- is at `$path`.
isLoaded()  : bool
Whether `load()` has stored a configuration.
load()  : void
Loads the configuration and stores it for this process, replacing whatever an earlier call stored. Call it once, at startup.
report()  : LoadReport
What the last successful `load()` did -- which document, and whether the compiled cache served or stored it.
require()  : mixed
The value at `$path`, which must be there.
unload()  : void
Forgets the configuration, so the next read is a `NotLoadedError` until `load()` runs again. For tests, and for a long-running worker that wants a clean slate before reloading.
__construct()  : mixed
absolute()  : string
loadDocument()  : LoadReport}
lookup()  : array{0: bool, 1: mixed}
segments()  : array<int, string|int>
`$path` as segments. Typed loosely on purpose: a caller's "list" may arrive with keys (`array_filter()`'s output), and only the order of its values matters.

Constants

DEFAULT_PATH

The document's default location, relative to the project root.

public mixed DEFAULT_PATH = 'config/config.casc'

Properties

$config

private static array<string|int, mixed>|null $config = null

Methods

all()

The whole configuration.

public static all() : array<string|int, mixed>
Tags
throws
NotLoadedError

when load() has not run

Return values
array<string|int, mixed> —

every top-level key and what it holds

get()

The value at `$path`, or `$default` when nothing is there. A present `nil` is a value, not an absence.

public static get(string|array<int, string|int> $path[, mixed $default = null ]) : mixed
Parameters
$path : string|array<int, string|int>

a dotted path or a list of segments

$default : mixed = null

what to return when $path leads nowhere

Tags
throws
NotLoadedError

when load() has not run

InvalidArgumentException

on an empty path or segment

Return values
mixed —

the value, or $default

has()

Whether anything -- `nil` included -- is at `$path`.

public static has(string|array<int, string|int> $path) : bool
Parameters
$path : string|array<int, string|int>

a dotted path or a list of segments

Tags
throws
NotLoadedError

when load() has not run

InvalidArgumentException

on an empty path or segment

Return values
bool —

whether $path leads to a value

isLoaded()

Whether `load()` has stored a configuration.

public static isLoaded() : bool
Return values
bool —

true once a load succeeded, until unload()

load()

Loads the configuration and stores it for this process, replacing whatever an earlier call stored. Call it once, at startup.

public static load([array<string, mixed> $options = [] ]) : void
Parameters
$options : array<string, mixed> = []

see the class documentation

Tags
throws
ConfigError

when the document is missing (an explicit path), does not load, or cannot be converted; nothing is stored

InvalidArgumentException

on an unknown or mistyped option

report()

What the last successful `load()` did -- which document, and whether the compiled cache served or stored it.

public static report() : LoadReport
Tags
throws
NotLoadedError

when load() has not run

Return values
LoadReport —

the report

require()

The value at `$path`, which must be there.

public static require(string|array<int, string|int> $path) : mixed
Parameters
$path : string|array<int, string|int>

a dotted path or a list of segments

Tags
throws
MissingKeyError

when nothing is at $path, naming it

NotLoadedError

when load() has not run

InvalidArgumentException

on an empty path or segment

Return values
mixed —

the value

unload()

Forgets the configuration, so the next read is a `NotLoadedError` until `load()` runs again. For tests, and for a long-running worker that wants a clean slate before reloading.

public static unload() : void

__construct()

private __construct() : mixed

absolute()

private static absolute(string $path, string $root) : string
Parameters
$path : string
$root : string
Return values
string

loadDocument()

private static loadDocument(string $file, string $root, Options $opts) : LoadReport}
Parameters
$file : string
$root : string
$opts : Options
Tags
throws
ConfigError
Return values
LoadReport}

lookup()

private static lookup(string|array<int, string|int> $path) : array{0: bool, 1: mixed}
Parameters
$path : string|array<int, string|int>
Return values
array{0: bool, 1: mixed}

segments()

`$path` as segments. Typed loosely on purpose: a caller's "list" may arrive with keys (`array_filter()`'s output), and only the order of its values matters.

private static segments(string|array<string|int, string|int> $path) : array<int, string|int>
Parameters
$path : string|array<string|int, string|int>
Return values
array<int, string|int>
On this page

Search results