Section Handlers

Introduction

Configuration can be organized in sections, which is not bound to a concrete configuration format.
Sections group configuration settings in order to have them organized according to the purpose they represent in terms of the application.
However, we may want to handle each section in a different way and assign different classes to load them.

The Lion configuration system provides an easy way to assign classes to handle concrete sections as well as accessors to get them.
__Configuration is the class for providing developer's access to their configuration. We can retrieve the configuration linked to a concrete context container by calling the __Context::getConfiguration() accessor.
The __Configuration class exposes an accessor which provides a way for the developer to request the configuration settings for a specific section: __Configuration::getSection()

We may also want to create custom configuration sections and classes to handle them. In that sense Lions provides an interface designed for that purpose: __ISectionHandler.
All we have to do is to implement this interface which defines just one single method: __ISectionHandler::process(). This method receives a callback when Lion intercepts a request to retrieve the associated configuration section. In the other hand, this method will receive an object representing the configuration section with accessors to navigate through the entire section structure.
This mechanism allows us to ignore details such as where the configuration files are located, parsing the configuration file for the particular section, and opening or closing the file.

Any call to get any section from the configuration system will be intercepted by Lion.
If the requested section has a section handler associated, Lion will execute the __ISectionHandler::process() method and return the obtained result from the section handler instead of the object representing the section.

Creating a section handler

Create a section handler is as simple as implement the __ISectionHandler.
At the same time, implement the __ISectionHandler is as simple as implement the __ISectionHandler::process() method.

The __ISectionHandler::process() receives a __ConfigurationSection instance representing the requested section. This object exposes several methods to ease the navigation through the section content.

i.e., imagine the following configuration file:

<?xml version = "1.0" standalone="yes"?>
 
<foobars>
  <foo bar="lion"/>
  <foo bar="rocks"/>
</foobars>

Now, a valid section handler to transform the configuration section in terms of Foo instances could be like the following one:

<?php
 
/**
 * foobars Section handler
 *
 */
class FooBarsSectionHandler implements __ISectionHandler {
    
    /**
     * Returns a collection of Foo instances according to
     * the configuration section.
     */ 
    public function &process(__ConfigurationSection &$section) {
        $return_value = array();
        $foobars = $section->getSections();
        foreach($foobars as &$foobar) {
            $foo = new Foo();
            $foo->setBar($foobar->getAttribute('bar'));   
            $return_value[] = $foo;
        }
        return $return_value;
    }
    
}

Enabling a section handler

Once we have defined a section handler we'll need to let Lion know which concrete section will be handled by it.
To do that, we'll add a new section-handler directive within the configuration-directives section.

i.e. continuing with our example, to enable the FooBarsSectionHandler to handle foobars section, will define the following section-handler directive:

<?xml version = "1.0" standalone="yes"?>
<configuration>
 
  <configuration-directives>
    <configuration-basedir>config</configuration-basedir>
 
    <section-handler name="foobars" 
                     handler-class="FooBarsSectionHandler"/>
  
  </configuration-directives>
  
  ...

Requesting a configuration section

Finally, to request a section within the configuration, we'll use the __Configuration::getSection() method:

i.e. continuing with our example:

<?php
 
//get an array of Foo instances according
//to the configuration:
$foos = __ApplicationContext::getInstance()->
                              getConfiguration()->
                              getSection('foobars');