repo_zf1/documentation/manual/en/module_specs/Zend_Config_Yaml.xml

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

    <sect2 id="zend.config.adapters.yaml.intro">
        <title>Overview</title>

        <para>
            <ulink url="http://www.yaml.org/">YAML</ulink> is a recursive acronym meaning "YAML
            Ain't Markup Language", and is intended as a "human friendly data serialization
            standard for all programming languages." It is often used for application configuration.
        </para>

        <para>
            <classname>Zend_Config_Yaml</classname> is a lightweight
            <classname>Zend_Config</classname> extension. It includes a parser capable of
            recognizing most common YAML syntax used for purposes of configuration, and allows
            specifying other parsers should you want more complex syntax (e.g., ext/syck, spyc,
            sfYaml, etc.).
        </para>
    </sect2>

    <sect2 id="zend.config.adapters.yaml.quick-start">
        <title>Quick Start</title>

        <para>
            The following is a YAML version of a standard application configuration.
        </para>

        <programlisting language="yaml"><![CDATA[
production:
  phpSettings:
    display_startup_errors: false
    display_errors: false
  includePaths:
    library: APPLICATION_PATH/../library
  bootstrap:
    path: APPLICATION_PATH/Bootstrap.php
    class: "Bootstrap"
  appnamespace: "Application"
  resources:
    frontController:
      controllerDirectory: APPLICATION_PATH/controllers
      moduleDirectory: APPLICATION_PATH/modules
      params:
        displayExceptions: false
    modules:
    db:
      adapter: "pdo_sqlite"
      params:
        dbname: APPLICATION_PATH/../data/db/application.db
    layout:
      layoutPath: APPLICATION_PATH/layouts/scripts/

staging:
  _extends: production

testing:
  _extends: production
  phpSettings:
    display_startup_errors: true
    display_errors: true

development:
  _extends: production
  phpSettings:
    display_startup_errors: true
    display_errors: true
  resources:
    frontController:
      params:
        displayExceptions: true
]]></programlisting>

        <para>
            To utilize it, you simply instantiate <classname>Zend_Config_Yaml</classname>, pointing
            it to the location of this file and indicating the section of the file to load. By
            default, constant names found in values will be substituted with their appropriate
            values.
        </para>

        <programlisting language="php"><![CDATA[
$config = new Zend_Config_Yaml(
    APPLICATION_PATH . '/configs/application.yaml',
    APPLICATION_ENV
);
]]></programlisting>

        <para>
            Once instantiated, you use it as you would any other configuration object.
        </para>

        <programlisting language="php"><![CDATA[
$db = Zend_Db::factory($config->resources->db);
]]></programlisting>
    </sect2>

    <sect2 id="zend.config.adapters.yaml.options">
        <title>Configuration Options</title>

        <para>
            The following options may be passed as keys to the third, <varname>$options</varname>
            argument of the constructor.
        </para>

        <variablelist>
            <title>Zend_Config_Yaml Options</title>

            <varlistentry>
                <term>allow_modifications</term>

                <listitem>
                    <para>
                        The default behavior of <classname>Zend_Config</classname> is to mark the
                        object as immutable once loaded. Passing this flag with a boolean
                        <constant>true</constant> will enable modifications to the object.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>skip_extends</term>

                <listitem>
                    <para>
                        By default, any time a section extends another,
                        <classname>Zend_Config</classname> will merge the section with the section
                        it extends. Speciying a boolean <constant>true</constant> value to this
                        option will disable this feature, giving you only the configuration defined
                        explicitly in that section.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>ignore_constants</term>

                <listitem>
                    <para>
                        By default, <classname>Zend_Config_Yaml</classname> will replace constant
                        names found in values with the defined constant value. You map pass a
                        boolean <constant>true</constant> to this option to disable this
                        functionality.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>yaml_decoder</term>

                <listitem>
                    <para>
                        By default, <classname>Zend_Config_Yaml</classname> uses a built in decoder,
                        <methodname>Zend_Config_Yaml::decode()</methodname>, to parse and process
                        YAML files. You may specify an alternate callback to use in place of the
                        built-in one using this option.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </sect2>

    <sect2 id="zend.config.adapters.yaml.methods">
        <title>Available Methods</title>

        <variablelist>
            <varlistentry id="zend.config.adapters.yaml.methods.constructor">
                <term>
                    <methodsynopsis>
                        <methodname>__construct</methodname>
                        <methodparam>
                            <funcparams>$yaml, $section = null, $options = false</funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Constructor. <varname>$yaml</varname> should refer to a valid filesystem
                        location containing a YAML configuration file. <varname>$section</varname>,
                        if specified, indicates a specific section of the configuration file to use.
                        <varname>$options</varname> is discussed in the <link
                            linkend="zend.config.adapters.yaml.options">options section</link>.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry id="zend.config.adapters.yaml.methods.decode">
                <term>
                    <methodsynopsis>
                        <methodname>decode</methodname>
                        <methodparam>
                            <funcparams>$yaml</funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Parses a YAML string into a PHP array.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry id="zend.config.adapters.yaml.methods.set-ignore-constants">
                <term>
                    <methodsynopsis>
                        <methodname>setIgnoreConstants</methodname>
                        <methodparam>
                            <funcparams>$flag</funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        This <emphasis>static</emphasis> function may be used to globally override
                        the default settings for how constants found in YAML strings are handled. By
                        default, constant names are replaced with the appropriate constant values;
                        passing a boolean <constant>true</constant> value to this method will
                        override that behavior. (You can override it per-instance via the
                        <varname>ignore_constants</varname> option as well.)
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry id="zend.config.adapters.yaml.methods.ignore-constants">
                <term>
                    <methodsynopsis>
                        <methodname>ignoreConstants</methodname>
                        <methodparam>
                            <funcparams></funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        This <emphasis>static</emphasis> method gives you the current setting for
                        the <varname>ignore_constants</varname> flag.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </sect2>

    <sect2 id="zend.config.adapters.yaml.examples">
        <title>Examples</title>

        <example id="zend.config.adapters.yaml.examples.sf-yaml">
            <title>Using Zend_Config_Yaml with sfYaml</title>

            <para>
                As noted in the <link linkend="zend.config.adapters.yaml.options">options
                    section</link>, <classname>Zend_Config_Yaml</classname> allows you to specify an
                alternate YAML parser at instantiation.
            </para>

            <para>
                <ulink url="http://components.symfony-project.org/yaml/">sfYaml</ulink> is a <ulink
                    url="http://components.symfony-project.org/">Symfony component</ulink> that
                implements a complete YAML parser in PHP, and includes a number of additional
                features including the ability to parse PHP expressions embedded in the YAML. In
                this example, we use the <methodname>sfYaml::load()</methodname> method as our YAML
                decoder callback. <emphasis>(Note: this assumes that the
                    <classname>sfYaml</classname> class is either already loaded or available via
                    autoloading.)</emphasis>
            </para>

            <programlisting language="php"><![CDATA[
$config = new Zend_Config_Yaml(
    APPLICATION_PATH . '/configs/application.yaml',
    APPLICATION_ENV,
    array('yaml_decoder' => array('sfYaml', 'load'))
);
]]></programlisting>
        </example>
    </sect2>
</sect1>