documentation/manual/fr/module_specs/Zend_Config_Xml.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!-- EN-Revision: 20765 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.config.adapters.xml">
   5     <title>Zend_Config_Xml</title>
   6
   7     <para>
   8         <classname>Zend_Config_Xml</classname> permet aux développeurs de stocker des données de
   9         configuration dans un format simple <acronym>XML</acronym> et de les lire grâce à une
  10         syntaxe de propriétés d'objets imbriquées. Le nom de l'élément racine du fichier
  11         <acronym>XML</acronym> n'a pas d'importance et peut être nommé arbitrairement. Le premier
  12         niveau des éléments <acronym>XML</acronym> correspond aux sections des
  13         données de configuration. Le format <acronym>XML</acronym> supporte l'organisation
  14         hiérarchique par l'emboîtement des éléments <acronym>XML</acronym> à l'intérieur des
  15         éléments de niveau section. Le contenu d'un élément <acronym>XML</acronym> de niveau le
  16         plus bas correspond aux données de configuration. L'héritage des sections est supportée
  17         par un attribut spécial de <acronym>XML</acronym> nommé <emphasis>extends</emphasis>, et la
  18         valeur de cet attribut correspond à la section de laquelle des données doivent être
  19         héritées.
  20     </para>
  21
  22     <note>
  23         <title>Type retourné</title>
  24         <para>
  25             Les données de configuration lues grâce à <classname>Zend_Config_Xml</classname> sont
  26             toujours des chaînes de caractères. La conversion des données à
  27             partir des chaînes de caractères vers d'autres types de données est laissée aux
  28             développeurs en fonction de leurs besoins.
  29         </para>
  30     </note>
  31
  32     <example id="zend.config.adapters.xml.example.using">
  33         <title>Utiliser Zend_Config_Xml</title>
  34
  35         <para>
  36             Cet exemple illustre une utilisation de base de <classname>Zend_Config_Xml</classname>
  37             pour le chargement des données de configuration à partir d'un fichier
  38             <acronym>XML</acronym>. Dans cet
  39             exemple il y a des données de configuration pour un environnement de production et pour
  40             un environnement de test. Puisque les données de configuration de l'environnement de
  41             test sont très semblables à celles de la production, la section de test hérite de la
  42             section de production. Dans ce cas, la décision est arbitraire et pourrait avoir été
  43             écrite réciproquement, avec la section de production héritant de la section de test,
  44             bien que ceci ne doit pas être le cas pour des situations plus complexes. Supposons,
  45             que les données suivantes de configuration sont contenues dans
  46             <filename>/chemin/vers/config.xml</filename>&#160;:
  47         </para>
  48
  49         <programlisting language="xml"><![CDATA[
  50 <?xml version="1.0"?>
  51 <configdata>
  52     <production>
  53         <webhost>www.example.com</webhost>
  54         <database>
  55             <adapter>pdo_mysql</adapter>
  56             <params>
  57                 <host>db.example.com</host>
  58                 <username>dbuser</username>
  59                 <password>secret</password>
  60                 <dbname>dbname</dbname>
  61             </params>
  62         </database>
  63     </production>
  64     <test extends="production">
  65         <database>
  66             <params>
  67                 <host>dev.example.com</host>
  68                 <username>devuser</username>
  69                 <password>devsecret</password>
  70             </params>
  71         </database>
  72     </test>
  73 </configdata>
  74 ]]></programlisting>
  75
  76         <para>
  77             Ensuite, supposons que le développeur a besoin des données de configuration de
  78             test issues du fichier <acronym>XML</acronym>. Il est facile de charger ces données
  79             en indiquant le fichier <acronym>XML</acronym> et la section de test&#160;:
  80         </para>
  81
  82         <programlisting language="php"><![CDATA[
  83 $config = new Zend_Config_Xml('/chemin/vers/config.xml', 'test');
  84
  85 echo $config->database->params->host;   // affiche "dev.example.com"
  86 echo $config->database->params->dbname; // affiche "dbname"
  87 ]]></programlisting>
  88     </example>
  89
  90     <example id="zend.config.adapters.xml.example.attributes">
  91         <title>Utilisation des attributs de balise avec Zend_Config_Xml</title>
  92
  93         <para>
  94             <classname>Zend_Config_Xml</classname> supporte aussi 2 autres manières de définir des
  95             noeuds dans la configuration. Celles-ci utilisent les attributs de balises. Puisque les
  96             attributs <emphasis>extends</emphasis> et <emphasis>value</emphasis> sont des mots
  97             réservés (ce dernier par la seconde manière d'utiliser les attributs), ils ne doivent
  98             pas être utilisés. La première manière d'utiliser les attributs est de les ajouter
  99             au noeud parent, ils seront ainsi interprétés en tant qu'enfant de ce noeud&#160;:
 100         </para>
 101
 102         <programlisting language="xml"><![CDATA[
 103 <?xml version="1.0"?>
 104 <configdata>
 105     <production webhost="www.example.com">
 106         <database adapter="pdo_mysql">
 107             <params host="db.example.com"
 108                     username="dbuser"
 109                     password="secret"
 110                     dbname="dbname"/>
 111         </database>
 112     </production>
 113     <staging extends="production">
 114         <database>
 115             <params host="dev.example.com"
 116                     username="devuser"
 117                     password="devsecret"/>
 118         </database>
 119     </staging>
 120 </configdata>
 121 ]]></programlisting>
 122
 123         <para>
 124             La seconde manière ne permet pas vraiment de raccourcir la configuration, mais la
 125             rend plus facile à maintenir puisque vous n'avez pas à écrire les noms de balises deux
 126             fois. Vous créez simplement une balise vide ayant sa valeur dans
 127             <emphasis>value</emphasis>&#160;:
 128         </para>
 129
 130         <programlisting language="xml"><![CDATA[
 131 <?xml version="1.0"?>
 132 <configdata>
 133     <production>
 134         <webhost>www.example.com</webhost>
 135         <database>
 136             <adapter value="pdo_mysql"/>
 137             <params>
 138                 <host value="db.example.com"/>
 139                 <username value="dbuser"/>
 140                 <password value="secret"/>
 141                 <dbname value="dbname"/>
 142             </params>
 143         </database>
 144     </production>
 145     <staging extends="production">
 146         <database>
 147             <params>
 148                 <host value="dev.example.com"/>
 149                 <username value="devuser"/>
 150                 <password value="devsecret"/>
 151             </params>
 152         </database>
 153     </staging>
 154 </configdata>
 155 ]]></programlisting>
 156     </example>
 157
 158     <note>
 159         <title>Chaînes de caractères XML</title>
 160         <para>
 161             <classname>Zend_Config_Xml</classname> est capable de charger une chaîne de caractères
 162             <acronym>XML</acronym> directement, par exemple si elle est issue d'une base de données.
 163             La chaîne est fournie en tant que premier paramètre du constructeur et doit commencer
 164             par les caractères <emphasis>'&lt;?xml'</emphasis>&#160;:
 165         </para>
 166         <programlisting language="xml"><![CDATA[
 167 $string = <<<EOT
 168 <?xml version="1.0"?>
 169 <config>
 170     <production>
 171         <db>
 172             <adapter value="pdo_mysql"/>
 173             <params>
 174                 <host value="db.example.com"/>
 175             </params>
 176         </db>
 177     </production>
 178     <staging extends="production">
 179         <db>
 180             <params>
 181                 <host value="dev.example.com"/>
 182             </params>
 183         </db>
 184     </staging>
 185 </config>
 186 EOT;
 187
 188 $config = new Zend_Config_Xml($string, 'staging');
 189 ]]></programlisting>
 190     </note>
 191
 192     <note>
 193         <title>Espace de noms XML de Zend_Config</title>
 194
 195         <para>
 196             <classname>Zend_Config</classname> possède son propre espace de noms
 197             <acronym>XML</acronym>, qui ajoute des fonctionnalités additionnelles lors du
 198             processus d'analyse. Pour tirer avantage de celui-ci, vous devez définir l'espace
 199             de noms avec l'<acronym>URI</acronym>
 200             <filename>http://framework.zend.com/xml/zesnd-config-xml/1.0/</filename> dans
 201             votre noeud racine de configuration.
 202         </para>
 203
 204         <para>
 205             Avec l'espace de noms activé, vous pouvez maintenant utiliser les constantes
 206             <acronym>PHP</acronym> à l'intérieur de vos fichiers de configuration.
 207             De plus l'attribut <emphasis>extends</emphasis> a été déplacé dans ce nouvel
 208             espace de noms et déprécié de l'espace de noms <constant>NULL</constant>.
 209             Il en sera complétement effacé dans Zend Framework 2.0.
 210         </para>
 211
 212         <programlisting language="xml"><![CDATA[
 213 $string = <<<EOT
 214 <?xml version="1.0"?>
 215 <config xmlns:zf="http://framework.zend.com/xml/zend-config-xml/1.0/">
 216     <production>
 217         <includePath>
 218             <zf:const zf:name="APPLICATION_PATH"/>/library</includePath>
 219         <db>
 220             <adapter value="pdo_mysql"/>
 221             <params>
 222                 <host value="db.example.com"/>
 223             </params>
 224         </db>
 225     </production>
 226     <staging zf:extends="production">
 227         <db>
 228             <params>
 229                 <host value="dev.example.com"/>
 230             </params>
 231         </db>
 232     </staging>
 233 </config>
 234 EOT;
 235
 236 define('APPLICATION_PATH', dirname(__FILE__));
 237 $config = new Zend_Config_Xml($string, 'staging');
 238
 239 echo $config->includePath; // Affiche "/var/www/something/library"
 240 ]]></programlisting>
 241     </note>
 242
 243 </sect1>