The WebAbility® Network Developers - Documentation
WebAbility Site
XConfig - the Configuration Files Loader

I. Introduction:


XConfig is a comprehensive configuration files loader.
The files can be separated into diverse logic functionalities, and can be overloaded in cascade.

XConfig is released under GPLv3 licence.

XConfig has been written 100% in PHP and is totally object oriented, with the highest programming standards.
XConfig is fully compatible with PHP 5.2+

II. Installation:


2.1. Requirements


XConfig works with any PHP 5.2 version or superior on the server side.

2.2. Download:


We recommend to always download the lastest version of XConfig from our site or from github:
Link to another Internet page, will open in a new browserhttp://www.webability.info/?P=xconfig_download
Link to another Internet page, will open in a new browserhttps://github.com/webability/XCONFIG
Never download from other untrusted sources.

Be sure to always have the lastest version. All the versions are compatible with previous ones.

XConfig is stable and should not suffer any changes soon.

2.3. Install:


The file you download is a tarball gziped file with the format xconfig-xx.yy.zz.tar.gz where xx.yy.zz is the version number.

On windows, you can expand it with any decent compressor like zip ( Link to another Internet page, will open in a new browserhttp://www.winzip.com ), rar ( Link to another Internet page, will open in a new browserhttp://www.rarlab.com ) or powerarchiver ( Link to another Internet page, will open in a new browserhttp://www.powerarchiver.com ) and so on.

On Linux, put the xconfig-xx.yy.zz.tar.gz file in the directory you need it and type:
tar zxvf xconfig-xx.yy.zz.tar.gz

On Unix, put the xconfig-xx.yy.zz.tar.gz file in the directory you need it and type:
gunzip xconfig-xx.yy.zz.tar.gz
tar -xf xconfig-xx.yy.zz.tar
Or install gnu tar to use it like linux on your unix.

You should uncompress the xconfig into a web directory to use the examples.
If you already know how to use the xconfig, just uncompress it and copy the include directory in your application to use the objects.
It is highly recomended to let the include directory into a place which is NOT a public internet directory, and link the libraries through an autoload library.

For example, if your apache is installed on:
/home/apache
your default web directory should be:
/home/apache/htdocs
Uncompress the xconfig in this directory and you should get the main xconfig directory:
/home/apache/htdocs/xconfig

The xconfig is totally included into the xconfig/ directory and ready to use.

For development and production purpose, uncompress and copy the include directory into your application, for instance in
/home/apache/xconfig
in the previous example, and link the libraries with an autoload magic library.


III. Demos and examples:



Downloading and installing the full source, you will have the same demo site available in http://www.yoursite.com/xconfig/index.php


IV. User guide


The configuration file have the following syntax for example:



# this file is named myconfig.conf, used in following examples
# the # denotes a comment.
; is also a comment
parameter1=value1
parameter2=value2
parameter2=value3
parameter3.sub1=value4
parameter3.sub2=value5
parameter3.sub2=value6



As version 1.1, xconfig now accept true, on, yes as a boolean 'true' and false, off, no, none as a boolean 'false'.
For instance, that means parameter=off is now a boolean false, and parameter=yes is now a boolean true.

Before verion 1.0, note the config file is always read as a STRING.
That means parameter=0, parameter=false, parameter=123
will be caught as "0", "false", "123", not integers or booleans

When there is a point into the parameter name, it is cut in 2 parts and the main parameter becomes an asociative array of the sub parameters (see example).

This will be converted into the XConfig object.
The XConfig object is easily usable as:



$config = new \xconfig\XConfig('String of the config file');

or

$config = new \xconfig\XConfig(Array of parameters);



Concrete Example 1:



include_once 'include/xconfig/XConfig.class.php');
$config = new \xconfig\XConfig(file_get_contents('myconfig.conf'));



The result of loading the previous config file example is:



array(
'parameter1' => value1,
'parameter2' => array(value2, value3),
'parameter3' => array(
'sub1' => value4,
'sub2' => array(value5, value6)
)
);




Concrete Example 2:



include_once 'include/xconfig/XConfig.class.php');
$config = new \xconfig\XConfig(array(
'parameter1' => 'value1',
'parameter2' => array('value2', 'value3')
));



Once you have an instance of your configuration, you may use it like this:



// assign a local variable
$param1 = $config->parameter1;
echo $param1 . '
';

// use directly the variable
foreach($config->parameter2 as $p)
echo $p . '
';

// set a new parameter
$config->parameter3 = 'value3';

// iterate the config
foreach($config as $parameter => $value)
echo $parameter . ' = ' . $value . '
';




V. Advanced topic


5.1. Default values:


You may pass an array of default values to the constructor so if the parameter is *not present* into the config file, it will take the default value.
Note: default values will be taken only if the parameter DOES NOT EXIST into the config file. This means an empty value is considerated as a value

Something like this:
parameter1=
will not fire the default value because the parameter is present into the config file

You may encapsulate the config object into a specific personal object with a local default set of parameters.

Example:



class myConfig extends \xconfig\XConfig
{
private $default = array(
'parameter1' => 'default1'
);

public function __construct($data)
{
parent::__construct($data, $this->default);
}
}




5.2. Merging:


You may merge two config file (or more), for example when you have a master config file and a local replacement values config file:



include_once 'include/xconfig/XConfig.class.php');
$globalconfig = new \xconfig\XConfig(file_get_contents('myglobalconfig.conf'));
$localconfig = new \xconfig\XConfig(file_get_contents('mylocalconfig.conf'));
$globalconfig->merge($localconfig);



with files:



#global config:
ip=127.0.0.1
port=80
domain=test.com


#local config:
port=8080
title=Welcome



The result config after merging local into global will be:



ip=127.0.0.1
port=8080
domain=test.com
title=Welcome




5.3. Saving:


You may build back the config file string to save it on disk or database. This is usefull when you write an interface to edit the file and save it back.

You can control the NEWLINE static parameter depending on where you want to save or see the configuration string.



include_once 'include/xconfig/XConfig.class.php');
$globalconfig = new \xconfig\XConfig(file_get_contents('myglobalconfig.conf'));

// Some modifs
$globalconfig->newparam = 'newvalue';

// Save the file
\xconfig\XConfig::$NEWLINE = "\n";
file_put_contents('myglobalconfig.conf', (string)$globalconfig);
// or just print it
\xconfig\XConfig::$NEWLINE = "<br />";
print (string)$globalconfig;






VI. Reference: