Last update: 10 Apr 2023
Load configuration files the easy way. This configuration loader supports PHP
, INI
, JSON
, XML
and
YAML
file extensions.
There are several ways to load configuration files. We will take a closer look at these in the following.
The easiest way to load configuration files, is by direct instantiation:
new Zaphyr\Config\Config(['/config/path/file.yml']);
load()
methodAnother way is to include configuration files using the load()
method:
$config = new Zaphyr\Config\Config();
$config->load(['/config/path/file.yml']);
Warning:
Please do not include untrusted configuration files with
php
extension. It could contain and execute malicious code!
It is also possible to load complete configuration file directories. This can be done in two ways.
The easiest way to do this, is to pass the configuration directory path to the constructor:
$config = new Zaphyr\Config\Config(['./config/path']);
You can also use the load()
method to load configuration file directories:
$config = new Zaphyr\Config\Config();
$config->load(['./config/path']);
Note:
Files are parsed and loaded depending on the file extension. When loading a directory, the path is
glob
ed and files are loaded in by name alphabetically.
Limitations:
It is not possible to load nested configuration file directories!
Getting configuration values can be done via the get()
method.
Let's say you have an app.yml
configuration file in your /config/path
directory
and the contents of your file looks like this:
# /config/path/app.yml
name: "My awesome app"
Now you load the configuration file as described above and use the get()
method to get the name of your application:
$config = new Zaphyr\Config\Config(['/config/path']);
$config->get('app.name'); // My awesome app
As you can see, the name of the configuration file, in your example app.yml
, acts as the "namespace"
for calling the configuration value.
The get()
method also provides the ability to pass default values if a variable is not present in your
configuration files. To do this, simply pass a second parameter to the get()
method:
$config->get('app.version', '1.0.0'); // 1.0.0
If a configuration value could not be found, the get()
method automatically returns null
.
If you want to know if a configuration value exists, just use the has()
method:
$config->has('app.name'); // true
You might also want to get all available configuration values as an array. This is possible with the
toArray()
method:
$config->toArray(); // ['app' => 'name']
You might want to store critical data, such as your database credentials, in your configuration files.
It would be fatal to write this directly into the configuration file and then commit it to your Git instance, for
example.
So you put your critical credentials in a .env
file and exclude them from your git commits. This repository now
offers you a way to access stored env
values within your configuration file.
Let's imagine a scenario where your database credentials are stored in a .env
file somewhere in your project:
DB_USER=user
DB_PASS=secret
Now you want to access the env
values in your database.yml
inside your /config/path
directory. This works as
follows:
# /config/path/database.yml
mysql:
user: '%env:DB_USER%'
password: '%env:DB_PASS%'
With the indicators %
and the keyword env:
the configuration loader knows to use a replacer.
In this case the EnvReplacer
. The corresponding replacer now takes over the resolution of your env
value for you.
You may also want to use your own replacers in your configuration files. This is also possible and is described below.
First you should create your own replacer class, which implements the ReplacerInterface
and includes the replace
method:
class MySuperCustomReplacer implements Zaphyr\Config\Contracts\ReplacerInterface
{
/**
* {@inheritdoc}
*/
public function replace(string $value): string
{
// Your custom replacer logic
}
}
Now you need to pass your previously created replacer in the constructor of your Config
instance:
$replacers = ['custom' => MySuperCustomReplacer::class];
$config = new Zaphyr\Config\Config(['/config/paths'], null, $replacers);
Alternatively, you can also pass your own replacer to the addReplacer()
method:
$config->addReplacer('custom', MySuperCustomReplacer::class);
You can now use your custom replacer in your configuration files:
config: '%custom:value%'
Note:
New replacer instances must always be added before the first use of the
load()
method. Otherwise, theload()
method throws an error because it does not yet know the new replacer!
Even if this repository is already equipped with a lot of configurations file extension readers, it is still possible to create your custom configuration readers. To do this, proceed as follows.
First you should create your own reader instance, which implements the ReaderInterface
and contains a read
method:
class MySuperCustomReader implements Zaphyr\Config\Contracts\ReaderInterface
{
/**
* {@inheritdoc}
*/
public function read(): array
{
// Your custom reader logic
}
}
Secondly, you register your custom reader in the config class:
$readers = ['custom' => MySuperCustomReader::class];
$config = new Zaphyr\Config\Config(['/config/paths'], $readers);
Alternatively, you can also use the addReader()
method:
$config->addReader('custom', MySuperCustomReader::class);
Now you can use configuration files with your own file extension.
Note:
New reader instances must always be added before the first use of the
load()
method. Otherwise, theload()
method throws an error because it does not yet know the new reader!