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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.config.introduction">
    <title>Introduction</title>

    <para>
        <classname>Zend_Config</classname> is designed to simplify the access to, and the use of,
        configuration data within applications. It provides a nested object property based user
        interface for accessing this configuration data within application code. The configuration
        data may come from a variety of media supporting hierarchical data storage. Currently
        <classname>Zend_Config</classname> provides adapters for configuration data that are stored
        in text files with <link
            linkend="zend.config.adapters.ini"><classname>Zend_Config_Ini</classname></link> and
        <link linkend="zend.config.adapters.xml"><classname>Zend_Config_Xml</classname></link>.
    </para>

    <example id="zend.config.introduction.example.using">
        <title>Using Zend_Config</title>

        <para>
            Normally it is expected that users would use one of the adapter classes such as <link
                linkend="zend.config.adapters.ini"><classname>Zend_Config_Ini</classname></link> or
            <link linkend="zend.config.adapters.xml"><classname>Zend_Config_Xml</classname></link>,
            but if configuration data are available in a <acronym>PHP</acronym> array, one may
            simply pass the data to the <classname>Zend_Config</classname> constructor in order to
            utilize a simple object-oriented interface:
        </para>

        <programlisting language="php"><![CDATA[
// Given an array of configuration data
$configArray = array(
    'webhost'  => 'www.example.com',
    'database' => array(
        'adapter' => 'pdo_mysql',
        'params'  => array(
            'host'     => 'db.example.com',
            'username' => 'dbuser',
            'password' => 'secret',
            'dbname'   => 'mydatabase'
        )
    )
);

// Create the object-oriented wrapper upon the configuration data
$config = new Zend_Config($configArray);

// Print a configuration datum (results in 'www.example.com')
echo $config->webhost;

// Use the configuration data to connect to the database
$db = Zend_Db::factory($config->database->adapter,
                       $config->database->params->toArray());

// Alternative usage: simply pass the Zend_Config object.
// The Zend_Db factory knows how to interpret it.
$db = Zend_Db::factory($config->database);
]]></programlisting>
    </example>

    <para>
        As illustrated in the example above, <classname>Zend_Config</classname> provides nested
        object property syntax to access configuration data passed to its constructor.
    </para>

    <para>
        Along with the object oriented access to the data values,
        <classname>Zend_Config</classname> also has <methodname>get()</methodname> which will
        return the supplied default value if the data element doesn't exist. For example:
    </para>

    <programlisting language="php"><![CDATA[
$host = $config->database->get('host', 'localhost');
]]></programlisting>

    <example id="zend.config.introduction.example.file.php">
        <title>Using Zend_Config with a PHP Configuration File</title>

        <para>
            It is often desirable to use a pure <acronym>PHP</acronym>-based configuration file.
            The following code illustrates how easily this can be accomplished:
        </para>

        <programlisting language="php"><![CDATA[
// config.php
return array(
    'webhost'  => 'www.example.com',
    'database' => array(
        'adapter' => 'pdo_mysql',
        'params'  => array(
            'host'     => 'db.example.com',
            'username' => 'dbuser',
            'password' => 'secret',
            'dbname'   => 'mydatabase'
        )
    )
);
]]></programlisting>

        <programlisting language="php"><![CDATA[
// Configuration consumption
$config = new Zend_Config(require 'config.php');

// Print a configuration datum (results in 'www.example.com')
echo $config->webhost;
]]></programlisting>
    </example>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->