Hiraeth uses Jsonified Ini Notation (JIN) for all configuration files and its .env. Without going into too much detail, these files use an INI structure with JSON-like values. The language is extremely similar to TOML, but does not attempt to be compatible or maintain feature parity. For example:
[middleware]
disabled = false
class = Acme\Middleware
Functions
JIN supports mapping functions for configuration values. These are useful to get information that requires some logic in order to generate or retrieve. Hiraeth registers three important functions that allow you to write more flexible configs.
The env() Function
Get environment variables value, including those set in your .env.
[config]
setting = env(VALUE)
With a default value if not found:
[config]
setting = env(VALUE, true)
The dir() Function
If you need to get an “application root” relative directory, you can use the dir() function. This is equivalent to $app->getDirectory() (See: Files and Directories).
[config]
directory = dir(storage/cache/acme)
Using the dir() function will always create the directory if it does not exist.
The file() Function
If you need to get an “application root” relative file, you can use the file() function. This is equivalent to $app->getFile() (See: Files and Directories).
[config]
file = file(storage/example.txt)
Using the file() function will not create the file if it does not exist.
Getting Configuration Information
A configuration collection is just an object containing information from a file somewhere in config. The collection “path” refers to the relative file path minus the .jin extension. For example, the collection path for config/common.jin is simply common.
To get specific configuration information you can use the $app->getConfig() method by passing it the path, the key to the setting, and a default value in the event that it’s not set. The following example shows how we might determine if an Acme\Middleware is disabled for the previous example JIN code:
$app->getConfig('middleware/acme', 'middleware.disabled', FALSE)
The “dot notation” for the second parameter allows you to access information nested at any depth of the collection, including retrieving from object / array values set in the configuration.
Default Values and Inferred Typing
When retrieving information from a specific collection, the default value will first and foremost be returned if:
- The path does not refer to a valid collection
- The the collection does not have a value set for the provided key
However, the default value is additionally used to infer and set the data type on any data retrieved. JIN supports typing natively, so this functionality is primarily used to convert scalar values to arrays at the time of retrieval or to typecast mixed values into booleans for simple checks.
For example, given the following config:
[config]
setting = value
Retrieving with $app->getConfig('path', 'config.value', []) will result in [value]. This will allow you to create settings that can be optionally scalar values or arrays and safely foreach over them:
foreach ($app->getConfig('path', 'config.value', []) as $value) {
...
}
Additionally, if the retrieved value is an array (natively or by inference) and the default value is an array, then any keys/values which exist in the default that don’t exist in the retrieved value will be added to the result.
For example, given the following config:
[config]
setting = {
"foo": "bar"
}
Retrieving with $app->getConfig('path', 'config.value', ['bar' => 'foo']) will result in:
[
'foo' => 'bar',
'bar' => 'foo'
]
Querying Information
In some cases you want to get a lot of similar configuration information across the entire set of collections. To perform this, you can specify a * as the first parameter and the $app->getconfig() method will return an array of values keyed by the collection path they’re found in.
$defaults = [
'class' => NULL,
'disabled' => FALSE,
'priority' => 50
];
foreach ($app->getConfig('*', 'middleware', $defaults) as $path => $collection) {
if (!$middleware['class'] || $middleware['disabled']) {
continue;
}
//
// do middleware things
//
}
Unlike when getting specific configuration information, querying information will only return values from collections where the key exists. That is, the default value will not be returned for collections which don’t have the value, but will still be used to infer data types and provide defaults within a retreived array.
Getting Environment Variables
Hiraeth, like many other popular frameworks, provides a .env file for setting environment specific data. Unlike other popular frameworks, the .env file also contains JIN. Although the source for the environment is JIN, because the environment cannot contain rich data types only simple key names and strings, the structure of the environment is flattened with the keys of nested information separated by an _ (underscore). Use arrays at your own risk!
To get an environment value, you can use the $app->getEnvironment() method:
$app->getEnvironment('CONFIG_DIR', 'config')
When accessing environment variables through $app->getEnvironment(), Hiraeth will perform the same default value and inferred typing as described above and will be accessing the data in its original data types.
You also access data using PHP’s built-in getenv() and the $_ENV superglobal. Though in the case of the former the data will only be available as a string.
Once you’ve got the basics down, you’ll probably want to modify your .env and get some basic error handling in place.