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>
                    The following naming rules apply on how you can access the providers
                    that were found by the IncludePathLoader:
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            The last part of your classname split by underscore is used
                            for the provider name, e.g. "My_Provider_Hello" leads to your
                            provider being accessible by the name "hello".
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            If your provider has a method <methodname>getName()</methodname>
                            it will be used instead of the previous method to determine
                            the name.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            If your provider has "Provider" as prefix, e.g. it is called
                            <classname>My_HelloProvider</classname> it will be stripped
                            from the name so that the provider will be called "hello".
                        </para>
                    </listitem>
                </itemizedlist>

                <note>
                    <para>The IncludePathLoader does not follow symlinks, that means
                    you cannot link provider functionality into your include paths,
                    they have to be physically present in the include paths.</para>
                </note>

                <example
                    id="zend.tool.extending.zend-tool-framework.providers-and-manifests.loading.example">
                    <title>Exposing Your Providers with a Manifest</title>

                    <para>
                        You can expose your providers to <classname>Zend_Tool</classname> by
                        offering a manifest with a special filename ending with "Manifest.php".
                        A Provider Manifest is an implementation of the
                        <interface>Zend_Tool_Framework_Manifest_ProviderManifestable</interface>
                        and requires the <methodname>getProviders()</methodname> method to return
                        an array of instantiated providers. In anticipation of our first
                        own provider <classname>My_Component_HelloProvider</classname>
                        we will create the following 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>Basic Instructions for Creating Providers</title>

                <para>
                    As an example, if a developer wants to add the capability of showing
                    the version of a datafile that his 3rd party component is working
                    from, there is only one class the developer would need to implement.
                    Assuming the component is called <classname>My_Component</classname>, he would
                    create a class named <classname>My_Component_HelloProvider</classname> in a
                    file named <filename>HelloProvider.php</filename> somewhere on the
                    <property>include_path</property>. This class would implement
                    <classname>Zend_Tool_Framework_Provider_Interface</classname>, and the body of
                    this file would only have to look like the following:
                </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>
                    Given that code above, and assuming the developer wishes to access
                    this functionality through the console client, the call would look
                    like this:
                </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>The response object</title>

                <para>
                    As discussed in the architecture section <classname>Zend_Tool</classname> allows
                    to hook different clients for using your <classname>Zend_Tool</classname>
                    providers. To keep compliant with different clients you should use the response
                    object to return messages from your providers instead of using
                    <methodname>echo()</methodname> or a similiar output mechanism. Rewritting our
                    hello provider with this knowledge it looks like:
                </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>
                    As you can see one has to extend the
                    <classname>Zend_Tool_Framework_Provider_Abstract</classname> to gain access to
                    the Registry which holds the
                    <classname>Zend_Tool_Framework_Client_Response</classname> instance.
                </para>
            </sect4>

            <sect4 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced">
                <title>Advanced Development Information</title>

                <sect5
                    id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced.variables">
                    <title>Passing Variables to a Provider</title>

                    <para>
                        The above "Hello World" example is great for simple commands, but
                        what about something more advanced? As your scripting and tooling
                        needs grow, you might find that you need the ability to accept
                        variables. Much like function signatures have parameters, your
                        tooling requests can also accept parameters.
                    </para>

                    <para>
                        Just as each tooling request can be isolated to a method within a
                        class, the parameters of a tooling request can also be isolated in a
                        very well known place. Parameters of the action methods of a
                        provider can include the same parameters you want your client to
                        utilize when calling that provider and action combination. For
                        example, if you wanted to accept a name in the above example, you
                        would probably do this in OO code:
                    </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>
                        The above example can then be called via the command line
                        <command>zf say hello Joe</command>. "Joe" will be supplied to the provider
                        as a parameter of the method call. Also note, as you see that the
                        parameter is optional, that means it is also optional on the command
                        line, so that <command>zf say hello</command> will still work, and default
                        to the name "Ralph".
                    </para>
                </sect5>

                <sect5
                    id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced.prompt">
                    <title>Prompt the User for Input</title>

                    <para>
                        There are cases when the workflow of your provider requires
                        to prompt the user for input. This can be done by requesting
                        the client to ask for more the required input by calling:
                    </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>
                        This command throws an exception if the current client is not
                        able to handle interactive requests. In case of the default Console Client
                        however you will be asked to enter the name.
                    </para>
                </sect5>

                <sect5
                    id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced.pretendable">
                    <title>Pretending to execute a Provider Action</title>

                    <para>
                        Another interesting feature you might wish to implement is
                        <emphasis>pretendability</emphasis>. Pretendabilty is the ability
                        for your provider to "pretend" as if it is doing the requested
                        action and provider combination and give the user as much
                        information about what it <emphasis>would</emphasis> do without
                        actually doing it. This might be an important notion when doing
                        heavy database or filesystem modifications that the user might not
                        otherwise want to do.
                    </para>

                    <para>
                        Pretendability is easy to implement. There are two parts to this
                        feature: 1) marking the provider as having the ability to "pretend",
                        and 2) checking the request to ensure the current request was indeed
                        asked to be "pretended". This feature is demonstrated in the code
                        sample below.
                    </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>
                        To run the provider in pretend mode just call:
                    </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>Verbose and Debug modes</title>

                    <para>
                        You can also run your provider actions in "verbose" or "debug" modes.
                        The semantics in regard to this actions have to be implemented by you
                        in the context of your provider. You can access debug or verbose modes
                        with:
                    </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>Accessing User Config and Storage</title>

                    <para>
                        Using the Enviroment variable <property>ZF_CONFIG_FILE</property> or the
                        .zf.ini in your home directory you can inject configuration parameters into
                        any <classname>Zend_Tool</classname> provider. Access to this configuration
                        is available via the registry that is passed to your provider if you extend
                        <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>
                        The returned configuration is of the type
                        <classname>Zend_Tool_Framework_Client_Config</classname> but internally the
                        <methodname>__get()</methodname> and <methodname>__set()</methodname> magic
                        methods proxy to a <classname>Zend_Config</classname> of the given
                        configuration type.
                    </para>

                    <para>
                        The storage allows to save arbitrary data for later reference. This can be
                        useful for batch processing tasks or for re-runs of your tasks. You can
                        access the storage in a similar way like the configuration:
                    </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>
                        The <acronym>API</acronym> of the storage is very simple:
                    </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>
                            When designing your providers that are config or storage aware remember
                            to check if the required user-config or storage keys really exist for a
                            user. You won't run into fatal errors when none of these are provided
                            though, since empty ones are created upon request.
                        </para>
                    </important>
                </sect5>
            </sect4>
        </sect3>
    </sect2>

    <sect2 id="zend.tool.extending.zend-tool-project">
        <title>Zend_Tool_Project Extensions</title>

        <para>
            <classname>Zend_Tool_Project</classname> exposes a rich set of functionality and
            capabilities that make the task of creating new providers, specficially those targetting
            project easier and more manageable.
        </para>

        <sect3 id="zend.tool.extending.zend-tool-project.architecture">
            <title>Overall Architecture</title>

            <para>
                This same concept applies to Zend Framework projects. In Zend Framework projects,
                you have controllers, actions, views, models, databases and so on and so forth. In
                terms of <classname>Zend_Tool</classname>, we need a way to track these types of
                resources - thus <classname>Zend_Tool_Project</classname>.
            </para>

            <para>
                <classname>Zend_Tool_Project</classname> is capable of tracking project resources
                throughout the development of a project. So, for example, if in one command you
                created a controller, and in the next command you wish to create an action within
                that controller, <classname>Zend_Tool_Project</classname> is gonna have to
                <emphasis>know</emphasis> about the controller file you created so that you can (in
                the next action), be able to append that action to it. This is what keeps our
                projects up to date and <emphasis>stateful</emphasis>.
            </para>

            <para>
                Another important point to understand about projects is that typically, resources
                are organized in a hierarchical fashion. With that in mind,
                <classname>Zend_Tool_Project</classname> is capable of serializing the current
                project into a internal representation that allows it to keep track of not only
                <emphasis>what</emphasis> resources are part of a project at any given time, but
                also <emphasis>where</emphasis> they are in relation to one another.
            </para>
        </sect3>


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

            <para>
                Project specific providers are created in the same fashion as plain framework
                providers, with one exception: project providers must extend the
                <classname>Zend_Tool_Project_Provider_Abstract</classname>. This class comes with
                some significant functionality that helps developers load existing project, obtian
                the profile object, and be able to search the profile, then later store any changes
                to the current project profile.
            </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>