documentation/manual/en/module_specs/Zend_Config-TheoryOfOperation.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.config.theory_of_operation">
   4     <title>Theory of Operation</title>
   5
   6     <para>
   7         Configuration data are made accessible to the <classname>Zend_Config</classname> constructor
   8         through an associative array, which may be multi-dimensional, in order to support
   9         organizing the data from general to specific. Concrete adapter classes
  10         adapt configuration data from storage to produce the associative array for the
  11         <classname>Zend_Config</classname> constructor. User scripts may provide such arrays
  12         directly to the <classname>Zend_Config</classname> constructor, without using an adapter
  13         class, since it may be appropriate to do so in certain situations.
  14     </para>
  15
  16     <para>
  17         Each configuration data array value becomes a property of the
  18         <classname>Zend_Config</classname> object. The key is used as the property name. If a value
  19         is itself an array, then the resulting object property is created as a new
  20         <classname>Zend_Config</classname> object, loaded with the array data. This occurs
  21         recursively, such that a hierarchy of configuration data may be created with any number of
  22         levels.
  23     </para>
  24
  25     <para>
  26         <classname>Zend_Config</classname> implements the <emphasis>Countable</emphasis> and
  27         <emphasis>Iterator</emphasis> interfaces in order to facilitate simple access to
  28         configuration data. Thus, one may use the
  29         <ulink url="http://php.net/count"><methodname>count()</methodname></ulink>
  30         function and <acronym>PHP</acronym> constructs such as
  31         <ulink url="http://php.net/foreach"><emphasis>foreach</emphasis></ulink> with
  32         <classname>Zend_Config</classname> objects.
  33     </para>
  34
  35     <para>
  36         By default, configuration data made available through <classname>Zend_Config</classname> are
  37         read-only, and an assignment (e.g.,
  38         <command>$config->database->host = 'example.com';</command>)
  39         results in a thrown exception. This default behavior may be overridden through the
  40         constructor, however, to allow modification of data values. Also, when modifications are
  41         allowed, <classname>Zend_Config</classname> supports unsetting of values (i.e.
  42         <methodname>unset($config->database->host)</methodname>). The
  43         <methodname>readOnly()</methodname> method can be used to determine if modifications to a
  44         given <classname>Zend_Config</classname> object are allowed and the
  45         <methodname>setReadOnly()</methodname> method can be used to stop any further modifications
  46         to a <classname>Zend_Config</classname> object that was created allowing modifications.
  47     </para>
  48
  49     <note>
  50         <para>
  51             It is important not to confuse such in-memory modifications with saving
  52             configuration data out to specific storage media. Tools for creating and modifying
  53             configuration data for various storage media are out of scope with respect to
  54             <classname>Zend_Config</classname>. Third-party open source solutions are readily
  55             available for the purpose of creating and modifying configuration data for various
  56             storage media.
  57         </para>
  58     </note>
  59
  60     <para>
  61         Adapter classes inherit from the <classname>Zend_Config</classname> class since they utilize
  62         its functionality.
  63     </para>
  64
  65     <para>
  66         The <classname>Zend_Config</classname> family of classes enables configuration data to be
  67         organized into sections. <classname>Zend_Config</classname> adapter objects may be loaded
  68         with a single specified section, multiple specified sections, or all sections
  69         (if none are specified).
  70     </para>
  71
  72     <para>
  73         <classname>Zend_Config</classname> adapter classes support a single inheritance model that
  74         enables configuration data to be inherited from one section of configuration data
  75         into another. This is provided in order to reduce or eliminate the need for
  76         duplicating configuration data for different purposes. An inheriting section
  77         may also override the values that it inherits through its parent section.
  78         Like <acronym>PHP</acronym> class inheritance, a section may inherit from a parent section,
  79         which may inherit from a grandparent section, and so on, but multiple inheritance
  80         (i.e., section C inheriting directly from parent sections A and B) is not supported.
  81     </para>
  82
  83     <para>
  84         If you have two <classname>Zend_Config</classname> objects, you can merge them into a single
  85         object using the <methodname>merge()</methodname> function. For example, given
  86         <varname>$config</varname> and <varname>$localConfig</varname>, you can merge data from
  87         <varname>$localConfig</varname> to <varname>$config</varname> using
  88         <command>$config->merge($localConfig);</command>. The items in
  89         <varname>$localConfig</varname> will override any items with the same name in
  90         <varname>$config</varname>.
  91     </para>
  92
  93     <note>
  94         <para>
  95             The <classname>Zend_Config</classname> object that is performing the merge must have
  96             been constructed to allow modifications, by passing <constant>TRUE</constant> as the
  97             second parameter of the constructor. The <methodname>setReadOnly()</methodname>
  98             method can then be used to prevent any further modifications after the merge is
  99             complete.
 100         </para>
 101     </note>
 102 </sect1>
 103 <!--
 104 vim:se ts=4 sw=4 et:
 105 -->