Settings Loader
, (*1)
The settings loader is a library that loads settings from several sources (currently only XML is supported)., (*2)
XML Loader
This loader loads the settings from an XML file with a given structure:, (*3)
``` xml
, (*4)
, (*5)
<country>Japan</country>
<s:settings>
<company>Nintendo</company>
</s:settings>
<s:settings>
<company>Sony</company>
</s:settings>
, (*6)
``` php
<?php
use \DomDocument;
use Superruzafa\Settings\Loader\XmlLoader;
$doc = new DomDocument();
$doc->load(__DIR__ . '/settings.xml');
$loader = new XmlLoader($doc);
$loader->load();
$settings = $loader->getSettings();
// $settings = array(
// array(
// 'country' => 'Japan',
// 'company' => 'Nintendo',
// ),
// array(
// 'country' => 'Japan',
// 'company' => 'Sony',
// )
// )
In essence you can create your own XML settings file following these steps:, (*7)
- Define in your XML a namespace pointing to
http://github.com/superruzafa/settings-loader
- Use the two reserved tags in that namespace for define settings entries:
<abstract> and <settings>
- The namespaceless tags will be used as key-value pairs and will build the settings entries.
<abstract> vs. <settings>
Both <abstract> and <settings> tags define a context (or change the previous one).
However, the <settings> takes the current context and creates a settings entry in the global settings list., (*8)
Summarizing, you should use <abstract> when you want to define a global context that would be overrided by concrete context using <settings>., (*9)
Inheritance
Both <abstract> and <settings> nodes inherit the values defined by its ancestors and could be combined for create large collections of settings easily.
These tags could be nested:, (*10)
``` xml, (*11)
...
, (*12)
<s:settings>
<s:abstract>
...
</s:abstract>
</s:settings>
<s:abstract>
<s:settings>
...
</s:settings>
, (*13)
### Elements vs. attributes
An ```<abstract>``` or a ```<setting>``` node are allowed to define their context using both elements and attributes. These two examples would create the same settings:
``` xml
<s:settings>
<language>PHP</language>
<purpose>Web and more</purpose>
</s:settings>
``` xml
, (*14)
``` xml
<s:settings language="PHP">
<language>PHP</language>
</s:settings>
You can use the method that better fits your needs., (*15)
Arrays
When a key appears twice or more within the same context then the values for that key are interpreted as an array, instead of preserving the last defined value:, (*16)
``` xml
red
green
blue
, (*17)
``` php
// array(
// array('colors' => array('red', 'green', 'blue'))
// )
When inheriting, the child settings overrides its parent:, (*18)
Reason: otherwise settings nodes having keys that already are defined by its parent would always append its value to the one from its parent, creating an array., (*19)
``` xml
black
white, (*20)
<s:settings>
<colors>red</colors>
<colors>green</colors>
<colors>blue</colors>
</s:settings>
<s:settings>
<colors>transparent</colors>
</s:settings>
, (*21)
``` php
// array(
// array('colors' => array('black', 'white')),
// array('colors' => array('red', 'green', 'blue'))
// array('colors' => 'transparent')
// )
String interpolation
String values could be considered as templates., (*22)
When an string contains something like {{ username }} the parser looks in the current context the value associated to the key "username" and makes a replacement., (*23)
``` xml
PHP
I like {{ language }}
, (*24)
``` php
// array(
// 'language' => 'PHP',
// 'string' => 'I like PHP',
// )
You can chain even more complicated interpolations and hierarchies:, (*25)
``` xml
PHP
{{ who }} {{ preference }} {{ language }} {{ how-many }}
like
, (*26)
<how-many>so much!<how-many>
<preference>love</preference>
, (*27)
``` php
// array(
// 'who' => 'I',
// 'language' => 'PHP',
// 'string' => 'I like PHP so much!',
// 'preference' => 'like',
// )
Caveats
Non-existing keys are replaced by an empty string, generating a warning.
``` xml
My name is {{ name }}
, (*28)
``` php
// array(
// array (
// 'string' => 'My name is ',
// )
// )
Cyclic recursive resolution will end with an empty string, generating a warning:, (*29)
``` xml
Need {{ key2 }}
Need {{ key3 }}
Need {{ key1 }}
, (*30)
``` php
// array(
// array (
// 'key1' => 'Need Need Need ',
// 'key2' => 'Need Need ',
// 'key3' => 'Need ',
// )
// )
Array interpolations are replaced by "<array>" and a warning is generated:, (*31)
``` xml
Spring
Summer
Autumn
Winter
A year is composed by {{ seasons }}
, (*32)
``` php
// array(
// array (
// 'seasons' => array('Spring','Summer','Autumn','Winter'),
// 'year' => 'A year is composed by <array>',
// )
// )
Wallogit.com
