repo_zf1/documentation/manual/pt-br/module_specs/Zend_Config_Writer.xml

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

    <para>
        <classname>Zend_Config_Writer</classname> lhe dá a capacidade de escrever arquivos de
        configuração a partir de objetos <classname>Zend_Config</classname>. Ele funciona com
        adaptadores separados do sistema e muito fáceis de usar. Por padrão, o
        <classname>Zend_Config_Writer</classname> vêm embarcado com quatro adaptadores, que são
        todos baseados em arquivos. Você instanciará um escritor com opções específicas, que podem
        ser <emphasis>filename</emphasis> e <emphasis>config</emphasis>. Em seguida, você irá chamar
        o método <methodname>write()</methodname> do escritor e o arquivo de configuração será
        criado. Você também pode fornecer <varname>$filename</varname> e <varname>$config</varname>
        diretamente ao método <methodname>write()</methodname>. Atualmente os escritores que se
        seguem são fornecidos com <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>
        Ao modificar ou criar um objeto <classname>Zend_Config</classname>, há algumas coisas que se
        deve conhecer. Para criar ou modificar um valor, basta definir o parâmetro do objeto
        <classname>Zend_Config</classname> através do assessor de parâmetro
        (<emphasis>-&gt;</emphasis>). Para criar uma seção na raiz ou para criar um ramo, você
        apenas irá criar uma nova matriz ("<command>$config-&gt;branch = array();</command>"). Para
        definir qual seção estende outra, você chamará o método <methodname>setExtend()</methodname>
        na raiz do objeto <classname>Zend_Config</classname>.
    </para>

    <example id="zend.config.writer.example.using">
        <title>Usando o Zend_Config_Writer</title>

        <para>
            Este exemplo ilustra a utilização básica de
            <classname>Zend_Config_Writer_Xml</classname>
            para criar um novo arquivo de configuração:
        </para>

        <programlisting language="php"><![CDATA[
// Cria o objeto de configuração
$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';

// Escreve o arquivo de configuração em uma das seguintes formas:
// 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>
            Isso criará um arquivo de configuração <acronym>XML</acronym> com as seções de produção
            e de testes, onde testes estende produção.
        </para>
    </example>

    <example id="zend.config.writer.modifying">
        <title>Modificando uma Configuração Existente</title>

        <para>
            Este exemplo demonstra como editar um arquivo de configuração existente.
        </para>

        <programlisting language="php"><![CDATA[
// Carrega todas as seções de um arquivo de configuração
// existente, enquanto pula o que é estendido.
$config = new Zend_Config_Ini('config.ini',
                              null,
                              array('skipExtends'        => true,
                                    'allowModifications' => true));

// Modifica um valor
$config->production->hostname = 'foobar';

// Escreve o arquivo de configuração
$writer = new Zend_Config_Writer_Ini(array('config'   => $config,
                                           'filename' => 'config.ini'));
$writer->write();
]]></programlisting>
    </example>

    <note>
        <title>Carregando um Arquivo de Configuração</title>

        <para>
            Ao carregar um arquivo de configuração existente para modificações, é muito importante
            que se carregue todas as seções e que se pule tudo o que é estendido, para que valores
            não sejam fundidos. Isto é feito passando o <emphasis>skipExtends</emphasis> como opção
            para o construtor.
        </para>
    </note>

    <para>
        Para todos os escritores baseados em arquivo (<acronym>INI</acronym>,
        <acronym>JSON</acronym>, <acronym>XML</acronym>, <acronym>YAML</acronym> e Matriz
        <acronym>PHP</acronym>) internamente o <methodname>render()</methodname> é usado para
        construir a string de configuração. Este método pode ser usado de forma independente para
        acessar a string de representação dos dados de configuração.
    </para>

    <sect2 id="zend.config.writer.introduction.ini-notes">
        <title>Notes specific to the INI writer</title>

        <itemizedlist>
            <listitem>
                <para>
                    The <acronym>INI</acronym> writer has two modes for rendering with regard to
                    sections.  By default the top-level configuration is always written into section
                    names.  By calling <command>$writer->setRenderWithoutSections();</command> all
                    options are written into the global namespace of the <acronym>INI</acronym> file
                    and no sections are applied.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Config_Writer_Ini</classname> has an additional option parameter
                    <emphasis>nestSeparator</emphasis>, which defines with which character the
                    single nodes are separated. The default is a single dot, which is accepted by
                    <classname>Zend_Config_Ini</classname> by default.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.config.writer.introduction.yaml-notes">
        <title>Notes specific to the YAML writer</title>

        <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:
-->