In addition to the technique described previously, the Config class also includes a number of built-in methods to retrieve configuration values from the internal stack after they have been read in. In order to understand this alternative approach, you first need to conceptually understand how the Config class deals with a configuration file, and with the various sections within it.

Seen through the eyes of Config, every configuration file can be broken down into four basic elements:

1. Sections - blocks within the configuration file, each with a name, containing one or more directives.

2. Directives - variable-value pairs

3. Comments - explanatory notes which can be ignored, these are meant only for human consumption

4. Blanks - blank lines, useful for cleaning up the visual appearance of a configuration file

The root object returned by the parseConfig() method is a section, and as such, it exposes a number of different methods. For the moment, we'll focus on the getItem() method, used to return a reference to another section, to a directive, or to a comment. Once a reference is obtained to a directive or comment, other methods - the most common one is getContent() - become available to retrieve the content of that directive or comment.

In order to better understand how this works, consider the following example, which does exactly what the previous example did, but uses object methods and properties to retrieve the various configuration values.

  <?php

// include class

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

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

  $root =& $c->parseConfig("mysql.conf.xml", "XML");
// get reference to <mysql> element of file

  $mysqlSection =& $root->getItem("section", "mysql");
// get reference to <host> element

  $hostDirective =& $mysqlSection->getItem("directive", "host"); 
  // get content of <host> element $host = $hostDirective->getContent();
// get reference to <user> element

  $userDirective =& $mysqlSection->getItem("directive", "user"); 
  // get content of <user> element $user = $userDirective->getContent();
// get reference to <pass> element

  $passDirective =& $mysqlSection->getItem("directive", "pass"); 
  // get content of <pass> element $pass = $passDirective->getContent();
// get reference to <db> element

  $dbDirective =& $mysqlSection->getItem("directive", "db");

  // get content of <db> element

  $db = $dbDirective->getContent();
// open connection to database

  $connection = mysql_connect($host, $user, $pass) or die ("Unable to connect!");

  mysql_select_db($db) or die ("Unable to select database!");
// execute query

  $query = "INSERT INTO stocks (symbol, price) VALUES ('HYYJ', 198.78)"; 
  $result = mysql_query($query) or die ("Error in query: $query. " . 
  mysql_error());
// close database connection

  mysql_close($connection);
?>

  

If you've ever used the Document Object Model (DOM) in XML, the above probably looks strangely familiar to you. It should - the Config class uses a similar approach, providing methods to obtain references to different "nodes" of the configuration "tree", and thereby to retrieve the values of those nodes. Like the DOM, there are also methods to add, edit and delete nodes - but those come later.

A quick note on the getItem() method above - it can be used to return a reference to any section of the configuration file and requires, as first argument, one of the keywords "section", "directive", "comment" or "blank" (to identify the type of data needed) and, as second argument, an identifier to help it locate the necessary node. A number of different options can be sent as additional arguments to getItem() to help it identify the correct node - take a look at the manual for detailed information on this.

Once a reference to the correct node has been obtained, the getContent() method can be used to retrieve its value. This method may be used with both directives and comments.

Here's another example, this time using a Windows INI file like the one below,

  [Settings]

  POPAccount=me@my.mail.domain

  SMTPServer=mail.my.domain.com

  Signature=default

  POPPassword=guessme

[ToolBar-Summary]

  Bars=7

  ScreenCX=800

  ScreenCY=600

  

and the following script to retrieve mail server access information:

  <?php

// include class

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

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

  $root =& $c->parseConfig("mail.ini", "IniFile");
// get reference to [Settings] section of file

  $settingsSection =& $root->getItem("section", "Settings");
// get POP account

  $popAccountDirective =& $settingsSection->getItem("directive", 
  "POPAccount"); $popAccount = $popAccountDirective->getContent();
// get password

  $passwordDirective =& $settingsSection->getItem("directive", 
  "POPPassword"); $password = $passwordDirective->getContent();
// print current configuration

  echo "System is currently configured for POP account $popAccount and password 
  $password";
?>

  

This follows much the same logic as before - the getItem() method is used to first obtain a reference to the [Settings] section of the INI file, and then to the appropriate directives within that section. Once the variable values have been retrieved via the getContent() method, they are printed to the output device.

Here's the output:

System is currently configured for POP account me@my.mail.domain and password guessme

When retrieving configuration data in this manner, a number of utility methods are also available; these can come in handy in certain situations. Here's a quick list:

getName() - retrieves the item name

getType() - retrieves the item type

getParent() - retrieves a reference to the item's parent

getChild() - returns a reference to the item's child

getItemPosition() - returns the item's position among its siblings

countChildren() - returns a count of the item's children