Let's assume that I have a PHP associative array containing a series of configuration variables, as in the following snippet:

  <?php

  $mailConfig = array(

  'name' => 'Bruce Banner', 

  'email' => 'hulk@angry.green.guy',

  'host' => 'mail.apollo.domain'

  );

  ?>

  

Normally, these configuration values would arrive via user input, perhaps via a form, perhaps through command-line entry. For simplicity and ease of understanding, however, I'm hard-wiring them for the moment; once you've understood the basics, a subsequent example will demonstrate how they can be extracted from a form.

The task at hand now consists of storing them permanently, by saving them to a configuration file. With the Config class, this is a snap - consider the following script, which demonstrates:

  <?php

// configuration data

  // hard-wired right now

  // usually taken from form input

  $mailConfig = array(

  'name' => 'Bruce Banner', 

  'email' => 'hulk@angry.green.guy',

  'host' => 'mail.apollo.domain'

  );
// include class

  include("Config.php");
// instantiate object

  $c = new Config();
// read configuration data and get reference to root

  $root =& $c->parseConfig($mailConfig, "PHPArray");
// write configuration to file as PHP array $c->writeConfig("mail.conf", 
  "PHPArray");
?> 

  

Let's dissect this a little to see how it works.

1. The first step is, obviously, to include all the relevant files for the class to work.

  // include class

  include("Config.php");

  

Once that's done, I can safely create an object of the Config class.

  // instantiate object

  $c = new Config();

  

This object instance will serve as the primary access point to the data in the application configuration file(s), allowing me to do all kinds of nifty things with it.

2. Next, the object's parseConfig() method is used to read the configuration data into the object.

  // read configuration data and get reference to root

  $root =& $c->parseConfig($mailConfig, "PHPArray");

  

An interesting point to note is the second argument to parseConfig(); this is a predefined type that tells the Config object the format or structure in which the configuration variables are stored, thereby simplifying the task of extracting those variables and restructuring them as per the object's internal requirements. The Config object defines a number of such formats, covering most of the major types of configuration files - here's a list of the important ones (there are a couple more, take a look at the manual for more details):

1. "GenericConf" - a generic configuration file consisting of colon-delimited variable-value pairs, such as the following:

  mouse:Mickey

  duck:Donald

  

2. "IniFile" - a Windows-style initialization (INI) file, such as the
following:

  [characters]

  mouse=Mickey

  duck=Donald

  

3. "PHPArray" - a PHP associative array, such as the following:

  <?php

  $mouse = 'Mickey';

  $duck = 'Donald';

  ?>

  

4. "XML" - an XML file, such as the following:

  <?xml version="1.0" encoding="ISO-8859-1"?>

  <characters>

  <mouse>Mickey</mouse>

  <duck>Donald</duck>

  </characters>

  

The second argument passed to parseConfig() thus tells the Config object how the configuration variables are stored, thereby activating the rulesets needed to read and manipulate them.

4. Once the configuration data has been read into the object via parseConfig(), you can use it for whatever purpose you wish - to retrieve an individual value (or set of values) from it, to modify values, or to write the data to a file. Coincidentally, the script above picks door number three, writing the configuration data to a file named "mail.conf" in the current directory via the writeConfig() method.

  // write configuration to file as PHP array $c->writeConfig("mail.conf", 
  "PHPArray"); 

Note that here too, the second argument to writeConfig() is a type identifier - this tells Config what format the data should be written in. As you will see shortly, altering this parameter significantly affects the format of the configuration file.

When you run this script via your Web browser, the configuration data in the PHP array $mailConfig will be written to a configuration file named "mail.conf", as noted previously. If you look into this file, you should see something like this:

<?php
$name = 'Bruce Banner';
$email = 'hulk@angry.green.guy';
$host = 'mail.apollo.domain';
?>

If you don't like this, the writeConfig() method also offers you a further degree of customization when dealing with the PHPArray type - you can specify that the variable-value pairs be structured as an associative array of key-value pairs (rather than regular variables, as above) by adding an optional third argument to writeConfig(). Here's how:

  <?php

// configuration data

  $mailConfig = array(

  'name' => 'Bruce Banner', 

  'email' => 'hulk@angry.green.guy',

  'host' => 'mail.apollo.domain'

  );
// include class

  include("Config.php");
// instantiate object

  $c = new Config();
// read configuration data and get reference to root

  $root =& $c->parseConfig($mailConfig, "PHPArray");
// set options for output array

  $options = array('name' => 'mailSettings');
// write configuration to file as PHP array $c->writeConfig("mail.conf", 
  "PHPArray", $options);
?>

  

In this case, the data written to "mail.conf" will be structured as an associative array with the name $mailSettings. Here's what the file would look like:

<?php
$mailSettings['name'] = 'Bruce Banner';
$mailSettings['email'] = 'hulk@angry.green.guy'; $mailSettings['host'] = 'mail.apollo.domain'; ?>