o.php

Configuration

In this section we are not talking about php.ini. This is about your applications configuration and how it is accessed.

Configuration in PHP

A configuration is used to configure the initial settings for the program that is about to execute. They are normally loaded from a config file and parsed into a format the software can understand. As an engineer you are expected to create and modify these files, usually by hand, to effect the operation of your application.

PHP does not ship with or promote any one solution for storing and working with configuration files. It is up to the engineer to decide what is right for the problem at hand.

File Structures

There are many ideas around how your configuration should be serialized. Either as an INI file, XML, JSON, YAML or just a plain PHP script. If I don't have to use your application I don't have a strong opinion about which one you should choose.

The important thing for configuration is how you access it from your code.

I personally use YAML because at the time of writing it fulfills my needs and has several parsers for PHP, spyc being 100% native.

A simple YAML structure.

---
title: o.php
default: home
menu:
  - Home
  - Objects
  - Callbacks

The YAML as a PHP array.

<?php
$config
['title'] = 'o.php';
$config['default'] = 'home';
$config['menu'][0] = 'Home';
$config['menu'][1] = 'Objects';
$config['menu'][2] = 'Callbacks';
?>

This section focuses on how do you cleanly work with large multi-dimensional arrays that need be globally accessible.

Lowercase C

In order to follow the examples in this section you will need to require() the Config.php class. This file is include as part of the oLite.php script.

<?php
require('path/to/Config.php');
?>

For the rest of this section the assumption will be made that you have loaded into the variable $source the following multi-dimensional array.

<?php
$source
['database']['username'] = 'username';
$source['database']['password'] = 'password';
$source['database']['host']     = 'localhost';
$source['database']['port']     = '1234';

$source['mail']['username'] = 'username';
$source['mail']['password'] = 'password';
$source['mail']['host']     = 'mail.example.com';

$source['app']['seo']['title']       = 'Super App';
$source['app']['seo']['keywords']    = 'super, application';
$source['app']['seo']['description'] = 'AWhat a super application';
?>

The static method c::create() is a convenience for generating new configuration objects. The class name, a lowercase c, has been chosen to keep the static methods short and clean.

Once you have a configuration object you can populate it using the setter method setConfig(). It takes one argument which is the array you want to use as your configuration source. You can then retrieve the array with the getter method getConfig().

<?php
// Create a new configuration obejct
$config c::create();

// Sets the main configuration array
$config->setConfig($source);

// Returns the main configuration array
$config->getConfig(); // array
?>

php> Array
(
    [database] => Array
        (
            [username] => username
            [password] => password
            [host] => localhost
            [port] => 1234
        )
    [mail] => Array
        (
            [username] => username
            [password] => password
            [host] => mail.example.com
        )
    [app] => Array
        (
            [seo] => Array
                (
                    [title] => Super App
                    [keywords] => super, application
                    [description] => AWhat a super application
                )
        )
)

The create() method can also be called with an array as an optional argument. If provided the array will be silently passed to the setConfig() method.

<?php
// Create a new configuration obejct
$config c::create($source);

// Returns the main configuration array
$config->getConfig(); // array
?>

php> Array
(
    [database] => Array
        (
            [username] => username
            ....
)


Get

With the configuration loaded we now need a convenient way to access its values. The configuration object has the method get() which lets you ask for values based on a string which is a period separated list of Keys.

<?php
$config 
c::create($source);
$config->get('database.host'); // localhost
$config->get('database.port'); // 1234
$config->get('mail.username'); // username
$config->get('app.seo.title'); // Super App
?>

The value returned form the resolution of the provided Key could be any PHP value (normally either a scalar or an array).

<?php
$config 
c::create($source);
$config->get('mail'); // array
?>

php> Array
(
    [username] => username
    [password] => password
    [host] => mail.example.com
)

If for some reason a value is not found for the supplied Key, a value of null is returned.

<?php
$config 
c::create($source);
$config->get('database.host'); // localhost
$config->get('database.name'); // null
?>

In the case of missing values, which could be your required behavior, you can supply a second argument to get() which will be used as the default. Of course this could be a get() call too.

<?php
$config 
c::create($source);
$config->get('database.name''Not Provided'); // Not Provided
$config->get('database.name'$config->get('app.seo.title')); // Super App
?>

It should be noted that when a requested Key is purposefully set to null it will still trigger a fallback to the default value if it was provided.

Set

The configuration object has a setter method set() which can be used to update or add values.

More to be written...

You can touch it, smell it, taste it so sweet - Mike Patton