File: README

Introduction

------------



ConfigurationLoader generates a php class from a specified xml file. Any property values are hard-coded into this class.

This means that you can use xml configuration files without having to re-parse them each time.



For instance, if you had an xml file that contained the following:

<Configuration>

    <username>david</username>

    <password>blah</password>

    <usernames type="array">

        <item value="david" />

        <item value="cath" />

        <item value="shaun" />

    </usernames>

</Configuration>



ConfigurationLoader would convert this into the following php class:



class Configuration

{

public $username;

public $password;

public $usernames

function __construct()

{

$this->username = "david";

$this->password = "blah;

$this->usernames = array();

$this->usernames[0] = "david";

$this->usernames[1] = "cath";

$this->usernames[2] = "shaun";

}

}



This table should help you to decide how to specify the values in your xml files

If you have been using a previous version of ConfigurationLoader, and are getting

errors caused by null configuration values when you use the latest version, consult

this table and update your xml file accordingly. As you can see, if the element has a value attribute then that value gets used over any value specified between the start and end tags.

the tag name 'elem' is used for documentation only, any tag name can be used in your xml files.



Xml content                    Php value assigned

                                  to property

<elem></elem>                        null 

<elem />                             null

<elem type="string" />               (string) null

<elem type="string></elem>           (string) null

<elem value="" />                    ""

<elem type="string" value="" />      (string) ""

<elem>12</elem>                      12

<elem type="int">12</elem>           (int) 12

<elem type="string">12</elem>        (string) "12"

<elem value="12" />                  12

<elem value="12" type="string" />    (string) "12"

<elem value="12" type="string">50</elem> (string) "12"

<elem value="12" type="int">50</elem> (int) 12

<elem value="hello" type="string"></elem> (string) "hello"

<elem value="hello"></elem>         (string) "hello"



Take a look at the example config.xml to find out the different ways of specifying your config values.



Setup

-----



1. If you are not putting ConfigurationLoader into your cgi directory, ensure that the folder where ConfigurationLoader.class.php is located is in your search path, eg:



    set_include_path(get_include_path() . PATH_SEPARATOR . "/home/dave/www/project/include");



2. Ensure that the path where your xml config file is has read permissions for whichever user runs your apache daemon. Open your apache config file and search for 'user', this value tells you which user is running apache.

   In unix-based systems you can then log in as root and enter:

   chown -R <user> <ConfigDirectory>

   chmod -R 755 <ConfigDirectory>





Ensure that the path where your php config class will reside has write permissions for whichever user runs your apache daemon. (It's easiest to put them both in the same folder). Log in as root and enter:

   chown -R <user> <ConfigDirectory>

   chmod -R 775 <ConfigDirectory>


DEFAULT VALUES

The easiest way to use ConfigurationLoader is to use the default file paths. If you call:

ConfigurationLoader::update(null, null);

It will look for a file called 'config.xml' in the same directory that your php page resides, it will then parse this file into config.xml.php for you to use.



Require_once(ConfigurationLoader.class.php);

ConfigurationLoader::update(</path/to/xml/config/file.xml>, </path/to/generated/php/config/file>);

$config = new <nameOfRootElementInXmlFile>();



For example, assuming that your root xml element is called 'config':



ConfigurationLoader::update("/home/me/www/app1/config/config.xml", "/home/me/www/app1/config/config.php");

$config = new config();



This will read config.xml and use it to generate config.php in /home/me/www/app1/config.php

You can now create a new instance of the class called config (the name of the class corresponds to the name of the root element in the xml config file), which will contain all your config values.

The method will only reparse the xml file if it is newer than the php class file, obviously if the php class doesn't yet exist then the xml file will be parsed anyway.



If you want to be more specific about what type you want a particular value to be, specify the type attribute for the value, eg:

<connectionString type="string">blahblahblah</connectionString>



If your xml file was:



<myApp>

    <database>

        <connectionString>This is my connection string</connectionString>

        <timeoutPeriod type="int">10</timeoutPeriod>

    </database>

</myApp>



After calling update you could create a new instance of your config class and access it as follows:



echo $config->database->connectionString . "<br />"; echo $config->database->timeoutPeriod . "<br />";



which would output:



This is my connection string

10



To the page



IMPORTANT NOTICES

-----------------



I'm no security expert but instinct tells me that allowing the apache user write access to your cgi-bin directory is not a good idea at all. There is also the added risk that ConfigurationLoader may overwrite one of your php files. For this reason it is better to put the generated .php file into it's own directory which is out of the web root directory.



I've only tested this class in php 5 on ubuntu linux. Feel free to report bugs but go easy on me!



Any hyphens or non-word characters in your xml element names will be converted into underscores when generating the classnames. For example an element named timeout-value will be converted to timeout_value. The simplest approach is to avoid naming your xml elements in this way.



Please email me at david.wainwright1@sky.com if you have any problems or suggestions for improvements to this class.