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

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

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

        <para>
            <ulink url="http://www.json.org/">JSON</ulink> is an acronym for "JavaScript Object
            Notation"; while compatible with JavaScript, it is also intended as a general-purpose,
            cross-language data interchange format.  <classname>Zend_Config_Json</classname> is a
            lightweight <classname>Zend_Config</classname> extension using <acronym>JSON</acronym>
            as its serialization format.
        </para>
    </sect2>

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

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

        <programlisting language="json"><![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_Json</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_Json(
    APPLICATION_PATH . '/configs/application.json',
    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>

        <warning>
            <title>Use Constants With Care</title>

            <para>
                <acronym>JSON</acronym> has a strict structure with regards to data types. As such,
                you need to ensure that your constants are use correctly. For constants that have
                string values, put your constant values in double quotes (""). For non-string
                values, you can omit the quotes -- but be absolutely certain that they are not
                returning strings, as otherwise you will encounter parser errors with your
                configuration file. When in doubt, enclose the contant in double quotes.
            </para>
        </warning>
    </sect2>

    <sect2 id="zend.config.adapters.json.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_Json Options</title>

            <varlistentry>
                <term>allow_modifications/allowModifications</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/skipExtends</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_Json</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>

                    <para>
                        Please note that ignoring constants can potentially lead to parse errors,
                        particularly if you are using constants for integer, float, or boolean
                        values. The safest practice is to enclose constants within quotes.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </sect2>

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

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

                <listitem>
                    <para>
                        Constructor. <varname>$json</varname> should be either a valid
                        <acronym>JSON</acronym> string, or refer to a valid filesystem location
                        containing a <acronym>JSON</acronym> 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.json.options">options
                            section</link>.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry id="zend.config.adapters.json.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 <acronym>JSON</acronym>
                        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.json.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>
</sect1>