documentation/manual/en/module_specs/Zend_Config_Writer.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.config.writer.introduction">
   4     <title>Zend_Config_Writer</title>
   5
   6     <para>
   7         <classname>Zend_Config_Writer</classname> gives you the ability to write config
   8         files out of <classname>Zend_Config</classname> objects. It works with an
   9         adapter-less system and thus is very easy to use. By default
  10         <classname>Zend_Config_Writer</classname> ships with three adapters, which are all
  11         file-based. You instantiate a writer with specific options, which
  12         can be <emphasis>filename</emphasis> and <emphasis>config</emphasis>. Then
  13         you call the <methodname>write()</methodname> method of the writer and the config
  14         file is created. You can also give <varname>$filename</varname> and
  15         <varname>$config</varname> directly to the <methodname>write()</methodname> method.
  16         Currently the following writers are shipped with
  17         <classname>Zend_Config_Writer</classname>:
  18     </para>
  19
  20     <itemizedlist>
  21         <listitem>
  22             <para>
  23                 <classname>Zend_Config_Writer_Array</classname>
  24             </para>
  25         </listitem>
  26
  27         <listitem>
  28             <para>
  29                 <classname>Zend_Config_Writer_Ini</classname>
  30             </para>
  31         </listitem>
  32
  33         <listitem>
  34             <para>
  35                 <classname>Zend_Config_Writer_Xml</classname>
  36             </para>
  37         </listitem>
  38     </itemizedlist>
  39
  40     <para>
  41         The <acronym>INI</acronym> writer has two modes for rendering with regard to sections.
  42         By default the top-level configuration is always written into section names.
  43         By calling <command>$writer->setRenderWithoutSections();</command> all options are written
  44         into the global namespace of the <acronym>INI</acronym> file and no sections are applied.
  45     </para>
  46
  47     <para>
  48         As an addition <classname>Zend_Config_Writer_Ini</classname> has an additional
  49         option parameter <emphasis>nestSeparator</emphasis>, which defines with which
  50         character the single nodes are separated. The default is a single dot,
  51         like it is accepted by <classname>Zend_Config_Ini</classname> by default.
  52     </para>
  53
  54     <para>
  55         When modifying or creating a <classname>Zend_Config</classname> object, there are
  56         some things to know. To create or modify a value, you simply say set
  57         the parameter of the <classname>Zend_Config</classname> object via the parameter
  58         accessor (<emphasis>-&gt;</emphasis>). To create a section in the root or to
  59         create a branch, you just create a new array
  60         ("<command>$config-&gt;branch = array();</command>"). To define which section
  61         extends another one, you call the <methodname>setExtend()</methodname> method
  62         on the root <classname>Zend_Config</classname> object.
  63     </para>
  64
  65     <example id="zend.config.writer.example.using">
  66         <title>Using Zend_Config_Writer</title>
  67
  68         <para>
  69             This example illustrates the basic use of
  70             <classname>Zend_Config_Writer_Xml</classname> to create a new config file:
  71         </para>
  72
  73         <programlisting language="php"><![CDATA[
  74 // Create the config object
  75 $config = new Zend_Config(array(), true);
  76 $config->production = array();
  77 $config->staging    = array();
  78
  79 $config->setExtend('staging', 'production');
  80
  81 $config->production->db = array();
  82 $config->production->db->hostname = 'localhost';
  83 $config->production->db->username = 'production';
  84
  85 $config->staging->db = array();
  86 $config->staging->db->username = 'staging';
  87
  88 // Write the config file in one of the following ways:
  89 // a)
  90 $writer = new Zend_Config_Writer_Xml(array('config'   => $config,
  91                                            'filename' => 'config.xml'));
  92 $writer->write();
  93
  94 // b)
  95 $writer = new Zend_Config_Writer_Xml();
  96 $writer->setConfig($config)
  97        ->setFilename('config.xml')
  98        ->write();
  99
 100 // c)
 101 $writer = new Zend_Config_Writer_Xml();
 102 $writer->write('config.xml', $config);
 103 ]]></programlisting>
 104
 105         <para>
 106             This will create an <acronym>XML</acronym> config file with the sections production
 107             and staging, where staging extends production.
 108         </para>
 109     </example>
 110
 111     <example id="zend.config.writer.modifying">
 112         <title>Modifying an Existing Config</title>
 113
 114         <para>
 115             This example demonstrates how to edit an existing config file.
 116         </para>
 117
 118         <programlisting language="php"><![CDATA[
 119 // Load all sections from an existing config file, while skipping the extends.
 120 $config = new Zend_Config_Ini('config.ini',
 121                               null,
 122                               array('skipExtends'        => true,
 123                                     'allowModifications' => true));
 124
 125 // Modify a value
 126 $config->production->hostname = 'foobar';
 127
 128 // Write the config file
 129 $writer = new Zend_Config_Writer_Ini(array('config'   => $config,
 130                                            'filename' => 'config.ini'));
 131 $writer->write();
 132 ]]></programlisting>
 133     </example>
 134
 135     <note>
 136         <title>Loading a Config File</title>
 137
 138         <para>
 139             When loading an existing config file for modifications it is very
 140             important to load all sections and to skip the extends, so that
 141             no values are merged. This is done by giving the
 142             <emphasis>skipExtends</emphasis> as option to the constructor.
 143         </para>
 144     </note>
 145
 146     <para>
 147         For all the File-Based writers (<acronym>INI</acronym>, <acronym>XML</acronym> and
 148         <acronym>PHP</acronym> Array) internally the <methodname>render()</methodname> is used to
 149         build the configuration string. This method can be used from the outside also if you need
 150         to access the string-representation of the configuration data.
 151     </para>
 152 </sect1>
 153 <!--
 154 vim:se ts=4 sw=4 et:
 155 -->