Configuration :: Adventure PHP Framework (APF)

Configuration

1. Introduction

To be able to implement reusable applications the aid of configuration is used in some places. To have a generic "interface" for the loading of configuration files in the Windows INI style the configurationManager was integrated into the framework. To improve handling of configuration files the additional wrapper method is __getConfiguration() was included in the class coreObject. This offers the ability in classes inheriting from coreObject to load configurations in that easy way. Because the configurationManager is initialized and accessed in the singleton mode each configuration is internally cached by the module. Hence, accessing one single configuration file frequently is no bottleneck. As are already mentioned the configuration files are build up like Windows INI files and contain sections and key-value-pairs. A typical INI file is showed by the following code example:

APF-Konfiguration

[Section1]
Param1 = "Value1"
Param2 = "Value2"
...

[Section2]
Param1 = "Value1"
Param2 = "Value2"
...

The sections and key value pairs contained in the configuration file are freely eligible by the developer. Merely the structure of the already existing components are given and the used sections and configuration keys are well-defined.

2. Naming convention for paths and files

With the name of the files and paths some basic conditions are to be followed. To make applications or modules (=software parts which can be used in several applications) reusable for different projects a configuration file is composed of different "parts":

Namespace:
The namespace is a path to a basic folder that contains all configuration file of a specific module or class. The namespace often corresponds with the namespace of the module or class. Due to the fact, that the APF features the paradigm of seperatinf configuration from code, the configurationManager expects all configuration files to pe placed in the config folder. This means, that the real folder path of the configuration is consists of the namespace, that is used to address the config within an application and the prefix config.
Context:
To realize reusabity, another differentiating factor is introduced. Each configuration file path is extended by the current context of the application. This introduces the possibility to include module A in website B or C without changing the progranm code but only by adding another configuration file under the current context of project C.
Environment:
The third distinguishing feature is the enviroment the modul is executed in. This patameter renders possible to create configuration files for different environments such as test server or production environment. The environment variable is therefor handled by the registry and can be manipulated in the bootstrap file if desired. For more details, please have a look at the basics chapter, section 3.3.
Name:
The name of the configuration file should be self-explanatory. The file must be equipped with the prefix {ENVIRONMENT} und the suffix .ini. If the developer wants to store his configuration params in a file called myconfig and the environment variable was not modified, the configurationManager expects the file to be named DEFAULT_myconfig.ini.

The context of an application can be influenced while creating the page controller or front controller instances:

2.1. Context while using the front controller

PHP-Code

$fC = &Singleton::getInstance('Frontcontroller');
$fC->set('Context','sites::mysite');
$fC->start('sites::mysite::pres::templates','mywebsite');

Here the internal variable "Context" is supplied by the explicit call of the set() method after creating the front controller instance. The context will be "transmitted" to other objects of the DOM tree of the presentation layer or to service objects of the business and data layer automatically.

2.2. Context while using the page controller

By the use of the page controller the context is implicitly filled with the first argument of the call of the method loadDesign(). Besides, the context can also be set manually by adding

PHP-Code

$page->set('Context','sites::myspecialsite');

to the following code lines:

PHP-Code

$page = new Page();
$page->loadDesign('sites::mysite::pres::templates','mywebsite');
echo $page->transform();

Now the context of the application is "sites::mysite". Setting the context manually it receives the value "sites::myspecialsite".

Let us assume, that we have the following index.php file:

PHP-Code

$page = new Page();
$page->set('Context','sites::myapp');
$page->loadDesign('sites::mysite::pres::templates','mywebsite');
echo $page->transform();

If in any module configurationManager is called by

PHP-Code

$Config = &$this->__getConfiguration('modules::mymodule','mymoduleconfig');

it would expect the configuration file to reside in the folder

Code

/apps/config/modules/mymodule/sites/myapp/

and to be named

Code

DEFAULT_mymoduleconfig.ini

In case of non existing configuration files, the developer is noticed by the configurationManager. Additionally a error message is printed that contains the expected configuration file so that this error can be corrected by the engineer.

3. Service objects

Because configurations are often used in the business and data layer, the context must be confessed to these both layers of the application. By the use of the front controller the topical context is given to every action and these are thus able to call service objects of the business layer with this context. The page controller provides the context to every node of the DOM tree. If a document controller likes to generate a business component, or get a reference on this, the methods __getServiceObject() or __getAndInitServiceObject() must always be used. Both functions ensure that every service object receives the right context. Implementing details and documentation of the parameters are found in the API documentation. As a rule it is adequate to create a service layer like this:

PHP-Code

$GuestbookID = '1';
$oGuestbookManager = &$this->__getServiceObject('modules::guestbook::biz','GuestbookManager');
$Guestbook = $oGuestbookManager->loadGuestbook($GuestbookID);

To get a initialized instance of the desired serice layer please use

PHP-Code

$GuestbookID = '1';
$oGuestbookManager = &$this->__getAndInitServiceObject(
                                                      'modules::guestbook::biz',
                                                      'GuestbookManager',
                                                      $GuestbookID
                                                    );
$Guestbook = $oGuestbookManager->loadGuestbook();

The last example premises, that the GuestbookManager has the init() function implemented.

4. Reading configuration

To read the values of a configuration several methods of the central configuration object are available. These are getConfiguration(), getSection() and getValue(). With these the complete configuration, a single section or the value of a section can be returned either.

Example:

We assume a configuration file with the following content was created:

APF-Konfiguration

[Section1]
Key1 = "Value1"
Key2 = "Value2"
Key3 = "Value3"
[Section2]
Key1 = "Value1"
Key2 = "Value2"
Key3 = "Value3"

So the developer can fetch the content of the configuration file by placing the code

PHP-Code

$Config = &$this->__getConfiguration('modules::mymodule','mymoduleconfig');
echo printObject($Config->getConfiguration());

in any component of the application. The "echo" results in

Code

Array
(
    [Section1] => Array
        (
            [Key1] => Value1
            [Key2] => Value2
            [Key3] => Value3
        )

    [Section2] => Array
        (
            [Key1] => Value1
            [Key2] => Value2
            [Key3] => Value3
        )
)

With the use of

PHP-Code

$Config = &$this->__getConfiguration('modules::mymodule','mymoduleconfig');
echo printObject($Config->getSection('Section2'));

the array

Code

Array
(
    [Key1] => Value1
    [Key2] => Value2
    [Key3] => Value3
)

is printed and

PHP-Code

$Config = &$this->__getConfiguration('modules::mymodule','mymoduleconfig');
echo $Config->getValue('Section1','Key2');

displays

Code

Value2

to the screen. The function printObject() is only used for cosmetic reasons. The values can be directly used in the application code as desired.

5. Case study: multi language applications

To be able to implement multilanguage applications the language is held in every GUI object of the framework. Thus the topically used language is always known and partial trees can also be equipped with different languages if desired. The realisation of the multilingual facility in application is provided by the tag <html:getstring /> and <template:getstring />. These read in the language-dependent contents from a configuration file specified in the tag attributes and print them to template files or HTML templates.

To realize this two conditions must be fulfilled::

5.1. Creation of a config file

As described in chapter 2, please take care of the current context of the application when creating the configuration file. Under the acceptance, that the topically discussed application is stored under the namespace

Code

/modules/mymodule/

and the current context is sites::myapp, the language dependent configuration file must be storend under the folder

Code

/config/modules/mymodule/sites/myapp/

The filename should be

Code

DEFAULT_mymodule_lang.ini

whereas mymodule is replaced by the real name of the module. The file's content can be filled out freely by the developers. It must be considered that the sections of the configuration file must be named with two letter ISO language codes. For details please refer to http://de.wikipedia.org/../ISO-L%C3%A4ndercode or to http://www.iso.org/../list-en1.html. The following example shows a common example:

APF-Konfiguration

[de]
Form.Name = "Ihr Name"
Form.EMail = "Ihre E-Mail-Adresse"
Form.Subject = "Betreff"
..

[en]
Form.Name = "Your name"
Form.EMail = "Your email adress"
Form.Subject = "Subject"
..

5.2. Display of language-dependent texts

To provide language-dependent texts two alternatives exist in the framework design. On the one hand the XML tags <html:getstring /> and <template:getstring /> can be used to display language-dependent content in template files or HTML templates. On the other hand the method __getConfiguration() of the configurationManager component can be uses directly (e.g. setting the display name of a form button). First the integration of the configuration file via XML tags described on top should be explained:

To provide language dependent areas the template

APF-Template

<html:template name="MyTemplate">
 [..]
 Ihr Name: <template:placeholder name="Name" />
 <br />
 Ihre E-Mail-Adresse: <template:placeholder name="EMail" />
 <br />
 [..]
</html:template>

must be changed to

APF-Template

<html:template name="MyTemplate">
 [..]
 <template:getstring namespace="modules::mymodule" config="mymodule_lang" entry="Form.Name" />:
 <template:placeholder name="Name" />
 <br />
 <template:getstring namespace="modules::mymodule" config="mymodule_lang" entry="Form.EMail" />:
 <template:placeholder name="EMail" />
 <br />
 [..]
</html:template>

Here the statical texts are exchanged with XML tags that print the values configuration keys "Form.Name" and "Form.EMail". If any language-dependent values are needed within a document controller (e.g. for email dipatching) these values can be gathered by placing the following code in your controller

PHP-Code

$Config = &$this->__getConfiguration('modules::mymodule','mymodule_lang');
echo '
Form.Name: '.$Config->getValue($this->__Language,'Form.Name');
echo '
Form.EMail: '.$Config->getValue($this->__Language,'Form.EMail');
echo '
Form.Subject: '.$Config->getValue($this->__Language,'Form.Subject');

The echo provided here is just placed there to demonstrate the functionality. In real life applications, the values printed out are used to fill place holders in templates such as

APF-Template

<html:template name="MyTemplate">
 <div class="FormHeader">
   <template:placeholder name="FormHeader" />
 </div>
</html:template>

by writing down the code

PHP-Code

// Read configuration
$Config = &$this->__getConfiguration('modules::mymodule','mymodule_lang');

// Get the reference of the template
$Template__MyTemplate = &$this->__getTemplate('MyTemplate');

// Fill placeholder "FormHeader"
$Template__MyTemplate->setPlaceHolder('FormHeader',$Config->getValue($this->__Language,'Form.Name'));

More examples can be seen in the guestbook tutorial.

Comments

Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.

There are no comments belonging to this article.

Configuration

Comments

QUICKNAVI