repo_zf1/documentation/manual/ja/module_specs/Zend_Config_Writer.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24604 -->
<sect1 id="zend.config.writer.introduction">
    <title>Zend_Config_Writer(日本語)</title>

    <para>
        <classname>Zend_Config_Writer</classname> は、設定ファイルに
        <classname>Zend_Config</classname> オブジェクトを書き出します。
        アダプタなしでも動作するので、使用するのも簡単です。
        デフォルトでは <classname>Zend_Config_Writer</classname>
        には 4 種類のアダプタが同梱されており、全てファイル・ベースです。
        まず、<emphasis>filename</emphasis> や <emphasis>config</emphasis>
        のオプションを指定してライターのインスタンスを作成します。
        それからライターの <methodname>write()</methodname> メソッドをコールすると、
        設定ファイルが作成されます。<varname>$filename</varname> や
        <varname>$config</varname> を、直接 <methodname>write()</methodname>
        メソッドで設定することもできます。現在は、次のライターが
        <classname>Zend_Config_Writer</classname> に同梱されています。
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <classname>Zend_Config_Writer_Array</classname>
            </para>
        </listitem>

        <listitem>
            <para>
                <classname>Zend_Config_Writer_Ini</classname>
            </para>
        </listitem>

         <listitem>
             <para>
                <classname>Zend_Config_Writer_Json</classname>
            </para>
        </listitem>

        <listitem>
            <para>
                <classname>Zend_Config_Writer_Xml</classname>
            </para>
        </listitem>

        <listitem>
            <para>
                <classname>Zend_Config_Writer_Yaml</classname>
            </para>
        </listitem>
    </itemizedlist>

    <para>
        <classname>Zend_Config</classname> オブジェクトを変更したり作成したりする際には、
        知っておくべきことがあります。値を作成したり変更したりするには、
        パラメータのアクセサ (<emphasis>-&gt;</emphasis>) で <classname>Zend_Config</classname>
        オブジェクトのパラメータを設定します。
        ルート内のセクションやブランチを作成するには、新規配列を作成します
        ("<command>$config-&gt;branch = array();</command>")。
        セクションの継承関係を定義するには、ルート
        <classname>Zend_Config</classname> オブジェクトの
        <methodname>setExtend()</methodname> メソッドをコールします。
    </para>

    <example id="zend.config.writer.example.using">
        <title>Zend_Config_Writer の使用法</title>

        <para>
            この例では、<classname>Zend_Config_Writer_Xml</classname>
            で新しい設定ファイルを作成する方法を説明します。
        </para>

        <programlisting language="php"><![CDATA[
// config オブジェクトを作成します
$config = new Zend_Config(array(), true);
$config->production = array();
$config->staging    = array();

$config->setExtend('staging', 'production');

$config->production->db = array();
$config->production->db->hostname = 'localhost';
$config->production->db->username = 'production';

$config->staging->db = array();
$config->staging->db->username = 'staging';

// 次のいずれかの方法で設定ファイルを書き出します
// a)
$writer = new Zend_Config_Writer_Xml(array('config'   => $config,
                                           'filename' => 'config.xml'));
$writer->write();

// b)
$writer = new Zend_Config_Writer_Xml();
$writer->setConfig($config)
       ->setFilename('config.xml')
       ->write();

// c)
$writer = new Zend_Config_Writer_Xml();
$writer->write('config.xml', $config);
]]></programlisting>

        <para>
            これは、production と staging というセクションを持つ <acronym>XML</acronym>
            設定ファイルを作成します。staging は production を継承しています。
        </para>
    </example>

    <example id="zend.config.writer.modifying">
        <title>既存の設定の変更</title>

        <para>
            この例では、既存の設定ファイルを編集する方法を説明します。
        </para>

        <programlisting language="php"><![CDATA[
// すべてのセクションを既存の設定ファイルから読み込みますが継承は読み飛ばします
$config = new Zend_Config_Ini('config.ini',
                              null,
                              array('skipExtends'        => true,
                                    'allowModifications' => true));

// 値を変更します
$config->production->hostname = 'foobar';

// 設定ファイルを書き出します
$writer = new Zend_Config_Writer_Ini(array('config'   => $config,
                                           'filename' => 'config.ini'));
$writer->write();
]]></programlisting>
    </example>

    <note>
        <title>設定ファイルの読み込み</title>
        <para>
            既存の設定ファイルを読み込んで変更をする場合は、
            すべてのセクションを読み込んで継承を読み飛ばすことが大切です。
            そうすることで、値がマージされてしまうことがなくなります。
            そのために、コンストラクタで
            <emphasis>skipExtends</emphasis> オプションを指定します。
        </para>
    </note>

    <para>
        構成節の文字列を作成するために、ファイル・ベースのライタ
        （ <acronym>INI</acronym> 、 <acronym>JSON</acronym>、<acronym>XML</acronym>、
        <acronym>YAML</acronym> 及び <acronym>PHP</acronym> 配列）
        全てで内部的に <methodname>render()</methodname> が使用されます。
        コンフィギュレーション・データの文字列表現にアクセスするために
        このメソッドをそれぞれ使用できます。
    </para>

    <sect2 id="zend.config.writer.introduction.ini-notes">
        <title>INI ライター特有の注意</title>

        <itemizedlist>
            <listitem>
                <para>
                    <acronym>INI</acronym> ライターでは、セクションについてのレンダリング用のモードが２つあります。
                    既定では、トップレベルの構成節は、常にセクション名に含まれます。
                    <command>$writer->setRenderWithoutSections()</command> を呼ぶことにより、
                    オプションの全てが <acronym>INI</acronym> ファイルのグローバル名前空間に含まれます。
                    そして、セクションは使用されません。
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Config_Writer_Ini</classname> にはオプションのパラメータ
                    <emphasis>nestSeparator</emphasis> が用意されています。
                    これは、ノードを区切る文字を定義します。デフォルトはドットひとつで、
                    これは <classname>Zend_Config_Ini</classname> によりデフォルトで受け付けられます。
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.config.writer.introduction.yaml-notes">
        <title>YAML ライター特有の注意</title>

        <!-- TODO : to be translated -->
        <para>
            The <acronym>YAML</acronym> writer lets you optionally specify an alternate
            <acronym>YAML</acronym> encoder to use. By default, one is shipped with the framework
            that is suitable for most configuration tasks. If you find it insufficient, or wish to
            use more advanced YAML, you may provide an alternate encoder callback.
        </para>

        <para>
            The method for doing so is to use the
            <methodname>Zend_Config_Writer_Yaml::setYamlEncoder()</methodname> method, passing it a
            valid callback.
        </para>

        <programlisting language="php"><![CDATA[
// Use the Symfony Yaml Component:
$writer = new Zend_Config_Writer_Yaml($filename);
$writer->setYamlEncoder(array('sfYaml', 'dump'));
]]></programlisting>

        <para>
            The above uses the Symfony Components' <classname>sfYaml</classname> component in order
            to encode the configuration to <acronym>YAML</acronym>.
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->