repo_zf1/documentation/manual/pt-br/module_specs/Zend_Tool-Extending.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24346 -->
<!-- Reviewed: no -->
<sect1 id="zend.tool.extending">
    <title>Extendendo o Zend_Tool</title>

    <sect2 id="zend.tool.extending.overview">
        <title>Visão Geral do Zend_Tool</title>

        <para>
            <classname>Zend_Tool_Framework</classname> é uma framework para expor as funcionalidades
            comuns, tais como a criação da estrutura do projeto, geração de código, geração de
            índice de pesquisa, e muito mais. Funcionalmente pode ser escrito e exposto por meio de
            classes <acronym>PHP</acronym> dentro do <property>include_path</property> do <acronym>PHP</acronym>,
            permitindo uma flexibilidade incrível de implementação. A funcionalidade pode ser consumida
            escrevendo implementação e/ou clientes de protocolo-específico -- tais como clientes console,
            <acronym>XML-RPC</acronym>, <acronym>SOAP</acronym>, e muito mais.
        </para>

        <para>
            <classname>Zend_Tool_Project</classname> desenvolve e amplia os recursos do
            <classname>Zend_Tool_Framework</classname> ao de gerenciar um "projeto". Em geral,
            um "projeto" é um esforço planejado ou uma iniciativa. No mundo da informática, projetos
            em geral são uma coleção de recursos. Esses recursos podem ser arquivos, diretórios,
            bases de dados, esquemas, imagens, estilos e muito mais.
        </para>
    </sect2>

    <sect2 id="zend.tool.extending.zend-tool-framework">
        <title>Extensões do Zend_Tool_Framework</title>

        <sect3 id="zend.tool.extending.zend-tool-framework.architecture">
            <title>Arquitetura Geral</title>

            <para>
                <classname>Zend_Tool_Framework</classname> fornece o seguinte:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>Interfaces comuns e abstratas</emphasis> que permitem a
                        desenvolvedores criar funcionalidades e capacidades que são
                        invocadas por clientes da ferramenta.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Funcionalidade base de clientes</emphasis> e uma implementação
                        concreta do console que conectam ferramentas externas e interfaces para o
                        Zend_Tool_Framework. O cliente do console pode ser utilizado em ambientes CLI,
                        como console unix e o console do Windows.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Interfaces de "Provider" e "Manifest"</emphasis> que
                        podem ser usadas pela ferramenta do sistema. "Providers" representam o
                        aspecto functional do framework, e define as ações que os clientes
                        da ferramenta podem chamar. "Manifests" age como registros de metadados
                        que proveem contexto adicional para os vários providers definidos.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Um sistema de loading introspectivo</emphasis> que irá
                        examinar o ambiente a procura de providers e determinar o que é necessário
                        para chama-los.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Uma conjunto padrão de sistemas de providers</emphasis> que
                        permite o sistema relatar o que todos os recursos do sistemas são, bem como
                        fornecer um feedback útil. Ele também inclui um compreessível "Systema de Ajuda".
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                Definições que você deve estar ciente de através deste manual com relação
                ao <classname>Zend_Tool_Framework</classname> incluem:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <classname>Zend_Tool_Framework</classname> - O framework que expõe
                        recursos da ferramenta.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Tooling Client</emphasis> - Uma ferramenta de desenvolvimento que se conecta
                        ao e consome <classname>Zend_Tool_Framework</classname>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Client</emphasis> - O subsistema do
                        <classname>Zend_Tool_Framework</classname> que expoe uma interface tal que
                        tooling clients podem conectar, pesquisar e executar comandos.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Console Client / Command Line Interface /
                        <filename>zf.php</filename></emphasis> - A tooling client para a linha
                        de comando.</para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Provider</emphasis> - Um subsistema e uma coleção de funcionalidades
                        internas que o framework exporta.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Manifest</emphasis> - Um subsistema para definição,
                        organização, e divulgação de dados exigidos pelo provider.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>Zend_Tool_Project</classname> Provider - Um conjunto de providers
                        especificamente para criação e manutenção de projetos baseados no Zend Framework.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.tool.extending.zend-tool-framework.cli-client">
            <title>Entendendo o Cliente CLI</title>

            <para>
                A <acronym>CLI</acronym>, ou ferramenta de linha de comando (internamente
                conhecida como ferramenta de console), é atualmente a interface primária para enviar
                pedidos ao <classname>Zend_Tool</classname> requests. Com a ferramenta <acronym>CLI</acronym>,
                desenvolvedores podem enviar pedidos para a ferramenta dentro da "janela de linha de comando", também
                comumente conhecida como janela do "terminal". Este ambiente é predominante em
                embientes *unix, mas também tem uma implementação comum no Windows como o
                <filename>cmd.exe</filename>, console2 e também com o projeto Cygwin.
            </para>

            <sect4 id="zend.tool.extending.zend-tool-framework.cli-client.setup-general">
                <title>Configuração da ferramenta CLI</title>

                <para>
                    Para distribuir pedidos via cliente de linha de comando, primeiro você
                    precisa configurar o cliente para que seu sistema possa manipular os
                    comandos "zf". O cliente de linha de comando, para todos as intenções e
                    propósitos, é o arquivo <filename>.sh</filename> ou <filename>.bat</filename>
                    que é provido com a sua distribuição do Zend Framework. No trunk, ele pode ser
                    encontrado aqui:
                    <ulink
                        url="http://framework.zend.com/svn/framework/standard/trunk/bin/">http://framework.zend.com/svn/framework/standard/trunk/bin/</ulink>.
                </para>

                <para>
                    Como você pode ver, existem 3 arquivos no diretório <filename>/bin/</filename>:
                    <filename>zf.php</filename>, <filename>zf.sh</filename>, e
                    <filename>zf.bat</filename>. O <filename>zf.sh</filename> e o <filename>zf.bat</filename>
                    são os pacotes específicos do sistema operacional: <filename>zf.sh</filename> para ambientes
                    *nix, e <filename>zf.bat</filename> para ambientes Win32. Estes empacotadores clientes são
                    responsáveis por procurar o php.exe correto, achando o <filename>zf.php</filename>, e
                    passando o pedido para o cliente. O <filename>zf.php</filename>, é responsável por
                    manipular a identificação do seu ambiente, construindo um include_path adequado, e passar o
                    que é fornecido na linha de comando para o componente de biblioteca adequado
                    para a expedição.
                </para>

                <para>
                    Finalmente, você quer garantir duas coisas para fazer tudo funcionar
                    independentemente do sistema operacional em que você está:
                </para>

                <orderedlist>
                    <listitem>
                        <para>
                            <filename>zf.sh/zf.bat</filename> acessível a partir do path do sistema.
                            Esta é a capacidade de chamar <command>zf</command> de qualquer lugar na sua linha de comando,
                            independentemente de qual é o seu diretório de trabalho atual.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <filename>ZendFramework/library</filename> estar no seu
                            <property>include_path</property>.
                        </para>
                    </listitem>
                </orderedlist>

                <note>
                    <para>
                        Nota: enquanto os acima são os requisitos ideais, você pode simplesmente
                        baixar o Zend Framework e esperar que ele funcione como <filename>./path/to/zf.php</filename>
                        algum comando..
                    </para>
                </note>
            </sect4>

            <sect4 id="zend.tool.extending.zend-tool-framework.cli-client.setup-starnix">
                <title>Configurando a ferramenta CLI em Sistemas Unix-like</title>

                <para>
                    A configuração mais comum no ambiente *nix, é copiar o <filename>zf.sh</filename> e
                    o <filename>zf.php</filename> no mesmo diretório que o seu binário <acronym>PHP</acronym>.
                    Isto pode geralmente ser achado nos seguintes lugares:
                </para>

                <programlisting language="text"><![CDATA[
/usr/bin
/usr/local/bin
/usr/local/ZendServer/bin/
/Applications/ZendServer/bin/
]]></programlisting>

                <para>
                    Para achar a localização do seu binário <acronym>PHP</acronym>, você pode executar
                    'which php' na linha de comando. Isto retornará a localização do binário do <acronym>PHP</acronym>
                    que você está usando para rodar scripts <acronym>PHP</acronym> no seu ambiente.
                </para>

                <para>
                    O próximo passo é certificar que a biblioteca Zend Framework está configurada
                    corretamente dentro do sistema de <property>include_path</property> do
                    <acronym>PHP</acronym>. Para achar onde seu <property>include_path</property>
                    está localizado, você pode executar <command>php -i</command> e olhar para
                    a variável <property>include_path</property>, o mais sucintamente, executar
                    <command>php -i | grep include_path</command>. Uma vez que você tenha achado
                    onde seu <property>include_path</property> está localizado (isto irá geralmente
                    estar em algum lugar como <filename>/usr/lib/php</filename>,
                    <filename>/usr/share/php</filename>, <filename>/usr/local/lib/php</filename>, ou
                    similar), certifique que o conteúdos do diretório <filename>/library/</filename>
                    estão colocados dentro do seu diretório <property>include_path</property>
                    especificado.
                </para>

                <para>
                    Uma vez que você tenha terminado estas duas coisas, você deve ser capaz de digitar
                    um comando e obter devolta a resposta adequada como:
                </para>

                <para>
                    <inlinegraphic scale="100" align="center" valign="middle"
                        fileref="figures/zend.tool.framework.cliversionunix.png" format="PNG" />
                </para>

                <para>
                    Se vocÊ não ver isto digitado na saída, volte e verifique sua configuração
                    para ter certeza que tem todas as partes necessárias in devido lugar.
                </para>

                <para>
                    Existem uma combinação de configurações alternativas que você pode querer empregar
                    dependendo das configurações dos servidores, seu nível de acesso, ou
                    por outras razões.
                </para>

                <para>
                   <emphasis>Configuração Alternativa</emphasis> envolve guardar o download do
                   Zend Framework junto como está, e criar um link de um local <constant>PATH</constant>
                   para o <filename>zf.sh</filename>. O que isto significa é que você coloca o conteúdo
                   do download do Zend Framework em uma localização tal como <filename>/usr/local/share/ZendFramework</filename>,
                   ou mais localmente como <filename>/home/username/lib/ZendFramework</filename>, e cria
                   um link simbólico para o <filename>zf.sh</filename>.
                </para>

                <para>
                    Assumindo que você quer colocar o link dentro de <filename>/usr/local/bin</filename>
                    (isto pode também funcionar colocando o link dentro de <filename>/home/username/bin/</filename>
                    por exemplo) você poderia dgitar um comando similar a este:
                </para>

                <programlisting language="sh"><![CDATA[
ln -s /usr/local/share/ZendFramework/bin/zf.sh /usr/local/bin/zf

# OU (por exemplo)
ln -s /home/username/lib/ZendFramework/bin/zf.sh /home/username/bin/zf
]]></programlisting>

                <para>
                    Isto irá criar um link que você poderá ser capaz de acessar globalmente
                    na linha de comando.
                </para>
            </sect4>

            <sect4 id="zend.tool.extending.zend-tool-framework.cli-client.setup-windows">
                <title>Configurando a ferramenta CLI no Windows</title>

                <para>
                    A confuguração mais comum no ambiente Win32, é copiar o
                    <filename>zf.bat</filename> e o <filename>zf.php</filename> para dentr do mesmo
                    diretório do seu binário <acronym>PHP</acronym>. Este pode geralmente ser achado
                    nos seguintes lugares:
                </para>

                <programlisting language="text"><![CDATA[
C:\PHP
C:\Program Files\ZendServer\bin\
C:\WAMP\PHP\bin
]]></programlisting>

                <para>
                    Você deve ser capaz de rodar <filename>php.exe</filename> na linha de comando.
                    Se você não for capaz, primeiro verifique a documentação que veio com sua
                    distribuição <acronym>PHP</acronym>, ou tenha certeza que o caminho para o
                    <filename>php.exe</filename> está na sua variável de ambiente
                    <constant>PATH</constant> do Windows.
                </para>

                <para>
                    O próximo passo é ter certeza que a biblioteca do Zend Framework
                    está configurada corretamente dentro do sistema de <property>include_path</property>
                    do <acronym>PHP</acronym>. Para achar onde seu <property>include_path</property>
                    está localizado, você pode digitar <command>php -i</command> e olhar para a
                    variável <property>include_path</property>, ou mais sucintamente executar
                    <command>php -i | grep include_path</command> se você tem um Cygwin configurado
                    com grep disponível. Uma vez você tenha achado onde seu <property>include_path</property>
                    está localizado(isto irá geralmente ser algo como <filename>C:\PHP\pear</filename>,
                    <filename>C:\PHP\share</filename>,<filename>C:\Program%20Files\ZendServer\share</filename>
                    ou similar), verifique que os conteúdos do diretório library/ estão postos dentro
                    do seu diretório <property>include_path</property>especificado.
                </para>

                <para>
                    Uma vez tenha terminado aquilas duas coisas, você deve ser capaz de enviar um
                    comando e receber o devida resposta como:
                </para>

                <para>
                    <inlinegraphic scale="100" align="center" valign="middle"
                        fileref="figures/zend.tool.framework.cliversionwin32.png" format="PNG" />
                </para>

                <para>
                    Se você não ver isto digitado na saída, volte e verifique sua configuração
                    para ter certeza que você tem todas as partes necessárias no lugar correto.
                </para>

                <para>
                    Existe uma combinação de configurações alternativas que você pode querer empregar
                    dependendo das configurações do seu servidor, do seu nível de acesso, ou de
                    outras razões.
                </para>

                <para>
                    <emphasis>Configuração Alternativa</emphasis> envolve guardar o download do
                    Zend Framework junto como está, e alterar ambos seu sistema de <constant>PATH</constant>
                    bem como o arquivo <filename>php.ini</filename>. No seu ambiente de usuário,
                    tenha certeza de adcionar <filename>C:\Path\To\ZendFramework\bin</filename>,
                    então seu arquivo <filename>zf.bat</filename> será executável. Também, altere
                    o arquivo <filename>php.ini</filename> certificando que
                    <filename>C:\Path\To\ZendFramework\library</filename> está no seu
                    <property>include_path</property>.
                </para>
            </sect4>

            <sect4 id="zend.tool.extending.zend-tool-framework.cli-client.setup-othernotes">
                <title>Outras Considerações de Configuração</title>

                <para>
                    Se por alguma razão você não quiser a biblioteca do Zend Framework dentro
                    do seu <property>include_path</property>, existe uma outra opção. Existem
                    duas variáveis de ambiente especiais que o <filename>zf.php</filename> irá
                    utilizar para determinar a localização da sua instalação do Zend Framework.
                </para>

                <para>
                    A primeira é <constant>ZEND_TOOL_INCLUDE_PATH_PREPEND</constant>, que irá
                    preceder o valor da variável de ambiente para o sistema de (<filename>php.ini</filename>)
                    <property>include_path</property> <property>include_path</property> antes
                    da carga do cliente.
                </para>

                <para>
                    Alternativamente, você pode querer usar <constant>ZEND_TOOL_INCLUDE_PATH</constant>
                    para <emphasis>substituir</emphasis> completamente o sistema de
                    <property>include_path</property> para um que faça sentido especialmente para
                    a ferramente de linha de comando <command>zf</command>.
                </para>
            </sect4>
        </sect3>

        <sect3 id="zend.tool.extending.zend-tool-framework.providers-and-manifests">
            <title>Criando Providers</title>

            <para>
                Em geral, um provider, por si só, é nada mais que o a casca para um
                desenvolvedor para agrupar-se algumas das capacidades que eles desejam
                enviar com um o cliente de linha de comando (ou outro). Ele é um análogo
                para o que um "controller" é dentro da sua aplicação <acronym>MVC</acronym>.
            </para>

            <sect4 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.loading">
                <title>Como o Zend_Tool encontra seus Providers</title>

                <para>
                    Por padrão <classname>Zend_Tool</classname> usa o BasicLoader para encontrar
                    todos os providers que você pode rodar. Ele itera recursivamente todos
                    os diretórios do include path e abre todos os arquivos que terminam
                    com "Manifest.php" ou "Provider.php". Todas as classes naqueles arquivos
                    são inspecionadas se implementam ou <classname>Zend_Tool_Framework_Provider_Interface</classname>
                    ou <classname>Zend_Tool_Framework_Manifest_ProviderManifestable</classname>.
                    Instancias da interface do provider implementam a real funcionalidade e
                    todos os métodos públicos estão acessíveis como actions do provider.
                    A interface ProviderManifestable de qualquer forma requer a implementação de um
                    metodo <methodname>getProviders()</methodname> que reforna um array de
                    instâncias da interface provider.
                </para>

                <para>
                    As seguintes regras de nomeação aplicaveis em como você pode acessar os providers
                    que foram encontrados pelo IncludePathLoader:
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            A última parte da sua divisão do classname por underscore é usado
                            para o nome do provedor, por exemplo, "My_Provider_Hello" permite ao seu
                            provider a ser acessível pelo nome de "hello".
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Se o seu provider tem um método <methodname>getName()</methodname>
                            ele irá ser usado ao invés da maneira anterior para determinar
                            o nome.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Se o seu provider tem um prefixo "Provider", por exemplo ele é chamado
                            de <classname>My_HelloProvider</classname>, isto será retirado
                            do nome, assim o provider será chamado "hello".
                        </para>
                    </listitem>
                </itemizedlist>

                <note>
                    <para>O IncludePathLoader não permite links simbólicos, que significa
                    que você não pode linkar funcionalmente o provider no seus inclide paths,
                    eles tem que estar fisicamente presentes nos inclide paths.</para>
                </note>

                <example
                    id="zend.tool.extending.zend-tool-framework.providers-and-manifests.loading.example">
                    <title>Expondo Seus Providers com um Manifest</title>

                    <para>
                        Você pode expor seus providers para <classname>Zend_Tool</classname>
                        oferecendo um manifest com a nome de arquivo especial terminando com
                        "Manifest.php". Um Provider Manifest é uma implementação do
                        <interface>Zend_Tool_Framework_Manifest_ProviderManifestable</interface>
                        e requer o método <methodname>getProviders()</methodname> para retornar
                        uma array providers instânciados. Em antecipação do seu primeiro próprio
                        provider <classname>My_Component_HelloProvider</classname> nós iremos
                        criar o seguinte manifest:
                    </para>

                    <programlisting language="php"><![CDATA[
class My_Component_Manifest
    implements Zend_Tool_Framework_Manifest_ProviderManifestable
{
    public function getProviders()
    {
        return array(
            new My_Component_HelloProvider()
        );
    }
}
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.basic">
                <title>Instruções Básicas para Criação de Providers</title>

                <para>
                   Como um exemplo, se um desenvolvedor quer adicionar a capacidade de apresentar
                   a versão de um arquivos de dados que seu componente de terceiros está usando,
                   exite apenas uma classe que o desenvolvedor precisaria implementar.
                   Asumindo que o componente é chamado <classname>My_Component</classname>,
                   Ele poderia criar uma classe chamada <classname>My_Component_HelloProvider</classname>
                   em um arquivo nomeado de <filename>HelloProvider.php</filename> em algum lugar no
                   <property>include_path</property>. Esta classe implementaria <classname>Zend_Tool_Framework_Provider_Interface</classname>,
                   e o corpo deste arquivo apenas teria que parecer com o seguinte:
                </para>

                <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    implements Zend_Tool_Framework_Provider_Interface
{
    public function say()
    {
        echo 'Hello from my provider!';
    }
}
]]></programlisting>

                <para>
                    Dado o códifo acima, e assumindo que o desenvolvedor deseja acessar
                    esta funcionalidade através do cliente de console, a chamada se pareceria
                    com isto:
                </para>

                <programlisting language="sh"><![CDATA[
% zf say hello
Hello from my provider!
]]></programlisting>
            </sect4>

            <sect4 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.response">
                <title>O objeto response</title>

                <para>
                    Como assumido na arquitetura da sessão <classname>Zend_Tool</classname> permite
                    unir diferentes cliente para usar o seus providers <classname>Zend_Tool</classname>.
                    Para manter a conformidade com diferentes clientes você deve usar o objeto de resposta
                    para retornar mensagens de seus providers em vez de usar <methodname>echo()</methodname>
                    ou um mecanismo de saída semelhante. Reescrevendo nosso provider hello com este conhecimento
                    isto vai se parecer com:
                </para>

                <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say()
    {
        $this->_registry
             ->getResponse()
             ->appendContent("Hello from my provider!");
    }
}
]]></programlisting>

                <para>
                    Como você pode ser ele extende o
                    <classname>Zend_Tool_Framework_Provider_Abstract</classname> para ter acesso
                    ao Registry que guarda a instância do <classname>Zend_Tool_Framework_Client_Response</classname>.
                </para>
            </sect4>

            <sect4 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced">
                <title>Informações sobre Desenvolvimento Avançado</title>

                <sect5
                    id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced.variables">
                    <title>Passando variáveis para o Provider</title>

                    <para>
                        O exemplo "Hello World" acima é ótimo para comandos simples, mas
                        o que dizer sobre algo mais avançado? Como seu script e ferramentas
                        necessitam crescer, você pode achar que precisa da capacidade de aceitar
                        variáveis. Bem como assinaturas de função têm parâmetros, a sua
                        chamada para a ferramenta também podem aceitar parâmetros.
                    </para>

                    <para>
                        Assim como cada requisição à ferramenta podem ser isolado a um método
                        dentro de uma classe, os parâmetros de uma requisição à ferramenta
                        também podem ser isolado em um lugar muito conhecido. Parâmetros dos
                        métodos de ação de um provider podem incluir os mesmos parâmetros que
                        você deseja que o seu cliente utilize ao chamar o provider e combinação
                        de ações. Por exemplo, se você quiser aceitar um nome no exemplo acima,
                        você provavelmente fazer isso em um código OO:
                    </para>

                    <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    implements Zend_Tool_Framework_Provider_Interface
{
    public function say($name = 'Ralph')
    {
        echo 'Hello' . $name . ', from my provider!';
    }
}
]]></programlisting>

                    <para>
                        O exemplo acima pode então ser chamado via linha de comando
                        <command>zf say hello Joe</command>. "Joe" será fornecido ao provider
                        como um parametro do método chamado. Também note, como pode ser que o
                        parametro é opcional, isto significa que ele é também opcional na linha
                        de comando, assim <command>zf say hello</command> ainda funcionará, e
                        por padrão o nome será "Ralph".
                    </para>
                </sect5>

                <sect5
                    id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced.prompt">
                    <title>Solicitar Entrada ao Usuário</title>

                    <para>
                        Existem casos quando o workflow do seu provider requer
                        solicitar o usuário entrada de dados. Isto pode ser feito,
                        solicitando o cliente a pedir mais entradas necessárias chamando:
                    </para>

                    <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say($name = 'Ralph')
    {
        $nameResponse = $this->_registry
                             ->getClient()
                             ->promptInteractiveInput("Whats your name?");
        $name = $nameResponse->getContent();

        echo 'Hello' . $name . ', from my provider!';
    }
}
]]></programlisting>

                    <para>
                        Este comando dispara uma exceção se o cliente corrente não é
                        capaz de manipular requisições interativas. No caso de o Cliente do Console
                        padrão, contudo, você será solicitado a digitar o nome.
                    </para>
                </sect5>

                <sect5
                    id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced.pretendable">
                    <title>Fingindo para executar um Provider Action</title>

                    <para>
                        Outra funcionalidade interessante que você pode desejar implementar
                        é <emphasis>fingimento</emphasis>. Fingimento é a capacidade de seu
                        provedor para "fingir" como se estivesse fazendo a ação solicitada e
                        combinação de provedor e dar ao usuário o máximo de informações sobre
                        o que <emphasis>faria</emphasis> sem realmente fazesse. Isso pode
                        ser uma noção importante ao fazer banco de dados pesado ​​ou modificações
                        do sistema de arquivos que o usuário não poderiam querer fazer.
                    </para>

                    <para>
                        Fingimento é fácil de implementar. Existem duas partes para esta
                        funcionalidade: 1) marcando o provider como tendo a habilidade para
                        "fingir", e 2) verificando a requisição para garantir a requisição
                        corrente foi de fato solicitada a ser "pretended". Esta funcionalidade
                        é demostrada no simples código abaixo.
                    </para>

                    <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    extends    Zend_Tool_Framework_Provider_Abstract
    implements Zend_Tool_Framework_Provider_Pretendable
{
    public function say($name = 'Ralph')
    {
        if ($this->_registry->getRequest()->isPretend()) {
            echo 'I would say hello to ' . $name . '.';
        } else {
            echo 'Hello' . $name . ', from my provider!';
        }
    }
}
]]></programlisting>

                    <para>
                        Para rodar o provider em modo fingido apenas chame:
                    </para>

                    <programlisting language="sh"><![CDATA[
% zf --pretend say hello Ralph
I would say hello Ralph.
]]></programlisting>
                </sect5>

                <sect5
                    id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced.verbosedebug">
                    <title>Modos Verboso e Debug</title>

                    <para>
                        Você pode também rodar as suas actions do provider em modo "verboso" ou "debug".
                        A semântica em relação a esta ações devem ser implementadas por você
                        no contexto do seu provedor. Você pode acessar o modo debug ou verboso com:
                    </para>

                    <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    implements Zend_Tool_Framework_Provider_Interface
{
    public function say($name = 'Ralph')
    {
        if($this->_registry->getRequest()->isVerbose()) {
            echo "Hello::say has been called\n";
        }
        if($this->_registry->getRequest()->isDebug()) {
            syslog(LOG_INFO, "Hello::say has been called\n");
        }
    }
}
]]></programlisting>
                </sect5>

                <sect5
                    id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced.configstorage">
                    <title>Acessando Configuração e Armazenamento de Usuário</title>

                    <para>
                        Usando a variável de Ambiente <property>ZF_CONFIG_FILE</property> ou o
                        .zf.ini em seu diretório home você pode injetar parametros configuração em
                        qualquer provider <classname>Zend_Tool</classname>. Acesso a esta configuração
                        está disponível via registry que é passado para seu provider se você extender
                        <classname>Zend_Tool_Framework_Provider_Abstract</classname>.
                    </para>

                    <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say()
    {
        $username = $this->_registry->getConfig()->username;
        if(!empty($username)) {
            echo "Hello $username!";
        } else {
            echo "Hello!";
        }
    }
}
]]></programlisting>

                    <para>
                        A configuração retornada está no tipo
                        <classname>Zend_Tool_Framework_Client_Config</classname> mas internamente os
                        métodos mágicos <methodname>__get()</methodname> and <methodname>__set()</methodname>
                        encaminham para um <classname>Zend_Config</classname> do tipo de configuração
                        fornecida.
                    </para>

                    <para>
                        O armazenamento permite salvar dados arbitrarios para referenciar depois.
                        Isto pode ser útil para tarefas de processamento em lote ou para re-executar
                        sua tarefa. Você pode acessar o armazenamento em uma caminho similar ao
                        da configuração:
                    </para>

                    <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say()
    {
        $aValue = $this->_registry->getStorage()->get("myUsername");
        echo "Hello $aValue!";
    }
}
]]></programlisting>

                    <para>
                        A <acronym>API</acronym> para o armazenamento é muito simples:
                    </para>

                    <programlisting language="php"><![CDATA[
class Zend_Tool_Framework_Client_Storage
{
    public function setAdapter($adapter);
    public function isEnabled();
    public function put($name, $value);
    public function get($name, $defaultValue=null);
    public function has($name);
    public function remove($name);
    public function getStreamUri($name);
}
]]></programlisting>

                    <important>
                        <para>
                            Ao projetar seus providers que estarão cientes do armazenamento e da
                            configuração lembre-se de verificar se configurações de usuário ou
                            chaves de armazenamento necessárias realmente existem para um usuário.
                            Você não vai executar em erros fatais quando nenhuma dessas existir
                            porém, desde que eles estejam vazios, são criados mediante solicitação.
                        </para>
                    </important>
                </sect5>
            </sect4>
        </sect3>
    </sect2>

    <sect2 id="zend.tool.extending.zend-tool-project">
        <title>Extensões Zend_Tool_Project</title>

        <para>
            <classname>Zend_Tool_Project</classname> expoe um rico conjunto de funcionalidades e
            capacidades que faz o tarefa de criação de novos providers, especificamente visando
            projetos mais fáceis e mais gerenciáveis.
        </para>

        <sect3 id="zend.tool.extending.zend-tool-project.architecture">
            <title>Arquitetura Geral</title>

            <para>
                Este mesmo conceito se aplica aos projetos Zend Framework. Em projetos de Zend Framework,
                você tem controllers, actions, views, models, bancos de dados e assim por diante. Em
                Termos de <classname>Zend_Tool</classname>, nós precisamos de um caminho para rastrear
                estes tipos de recursos - portanto <classname>Zend_Tool_Project</classname>.
            </para>

            <para>
                <classname>Zend_Tool_Project</classname> é capaz de rastrear os recursos do projeto
                ao longo do desenvolvimento de um projeto. Então, por exemplo, se em um comando você
                criar um controller, e no próximo comando você quiser criar uma action sem o controller,
                <classname>Zend_Tool_Project</classname> vai ter de <emphasis>saber</emphasis>
                sobre o arquivo controller que você criou de modo que você pode (na próxima ação),
                ser capaz de acrescentar a action a ele. Isto é o que mantém os nossos projetos
                em dia e <emphasis>monitorado</emphasis>.
            </para>

            <para>
                Outro ponto importante para entender é sobre projetos é que tipicamente, recursos
                são organizados em uma forma hierarquica. Com que em mente, <classname>Zend_Tool_Project</classname>
                é capaz de serializar o projeto corrente em uma representação interna que permite
                lhe permite acompanhar não só <emphasis>que</emphasis> recursos são parte de um projeto em um dado momento,
                mas também <emphasis>onde</emphasis> eles estão em relação uns aos outros.
            </para>
        </sect3>


        <sect3 id="zend.tool.extending.zend-tool-project.providers">
            <title>Criando Providers</title>

            <para>
                Providers específicos de projeto são criados da mesma forma como providers de serviços,
                com uma exceção: os providers de projeto devem estender de <classname>Zend_Tool_Project_Provider_Abstract</classname>.
                Esta classe vem com algumas funcionalidades significativas que ajudam os desenvolvedores
                a caregar o projeto existente, obter o objeto de profile, e ser capaz de pesquisar o profile,
                e depois armazenar quaisquer alterações ao profile do projeto atual.
            </para>

            <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    extends Zend_Tool_Project_Provider_Abstract
{
    public function say()
    {
        $profile = $this->_loadExistingProfile();

        /* ... do project stuff here */

        $this->_storeProfile();
    }
}
]]></programlisting>
        </sect3>

        <!--
        <sect3 id="zend.tool.extending.zend-tool-project.resources-and-contexts">
            <title>Creating Resources &amp; Contexts</title>



        </sect3>
        -->
    </sect2>
</sect1>