Configuration

Basics

Configs allow you to store changeable values that power your application. Unlike environment variables, they do not typically change between environments. Configurations must implement IConfiguration, which provides the following methods:

$config->getArray('foo');

$config->getBool('foo');

$config->getFloat('foo');

$config->getInt('foo');

$config->getString('foo');

$config->getValue('foo');

$config->tryGetArray('foo', $value);

$config->tryGetBool('foo', $value);

$config->tryGetFloat('foo', $value);

$config->tryGetInt('foo', $value);

$config->tryGetString('foo', $value);

$config->tryGetValue('foo', $value);

Reading PHP Files

Let's say you have a PHP config array that looks like this:

return [
    'api' => [
        'supportedLanguages' => ['en', 'es']
    ]
];

You can load this PHP file into a configuration object:

use Aphiria\Configuration\PhpConfigurationFileReader;

$config = (new PhpConfigurationFileReader)->readConfiguration('config.php');

Grab the supported languages by using . as a delimiter for nested sections:

$supportedLanguages = $config->getArray('api.supportedLanguages');

Note: Avoid using periods as keys in your configs. If you must, you can change the delimiter character (eg to :) by passing it in as a second parameter to readConfiguration().

Reading JSON Files

Similarly, you can read JSON config files.

use Aphiria\Configuration\JsonConfigurationFileReader;

$config = (new JsonConfigurationFileReader)->readConfiguration('config.json');

Custom File Readers

You can create your own custom file reader. Let's look at an example that reads from YAML files:

use Aphiria\Configuration\HashTableConfiguration;
use Aphiria\Configuration\IConfiguration;
use Aphiria\Configuration\IConfigurationFileReader;
use Aphiria\Configuration\InvalidConfigurationFileException;
use Symfony\Component\Yaml\Yaml;

class YamlConfigurationFileReader implements IConfigurationFileReader
{
    public function readConfiguration(string $path, string $pathDelimiter = '.'): IConfiguration
    {
        if (!file_exists($path)) {
            throw new InvalidConfigurationFileException("$path does not exist");
        }

        $hashTable = Yaml::parseFile($path);

        if (!\is_array($hashTable)) {
            throw new InvalidConfigurationFileException("Configuration in $path must be an array");
        }

        return new HashTableConfiguration($hashTable, $pathDelimiter);
    }
}

Global Configuration

GlobalConfiguration is a static class that can access values from multiple sources registered via GlobalConfiguration::addConfigurationSource(). It is the most convenient way to read configuration values from places like binders. Let's look at its methods:

use Aphiria\Configuration\GlobalConfiguration;

GlobalConfiguration::getArray('foo');

GlobalConfiguration::getBool('foo');

GlobalConfiguration::getFloat('foo');

GlobalConfiguration::getInt('foo');

GlobalConfiguration::getString('foo');

GlobalConfiguration::getValue('foo');

GlobalConfiguration::tryGetArray('foo', $value);

GlobalConfiguration::tryGetBool('foo', $value);

GlobalConfiguration::tryGetFloat('foo', $value);

GlobalConfiguration::tryGetInt('foo', $value);

GlobalConfiguration::tryGetString('foo', $value);

GlobalConfiguration::tryGetValue('foo', $value);

These methods mimic the IConfiguration interface, but are static. Like IConfiguration, you can use . as a delimiter between sections. If you have 2 configuration sources registered, GlobalConfiguration will attempt to find the path in the first registered source, and, if it's not found, the second source. If no value is found, the get*() methods will throw a MissingConfigurationValueException, and the tryGet*() methods will return false.

Building The Global Configuration

GlobalConfigurationBuilder simplifies configuring different sources and building your global configuration. In this example, we're loading from a PHP file, a JSON file, and from environment variables:

use Aphiria\Configuration\GlobalConfigurationBuilder;

$globalConfigurationBuilder = new GlobalConfigurationBuilder();
$globalConfigurationBuilder->withPhpFileConfigurationSource('config.php')
    ->withJsonFileConfigurationSource('config.json')
    ->withEnvironmentVariables()
    ->build();

Note: The reading of files and environment variables is deferred until build() is called.

After build() is called, you can start accessing GlobalConfiguration.