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

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

    <para>
        <classname>Zend_Config_Xml</classname> permite aos desenvolvedores armazenarem os dados de
        configuração em um formato <acronym>XML</acronym> simples e lê-los através de uma sintaxe
        de propriedade de objeto aninhado. O nome do elemento raiz do arquivo ou string
        <acronym>XML</acronym> é irrelevante e pode ser escolhido. O primeiro nível dos elementos
        <acronym>XML</acronym> corresponde às seções de dados de configuração. O formato
        <acronym>XML</acronym> suporta organização hierárquica para o aninhamento dos elementos
        <acronym>XML</acronym> abaixo dos elementos de seção-nível. O conteúdo de uma folha de
        elemento <acronym>XML</acronym> (leaf) corresponde ao valor de um dado de configuração.
        Herança de seção é suportada por um atributo <acronym>XML</acronym> especial chamado
        <emphasis>extends</emphasis>, e o valor deste atributo corresponde à seção a que a
        informação deve ser herdada.
    </para>

    <note>
        <title>Tipo de Retorno</title>

        <para>
            Os dados de configuração lidos em <classname>Zend_Config_Xml</classname> são sempre
            retornados como strings. A conversão de dados de strings para outros tipos é deixado
            para os desenvolvedores de acordo com suas necessidades específicas.
        </para>
    </note>

    <example id="zend.config.adapters.xml.example.using">
        <title>Usando o Zend_Config_Xml</title>

        <para>
            Este exemplo ilustra uma utilização básica de <classname>Zend_Config_Xml</classname>
            para carregar dados de configuração de um arquivo <acronym>XML</acronym>. Neste
            exemplo, existem dados de configuração, tanto para um sistema de produção como para um
            sistema de testes. Pois os dados de configuração de um sistema de testes são muito
            semelhantes aos de produção, a seção de testes herda da seção de produção. Neste caso,
            a decisão é arbitrária e poderia ter sido escrita de modo inverso, com a seção de
            produção herdando da seção de testes, embora isso possa não ser o caso em situações
            mais complexas. Suponha-se, então, que os dados de configuração a seguir estão
            contidos em <filename>/path/to/config.xml</filename>:
        </para>

        <programlisting language="xml"><![CDATA[
<?xml version="1.0"?>
<configdata>
    <production>
        <webhost>www.example.com</webhost>
        <database>
            <adapter>pdo_mysql</adapter>
            <params>
                <host>db.example.com</host>
                <username>dbuser</username>
                <password>secret</password>
                <dbname>dbname</dbname>
            </params>
        </database>
    </production>
    <staging extends="production">
        <database>
            <params>
                <host>dev.example.com</host>
                <username>devuser</username>
                <password>devsecret</password>
            </params>
        </database>
    </staging>
</configdata>
]]></programlisting>

        <para>
            Em seguida, suponha que o desenvolvedor do aplicativo necessite dos dados de
            configuração de testes do arquivo <acronym>XML</acronym>. É o simples caso de carregar
            esses dados especificando o arquivo <acronym>XML</acronym> e a seção de testes:
        </para>

        <programlisting language="php"><![CDATA[
$config = new Zend_Config_Xml('/path/to/config.xml', 'staging');

echo $config->database->params->host;   // prints "dev.example.com"
echo $config->database->params->dbname; // prints "dbname"
]]></programlisting>
    </example>

    <example id="zend.config.adapters.xml.example.attributes">
        <title>Usando os Atributos de Tag no Zend_Config_Xml</title>

        <para>
            <classname>Zend_Config_Xml</classname> também suporta outras duas maneiras para definir
            os nós na configuração. Ambas fazem uso de atributos. A partir do momento que os
            atributos <emphasis>extends</emphasis> e <emphasis>value</emphasis> são palavras-chaves
            reservadas (o último através segunda maneira de uso dos atributos), eles não poderão
            ser utilizados. A primeira maneira usar os atributos é adicionar um nó pai, assim eles
            serão interpretados como um filho deste nó:
        </para>

        <programlisting language="xml"><![CDATA[
<?xml version="1.0"?>
<configdata>
    <production webhost="www.example.com">
        <database adapter="pdo_mysql">
            <params host="db.example.com" username="dbuser" password="secret"
                    dbname="dbname"/>
        </database>
    </production>
    <staging extends="production">
        <database>
            <params host="dev.example.com" username="devuser"
                    password="devsecret"/>
        </database>
    </staging>
</configdata>
]]></programlisting>

        <para>
            A outra maneira não encurta realmente a configuração, mas a torna mais fácil para
            manter, pois você não tem que escrever o nome da tag duas vezes. Você simplesmente cria
            uma tag vazia com o valor no atributo <emphasis>value</emphasis>:
        </para>

        <programlisting language="xml"><![CDATA[
<?xml version="1.0"?>
<configdata>
    <production>
        <webhost>www.example.com</webhost>
        <database>
            <adapter value="pdo_mysql"/>
            <params>
                <host value="db.example.com"/>
                <username value="dbuser"/>
                <password value="secret"/>
                <dbname value="dbname"/>
            </params>
        </database>
    </production>
    <staging extends="production">
        <database>
            <params>
                <host value="dev.example.com"/>
                <username value="devuser"/>
                <password value="devsecret"/>
            </params>
        </database>
    </staging>
</configdata>
]]></programlisting>
    </example>

    <note>
        <title>Strings XML</title>

        <para>
            <classname>Zend_Config_Xml</classname> é capaz de carregar uma string
            <acronym>XML</acronym> diretamente, por exemplo, uma que foi recuperada de um banco de
            dados. A string é passada como primeiro parâmetro para o construtor e deve começar com
            os caracteres <emphasis>'&lt;?xml'</emphasis>:
        </para>

        <programlisting language="xml"><![CDATA[
$string = <<<EOT
<?xml version="1.0"?>
<config>
    <production>
        <db>
            <adapter value="pdo_mysql"/>
            <params>
                <host value="db.example.com"/>
            </params>
        </db>
    </production>
    <staging extends="production">
        <db>
            <params>
                <host value="dev.example.com"/>
            </params>
        </db>
    </staging>
</config>
EOT;

$config = new Zend_Config_Xml($string, 'staging');
]]></programlisting>
    </note>

    <note>
        <title>Namespace XML do Zend_Config</title>

        <para>
            <classname>Zend_Config</classname> vem com sua próprio namespace <acronym>XML</acronym>,
            que adiciona funcionalidade adicional ao processo de análise. Para aproveitá-la, você
            tem que definir um namespace com o namespace <acronym>URI</acronym>
            <filename>http://framework.zend.com/xml/zend-config-xml/1.0/</filename> em seu nó raiz
            de configuração.
        </para>

        <para>
            Com o namespace habilitado, você pode usar constantes do <acronym>PHP</acronym> dentro
            de arquivos de configuração. Além disso, o atributo <emphasis>extends</emphasis> foi
            transferido para um novo namespace e está depreciado no namespace
            <constant>NULL</constant>. Ele será completamente removido no Zend Framework 2.0.
        </para>

        <programlisting language="xml"><![CDATA[
$string = <<<EOT
<?xml version="1.0"?>
<config xmlns:zf="http://framework.zend.com/xml/zend-config-xml/1.0/">
    <production>
        <includePath>
            <zf:const zf:name="APPLICATION_PATH"/>/library</includePath>
        <db>
            <adapter value="pdo_mysql"/>
            <params>
                <host value="db.example.com"/>
            </params>
        </db>
    </production>
    <staging zf:extends="production">
        <db>
            <params>
                <host value="dev.example.com"/>
            </params>
        </db>
    </staging>
</config>
EOT;

define('APPLICATION_PATH', dirname(__FILE__));
$config = new Zend_Config_Xml($string, 'staging');

echo $config->includePath; // Prints "/var/www/something/library"
]]></programlisting>
    </note>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->