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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.config.introduction">
   4     <title>Introduction</title>
   5
   6     <para>
   7         <classname>Zend_Config</classname> is designed to simplify the access to, and the use of,
   8         configuration data within applications. It provides a nested object property based user
   9         interface for accessing this configuration data within application code. The configuration
  10         data may come from a variety of media supporting hierarchical data storage. Currently
  11         <classname>Zend_Config</classname> provides adapters for configuration data that are stored
  12         in text files with <link
  13             linkend="zend.config.adapters.ini"><classname>Zend_Config_Ini</classname></link> and
  14         <link linkend="zend.config.adapters.xml"><classname>Zend_Config_Xml</classname></link>.
  15     </para>
  16
  17     <example id="zend.config.introduction.example.using">
  18         <title>Using Zend_Config</title>
  19
  20         <para>
  21             Normally it is expected that users would use one of the adapter classes such as <link
  22                 linkend="zend.config.adapters.ini"><classname>Zend_Config_Ini</classname></link> or
  23             <link linkend="zend.config.adapters.xml"><classname>Zend_Config_Xml</classname></link>,
  24             but if configuration data are available in a <acronym>PHP</acronym> array, one may
  25             simply pass the data to the <classname>Zend_Config</classname> constructor in order to
  26             utilize a simple object-oriented interface:
  27         </para>
  28
  29         <programlisting language="php"><![CDATA[
  30 // Given an array of configuration data
  31 $configArray = array(
  32     'webhost'  => 'www.example.com',
  33     'database' => array(
  34         'adapter' => 'pdo_mysql',
  35         'params'  => array(
  36             'host'     => 'db.example.com',
  37             'username' => 'dbuser',
  38             'password' => 'secret',
  39             'dbname'   => 'mydatabase'
  40         )
  41     )
  42 );
  43
  44 // Create the object-oriented wrapper upon the configuration data
  45 $config = new Zend_Config($configArray);
  46
  47 // Print a configuration datum (results in 'www.example.com')
  48 echo $config->webhost;
  49
  50 // Use the configuration data to connect to the database
  51 $db = Zend_Db::factory($config->database->adapter,
  52                        $config->database->params->toArray());
  53
  54 // Alternative usage: simply pass the Zend_Config object.
  55 // The Zend_Db factory knows how to interpret it.
  56 $db = Zend_Db::factory($config->database);
  57 ]]></programlisting>
  58     </example>
  59
  60     <para>
  61         As illustrated in the example above, <classname>Zend_Config</classname> provides nested
  62         object property syntax to access configuration data passed to its constructor.
  63     </para>
  64
  65     <para>
  66         Along with the object oriented access to the data values,
  67         <classname>Zend_Config</classname> also has <methodname>get()</methodname> which will
  68         return the supplied default value if the data element doesn't exist. For example:
  69     </para>
  70
  71     <programlisting language="php"><![CDATA[
  72 $host = $config->database->get('host', 'localhost');
  73 ]]></programlisting>
  74
  75     <example id="zend.config.introduction.example.file.php">
  76         <title>Using Zend_Config with a PHP Configuration File</title>
  77
  78         <para>
  79             It is often desirable to use a pure <acronym>PHP</acronym>-based configuration file.
  80             The following code illustrates how easily this can be accomplished:
  81         </para>
  82
  83         <programlisting language="php"><![CDATA[
  84 // config.php
  85 return array(
  86     'webhost'  => 'www.example.com',
  87     'database' => array(
  88         'adapter' => 'pdo_mysql',
  89         'params'  => array(
  90             'host'     => 'db.example.com',
  91             'username' => 'dbuser',
  92             'password' => 'secret',
  93             'dbname'   => 'mydatabase'
  94         )
  95     )
  96 );
  97 ]]></programlisting>
  98
  99         <programlisting language="php"><![CDATA[
 100 // Configuration consumption
 101 $config = new Zend_Config(require 'config.php');
 102
 103 // Print a configuration datum (results in 'www.example.com')
 104 echo $config->webhost;
 105 ]]></programlisting>
 106     </example>
 107 </sect1>
 108 <!--
 109 vim:se ts=4 sw=4 et:
 110 -->