Pour faciliter l'utilisation du paquetage Hoa_Configuration, on ne se base pas sur une fabrique, mais sur les règles de nommages.

Ainsi, tous les paquetages commencent par : Hoa_Configuration_ et sont suivis du format que l'on souhaite utiliser. Si on veut utiliser le format INI, alors on demandera l'instance du paquetage : Hoa_Configuration_Ini, et ainsi de suite pour les autres formats. On aura quelque chose de semblable à :

<?php
 
set_include_path( ... );
require_once 'Framework.php';
import('Configuration.Ini');
 
/**
 * On demande l'instance de la
 * configuration des fichiers INI.
 */
$config = new Hoa_Configuration_Ini( ... );

Chaque objet de configuration par type de fichier a un constructeur différent. Cela se conçoit facilement, car chaque type de fichier n'a pas les mêmes besoins d'analyse ; un tableau se lit de façon naturelle, alors qu'un fichier INI a besoin de paramètres de lecture.

Il y a deux façons d'exploiter les données de configurations. La première, et celle par défaut, est la sortie en objet Hoa_StdClass. Cet objet offre des possibilités qui ne sont pas forcément évoquées ou détaillées dans ce chapitre, on conseille alors de lire le Chapitre 25, Hoa_StdClass.

/**
 * Soit la structure suivante :
 */
(
    'a' => 'AaA',
    'b' => 'bBb',
    'c' => (
        'x' => 'XxX',
        'y' => 'yYy',
        'z' => 'Zzz'
    )
);
 
/**
 * Alors on atteint les données de
 * cette façon :
 */
echo $structure->c->y;

[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*

$config = new Hoa_Configuration_xxx( ... );
 
/**
 * On parcourt tout le sous-niveau c.
 */
foreach($config->c as $key => $value)
    echo $key . ' : ' . $value . "\n";

echo $config;
 
/**
 * Affichera :
 *
 * Hoa_StdClass (
 *     [a] => AaA
 *     [b] => bBb
 *     [c] => Hoa_StdClass (
 *         [x] => XxX
 *         [y] => yYy
 *         [z] => Zzz
 *     )
 * )
 */

/**
 * On transforme nos configurations sous forme d'objet
 * vers un tableau.
 */
print_r($config->get()->toArray());
print_r($config->c->toArray());

Par défaut, la sortie est sous forme d'objet Hoa_StdClass, mais on a la possibilité de désactiver cette conversion à l'aide du dernier paramètre de chaque constructeur : CONVERT_TO_OBJECT pour activer la conversion, CONVERT_TO_ARRAY sinon. Ces constantes sont disponibles sur la classe Hoa_Configuration.

/**
 * On désactive la conversion en objet.
 */
$config = new Hoa_Configuration_xxx( ... , ... , Hoa_Configuration::CONVERT_TO_ARRAY);
 
/**
 * On accède aux données.
 */
echo $config['c']['y'] . "\n";
 
/**
 * On parcours les configurations.
 */
foreach($config['c'] as $key => $value)
    echo $key . ' : ' . $value . "\n";
 
/**
 * On affiche les configurations.
 */
print_r($config['c']);

Si on veut atteindre le niveau 0 (la racine) des configurations, on doit appeller la méthode get sur notre objet de configuration.

On peut également exploiter les configurations stockées dans un fichier INI. Pour cela, on procédera de la façon suivante :

<?php
 
set_include_path( ... );
require_once 'Framework.php';
 
import('Configuration.Ini');
 
$config = new Hoa_Configuration_Ini('Config.ini');

Si on veut reprendre les exemples précédents, alors le fichier Config.ini ressemblera à ceci :

a   = AaA
b   = bBb
c.x = XxX
c.y = yYy
c.z = Zzz

Les fichiers INI peuvent être construits en catégories, i.e. partagées en plusieurs parties :

[db]
host               = localhost
user               = root
pwd                = 
dbname             = base
 
[lang]
locale.timezone    = Europe/Paris
locale.region      = Franche-Comté
locale.departement = Doubs
encoding           = utf-8

Pour simplifier les traitements, on peut manipuler seulement une seule catégorie. Pour cela, on passe le nom de la catégorie en second paramètre du constructeur de Hoa_Configuration_Ini :

$config = new Hoa_Configuration_Ini('Config.ini', 'db');
 
/**
 * On ne parcourt que les configurations
 * de la base de données.
 */
foreach($config->get() as $key => $value)
    echo $key . ' ' . $value . "\n";

Et enfin, le troisième paramètre sert à désactiver la sortie sous forme de l'objet Hoa_StdClass pour activer la sortie sous forme d'un tableau :

$config = new Hoa_Configuration_Ini('Config.ini',
                                    'db',
                                    Hoa_Configuration::CONVERT_TO_ARRAY);
 
foreach($config->get() as $key => $value)
    echo $key . ' ' . $value . "\n";

On remarque que le point (.) est le séparateur de niveau dans les fichiers INI. Il est possible de les échapper avec Hoa, en les précédent d'un anti-slash (\) :

on.echappe\.un.point = hopla

Attention, si le fichier est converti en Hoa_StdClass le point sera transformé en trait de soulignement (underscore, _). À manipuler avec précaution donc.

L'analyse des fichiers XML se fait à l'aide du paquetage Hoa_Xml (voir le Chapitre 31, Hoa_Xml). Le constructeur de Hoa_Configuration_Xml prend donc en premier paramètre le fichier qui contient les configurations, puis l'encodage du fichier, et pour finir l'activation de la conversion vers une sortie objet :

import('Configuration.Xml');
 
$config = new Hoa_Configuration_Xml('Config.xml');

On aurait un fichier qui ressemblerait à (avec une en-tête qui précise la version et l'encodage) :

<configuration>
  <db>
    <host>localhost</host>
    <user>root</user>
    <pwd></pwd>
    <dbname>base</dbname>
  </db>
  <lang>
    <locale>
      <timezone>Europe/Paris</timezone>
      <region>Franche-Comté</region>
      <departement>Doubs</departement>
    </locale>
    <encoding>utf-8</encoding>
  </lang>
</configuration>

Et on accéderait aux données de cette façon :

echo $config->lang->locale->region . "\n";
 
/**
 * Affichera :
 *     Franche-Comté
 */

Dans XML, il peut arriver que l'on ait plein de fois la même balise à un même niveau, c'est ce qu'on appelle le multi-balisage^[8]. Dans ce cas, on a une liste ordonnée des balises (on conseille vraiment d'aller voir le chapitre concerné). Dans le cas d'une sortie Hoa_StdClass, les variables ne peuvent pas être entières^[9]. La solution qui a été retenue est de préfixer les entiers par un trait de soulignement (underscore, _), si on a demandé cette sortie. Pour un tableau rien ne change.

On pourrait alors avoir :

<configuration>
  <test>
    <bidule>machin</bidule>
  </test>
  <test>
    <truc>hopla</truc>
  </test>
</configuration>

On y accéderait de cette façon :

echo $config->test->_0->bidule;
 
/**
 * Affichera :
 *     machin
 */

On rappelle que ce problème n'a pas lieu avec une sortie en tableau.

Hoa_Configuration_Yaml analyse les fichiers à l'aide du paquetage Hoa_Yaml (voir le Chapitre 33, Hoa_Yaml), on retrouve donc les mêmes options que le constructeur pour le constructeur de Hoa_Configuration_Yaml (avec, en plus, la possibilité de ne pas convertir les configurations en objet Hoa_StdClass).

On aura quelque chose de semblable à ça :

import('Configuration.Yaml');
 
$config = new Hoa_Configuration_Yaml('Config.yml');

On aurait un fichier de configuration qui serait susceptible de ressembler à ceci :

host: localhost
user: root
pwd:
dbname: base

On accéderait aux données de cette façon (comme déjà vu précédemment) :

echo $config->host . "\n";

Un document YAML peut contenir plusieurs sous-documents, comme si le fichier en contenait plusieurs autres. Ces documents sont numérotés de 0 à n, et on y accède en passant un entier en second paramètre du constructeur. Par défaut, on sélectionne le premier document (donc d'index 0).

On aurait alors :

$config = new Hoa_Configuration_Yaml('Config.ini', 2);

On rappelle que les documents sont séparés par trois traits d'union (---) :

# Premier document (index 0).
---
host: localhost
user: root
pwd: 
dbname: base
 
# Second document (index 1).
---
etc: bla bla bla

Et enfin, le dernier paramètre spécifie si on veut que les configurations soient converties en objet Hoa_StdClass ou pas. Pour avoir un tableau en sortie, on aura :

$config = new Hoa_Configuration_Yaml('Config.yml',
                                     0,
                                     Hoa_Configuration::CONVERT_TO_ARRAY);

Dans YAML, on travaille beaucoup avec des listes ordonnées. Le problème, si on a choisi une sortie Hoa_StdClass, est que les nombres ne peuvent pas constituer une variable^[10]. La solution qui a été trouvée est que tous les nombres sont préfixés d'un trait de soulignement (underscore, _) si on a demandé cette sortie. Pour un tableau, rien ne change.

On pourrait alors avoir :

bob:
  - bill: le chien
  - billy: le crabe

On y accéderait de cette façon :

echo $config->bob->_1->billy;
 
/**
 * Affichera :
 *     le crabe
 */

On rappelle que ce problème n'a pas lieu avec une sortie en tableau.