Wallogit.com
2017 © Pedro Peláez
A simple object with useful methods to easily access your configuration values.
, (*1)
This component provides a simple API to handle configuration parameters. It can handle different readers and writers to read from and write to any storage., (*2)
Currently supported readers and writers:, (*3)
To start using the configuration object, you only need to instantiate it. Default reader is file, which means it loads the configuration from a file by default. The default writer is also file, which means it will save the data to a file. You can, of course, set the reader and writer you want, as you'll see later., (*4)
In the following example, we set an array as the initial data of the config object, and start accessing its data through the API provided by our IronEdge\Component\Config\Config class. We use the DataTrait provided by our component ironedge/common-utils to expose some of the following methods:, (*5)
``` php <?php, (*6)
namespace Your\Namespace;, (*7)
use IronEdge\Component\Config\Config;, (*8)
// Create a config instance. You can set initial data and options // using its constructor., (*9)
$data = [ 'user' => [ 'username' => 'admin', 'groups' => [ 'primary' => 'administrator', 'secondary' => ['development'] ] ] ];, (*10)
$config = new Config($data);, (*11)
// Obtain the username. Returns: 'admin', (*12)
$config->get('user.username');, (*13)
// Obtain the primary group. Returns: 'administrator', (*14)
$config->get('user.groups.primary');, (*15)
// This attribute does not exist, so we return the default value used as the second argument: 'defaultProfile', (*16)
$config->get('user.profile.name', 'defaultProfile');, (*17)
// Returns true because this attribute exists, (*18)
$config->has('user.username');, (*19)
// Returns false because this attribute does not exist, (*20)
$config->has('user.profile.name');, (*21)
// Sets the missing attribute of the last example. Note that it creates any missing attribute, at any depth., (*22)
$config->set('user.profile.name', 'myProfile');, (*23)
// Obtain the newly created attribute. Returns: 'myProfile', (*24)
$config->get('user.profile.name');, (*25)
### Load Configuration Data from the Reader Following the last example, suppose you want to load data from an YML file with the following contents: ``` yml user: profile: name: newProfile createdAt: 2010-01-01 12:00:01 cacheDir: %root_path%/cache
To load this file, use the following code:, (*26)
``` php <?php, (*27)
// ... // Include here the code of the last examples // ..., (*28)
// Load the YML file, (*29)
$config->load(['file' => '/path/to/config.yml']);, (*30)
// Returns: 'newProfile', (*31)
$config->get('user.profile.name');, (*32)
// Returns: '2010-01-01 12:00:01', (*33)
$config->get('user.createdAt');, (*34)
// Returns 'administrator', (*35)
$config->get('user.groups.primary');, (*36)
The **load** method delegated the loading of the file **/path/to/config.yml** file to the **file** reader. This reader loaded the YML file, and then the config object did an **array_replace_recursive** using the current data, and the data loaded from the YML file. ### Replace Template Variables Did you notice the value of the parameter **cacheDir**, **%root_dir%/cache**? The config object allows to use template variables to be replace in all the string values found on the configuration data. By default, we don't provide any template variables, but you can set them with the **templateVariables** option as shown in the following example: ``` php <?php // ... // Include here the code of the last examples // ... // This returns '%root_dir%/cache' since we didn't configure // any template variables yet $config->get('cacheDir'); // Now we set the template variable $config->setOptions(['templateVariables' => ['%root_dir%' => '/my/root/dir']]); // Now, it will return '/my/root/dir/cache' $config->get('cacheDir');
As the default writer is file, if you call the save method, it will save the configuration data to a file:, (*37)
``` php <?php, (*38)
// ... // Include here the code of the last examples // ..., (*39)
// Save configuration data to file '/path/to/my_config.yml', (*40)
$config->save(['file' => '/path/to/my_config.yml']);, (*41)
### Additional Features These are additional features provided by this component. #### Load Data into a Specific Key Sometimes you want to load configuration data into a specific key instead of replacing the whole data array. You can do it using the following code:} ``` php <?php namespace Your\Namespace; use IronEdge\Component\Config\Config; $config = new Config( [ 'user' => [ 'username' => 'myUser' ] ] ); // Load profiles from file /path/to/profiles.yml // // Suppose this file has the following contents // // profiles: // - administrator // - development $config->load( ['file' => '/path/to/profiles.yml'], ['loadInKey' => 'user.profiles'] ); // This would return: ['administrator', 'development'] $config->get('user.profiles');
You can execute any of this operations using the following methods:, (*42)
``` php <?php, (*43)
namespace Your\Namespace;, (*44)
use IronEdge\Component\Config\Config;, (*45)
$config = new Config( [ 'user' => [ 'username' => 'admin', 'groups' => [ 'administrator' ] ] ] );, (*46)
// Internally it uses "array_merge". // Config data will end like: ['user' => 'myUser', 'groups' => ['myGroup']], (*47)
$config->merge(['user' => 'myUser', 'groups' => ['myGroup']]);, (*48)
// Internally it uses "array_merge_recursive". // Config data will end like: ['user' => 'myUser', 'groups' => ['myGroup', 'myOtherGroup']], (*49)
$config->mergeRecursive(['user' => 'myUser', 'groups' => ['myOtherGroup']]);, (*50)
// Internally it uses "array_replace". // Config data will end like: ['user' => 'myOtherUser', 'groups' => ['myGroup']], (*51)
$config->replace(['user' => 'myOtherUser', 'groups' => ['myGroup']]);, (*52)
// Internally it uses "array_replace_recursive". // Config data will end like: ['user' => 'myUser', 'groups' => ['myOtherGroup']], (*53)
$config->replaceRecursive(['user' => 'myUser', 'groups' => ['myOtherGroup']]);, (*54)
### Custom Reader and Writer You can define your own readers and writers in the following way: ``` php <?php namespace Your\Namespace; use IronEdge\Component\Config\Config; // This must implement IronEdge\Component\Config\Reader\ReaderInterface $myReader = new MyReader(); // This must implement IronEdge\Component\Config\Writer\WriterInterface $myWriter = new MyWriter(); $config = new Config( [], [ 'reader' => $myReader, 'writer' => $myWriter ] ); // Reader method **read** will receive values from **readerOptions** $config->load(['readerOptions' => ['myReaderOption' => 'myReaderOptionValue']]); // Writer method **writer** will receive values from **writerOptions** $config->save(['writerOptions' => ['myWriterOption' => 'myWriterOptionValue']]);
Of course, you can use any reader / writer combination you want. For instance, you could read the configuration from a file, but write it to a database., (*55)
A simple object with useful methods to easily access your configuration values.
MIT
config