repo_zf1/documentation/manual/pt-br/module_specs/Zend_Tool-Usage-CLI.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24333 -->
<!-- Reviewed: no -->
<sect1 id="zend.tool.usage.cli">
    <title>Usando Zend_Tool na Linha de Comando</title>

    <para>
        O <acronym>CLI</acronym>, ou ferramenta de linha de comando (internamente conhecida como ferramenta de console),
        é a principal interface para envio de requisições <classname>Zend_Tool</classname>.
        Com a ferramenta <acronym>CLI</acronym>, desenvolvedores podem emitir requisições para a ferramenta
        dentro da "janela de linha de comando", também comumente conhecida como uma janela do "terminal". Este
        ambiente é predominante em um contexto *nix, porem tem uma implementação comum
        no windows com o <filename>cmd.exe</filename>, console2 e também com o projeto Cygwin.
    </para>

    <!--
    <sect2 id="zend.tool.usage.cli.introduction">
        <title>Introduction</title>
    </sect2>
    -->

    <sect2 id="zend.tool.usage.cli.installation">
        <title>Instalação</title>

        <sect3 id="zend.tool.usage.cli.installation.download-and-go">
            <title>Download E Siga</title>

            <para>
                Primeiro faça o download do Zend Framework. Isto pode ser feito indo em framework.zend.com
                e fazendo download do último release. Depois que você fez o download do pacote e colocou-o
                no seu sistem. O próximo passo é deixar o comando zf disponível para seu sistema
                O caminho mais fácil de fazer isso, é copiar os próprios arquivos do diretório bin/
                do download, e colocar esses arquivos no <emphasis>mesmo</emphasis> diretório local do
                binário do cli <acronym>PHP</acronym>.
            </para>
        </sect3>

        <sect3 id="zend.tool.usage.cli.installation.pear">
            <title>Instalação Via Pear</title>

            <para>
                Para instalar via PEAR, você deve usar o site de terceiros zfcampus.org para obter o
                último pacote PEAR do Zend Framework. Estes pacotes são tipicamente construídos dentro
                de um dia de um release oficial do Zend Framework. O benefício da instalação via gerenciador
                de pacotes PEAR é que durante o processo de instalação, a biblioteca ZF vai acabar no
                include_path, e os scripts zf.php e zf scripts irão acabar em um lugar no seu sistema
                que vai permitir executar-los sem nenhuma configuração adicional.
            </para>

            <programlisting language="text"><![CDATA[
pear discover-channel pear.zfcampus.org
pear install zfcampus/zf
]]></programlisting>

            <para>
                É isto. Depois de instalação inicial, você deve ser capaz de continuar executando
                o comando zf. Uma boa maneira para ver se está tudo certo é executar o zf --help
            </para>
        </sect3>

        <sect3 id="zend.tool.usage.cli.installation.install-by-hand">
            <title>Instalação na Mão</title>

            <para>
                Instalação na mão refere-se ao processo de forçar o zf.php e a biblioteca Zend Framework
                a trabalhar juntas quando elas são colocadas em lugares não-convencionais, ou pelo menos,
                em um lugar que seu sistema não pode dispachar facilmente (típico de programas no PATH
                do seu sistema).
            </para>

            <para>
                Se você está em um sistema *nix ou mac, você pode também criar um link de algum lugar
                no seu path para o arquivo zf.sh. Se fizer isso, você não precisa se preocupar em ter
                a biblioteca Zend Framework no seu include_path, como os arquivos zf.php e zf.sh serão
                capazes de acessar a biblioteca em relação a onde elas estão (significa que os arquivos
                no ./bin/ são ../library/ relativos a biblioteca Zend Framework).
            </para>

            <para>
                Existe um número de outras opções disponíveis para configurar o zf.php e a biblioteca
                no seu sistema. Essas opções giram em torno da definição de variáveis específicas de
                ambiente. Estas serão descritas mais tarde na seção "customizando o ambiente CLI". As
                variáveis de ambiente para configurar o zf.php no include_path, ZF_INCLUDE_PATH e
                ZF_INCLUDE_PATH_PREPEND, são as mais interessantes.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.tool.usage.cli.general-purpose-commands">
        <title>Comandos de Propósito General</title>

        <sect3 id="zend.tool.usage.cli.general-purpose-commands.version">
            <title>Version</title>

            <para>
                Isto mostrará o número da versão corrente da cópia do Zend Framework que a ferramenta
                zf.php está usando.
            </para>

            <programlisting language="text"><![CDATA[
zf show version
]]></programlisting>
        </sect3>

        <sect3 id="zend.tool.usage.cli.general-purpose-commands.built-in-help">
            <title>Help Embutido</title>

            <para>
                O sistema de help embutido é o primeiro lugar onde você pode obter informações atualizadas
                sobre o que o seu sistema é capaz de fazer. O sistema de help é dinâmico pois como
                os providers são adicionados ao seus sistema, eles são automaticamente executáveis,
                bem como, os parametros necessários para executar-los estarão na tela de ajuda. O caminho
                mais fácil de obter a tela de ajuda é o seguinte:
            </para>

            <programlisting language="text"><![CDATA[
zf --help
]]></programlisting>

            <para>
                Isto dará a você uma visão geral de várias capacidades do sistema.
                Algumas vezes, existem mais comandos expecíficos que podem ser executados, e para ter
                mas informações sobre eles, você pode ter que rodar mais um comando de help especializado.
                Para um help especializado, simplesmente substitua qualquer um dos elementos do comando
                por uma "?". Isto dirá ao sistema de help que você quer mais informações sobre que
                comandos podem ir no lugar da interrogação. Por exemplo:
            </para>

            <programlisting language="text"><![CDATA[
zf ? controller
]]></programlisting>

            <para>
                O acima exposto significa "mostre-me todos os 'actions' do provider 'controller'";
                enquanto o seguinte:
            </para>

            <programlisting language="text"><![CDATA[
zf show ?
]]></programlisting>

            <para>
                significa "mostre-me todos os providers que suportam a action 'show'". Isso funciona
                para as opções do exemplo a baixo, bem como você pode ver nos exemplos a seguir:
            </para>

            <programlisting language="text"><![CDATA[
zf show version.? (mostra todas as especialidades)
zf show version ? (mostra todas as opções)
]]></programlisting>
        </sect3>

        <sect3 id="zend.tool.usage.cli.general-purpose-commands.manifest">
            <title>Manifest</title>

            <para>
                Isto irá mostrar o que existe no manifest das ferramentas do sistema. Isso é mais importante
                para os desenvolvedores de provider do que para usuários casuais das ferramentas do sistema.
            </para>

            <programlisting language="text"><![CDATA[
zf show manifest
]]></programlisting>
        </sect3>

        <!--
        <sect3 id="zend.tool.usage.cli.general-purpose-commands.tool-configuration">
            <title>Tool Configuration</title>

            <para>Placeholder   need docs from @beberli </para>

        </sect3>
        -->
    </sect2>

    <sect2 id="zend.tool.usage.cli.project-specific-commands">
        <title>Comandos Específicos do Projeto</title>

        <sect3 id="zend.tool.usage.cli.project-specific-commands.project">
            <title>Project</title>

            <para>
                O provider project é o primeiro comando que você deve querer rodar. Ele irá configurar a
                estrutura básica da sua aplicação. Isto é necessário antes de qualquer dos outros
                providers pode serem executado.
            </para>

            <programlisting language="text"><![CDATA[
zf create project MyProjectName
]]></programlisting>

            <para>
                Isso irá criar um projeto em um diretório chamado ./MyProjectName. A partir deste ponto,
                é importante notar que qualquer dos comandos subseqüentes na linha de comando deve ser
                executado de dentro do diretório do projeto que você acabou de criar. Assim, após a criação,
                a mudança de diretório é necessária.
            </para>
        </sect3>

        <sect3 id="zend.tool.usage.cli.project-specific-commands.module">
            <title>Module</title>

            <para>
                O provider module permite a fácil criação de um modulo Zend Framework. Um
                um módulo segue ligeiramente o padrão hMVC. Ao criar módulos, levamos a mesma
                estrutura usada no nível application/, e duplicamos dentro do nome escolhido
                para o seu módulo, dentro do diretório "modules" do diretório application/
                sem duplicar o diretório de modules em si. Por exemplo:
            </para>

            <programlisting language="text"><![CDATA[
zf create module Blog
]]></programlisting>

            <para>
                Isto irá criar um módulo chamado Blog em application/modules/Blog, e todos os artefatos
                que o módulo irá precisar.
            </para>
        </sect3>

        <sect3 id="zend.tool.usage.cli.project-specific-commands.controller">
            <title>Controller</title>

            <para>
                O privider controller é responsável por criar (principalmente) controllers vazios bem
                como seus correspondentes diretórios dos script de view e os arquivos. Para utiliza-lo
                crie um 'Auth' controlller, por exemplo, execute:
            </para>

            <programlisting language="text"><![CDATA[
zf create controller Auth
]]></programlisting>

            <para>
                Isto irá criar um controller chamado Auth, expecificamente criará um arquivo em
                application/controllers/AuthController.php com AuthController dentro.
                Se você quiser criar um controller para um módulo, use qualquer dos seguintes comandos:
            </para>

            <programlisting language="text"><![CDATA[
zf create controller Post 1 Blog
zf create controller Post -m Blog
zf create controller Post --module=Blog
]]></programlisting>

            <para>
                Note: No primeiro comando, 1 é o valor para a flag "includeIndexAction".
            </para>
        </sect3>

        <sect3 id="zend.tool.usage.cli.project-specific-commands.action">
            <title>Action</title>

            <para>
                Para criar uma action dentro de um controller existente:
            </para>

            <programlisting language="text"><![CDATA[
zf create action login Auth
zf create action login -c Auth
zf create action login --controller-name=Auth
]]></programlisting>
        </sect3>

        <sect3 id="zend.tool.usage.cli.project-specific-commands.view">
            <title>View</title>

            <para>
                Para criar uma view fora do controller/action corrente, você poderia
                usar um dos seguintess comandos:
            </para>

            <programlisting language="text"><![CDATA[
zf create view Auth my-script-name
zf create view -c Auth -a my-script-name
            ]]></programlisting>

            <para>
                Isto irá criar um script de view na pasta do controller Auth.
            </para>
        </sect3>

        <sect3 id="zend.tool.usage.cli.project-specific-commands.model">
            <title>Model</title>

            <para>
                O provider model é apenas responsável por criar os arquivos de modelo de forma adequada,
                com o próprio nome dentro da pasta application. Por exemplo
            </para>

            <programlisting language="text"><![CDATA[
zf create model User
]]></programlisting>

            <para>
                Se você deseja criar um model dentro de um módulo específico:
            </para>

            <programlisting language="text"><![CDATA[
zf create model Post -m Blog
]]></programlisting>

            <para>
                O comando a cima cria um model 'Post' dentro do módulo 'Blog'.
            </para>
        </sect3>

        <sect3 id="zend.tool.usage.cli.project-specific-commands.form">
            <title>Form</title>

            <para>
                O provider form é apenas responsável por criar o arquivo e o
                método init() de forma adequada, com o nome adequado dentro da pasta application. Por exemplo:
            </para>

            <programlisting language="text"><![CDATA[
zf create form Auth
]]></programlisting>

            <para>
                Se você deseja criar um model dentro de um módulo expecífico:
            </para>

            <programlisting language="text"><![CDATA[
zf create form Comment -m Blog
]]></programlisting>

            <para>
                O comando acima criará o form 'Comment' dentro do módulo 'Blog'.
            </para>
        </sect3>

        <sect3 id="zend.tool.usage.cli.project-specific-commands.database-adapter">
            <title>DbAdapter</title>

            <para>
                Parar configurar um DbAdapter, você precisará fornecer informações como uma
                string de url codificada. As strings precisam estar com aspas na linha de comando.
            </para>

            <para>
                Por exemplo, para digitar as seguintes informações:

                <itemizedlist>
                    <listitem>
                        <para>adapter: Pdo_Mysql</para>
                    </listitem>

                    <listitem>
                        <para>username: test</para>
                    </listitem>

                    <listitem>
                        <para>password: test</para>
                    </listitem>

                    <listitem>
                        <para>dbname: test </para>
                    </listitem>
                </itemizedlist>

                O seguinte comando terá que ser rodado na linha de comando:
            </para>

            <programlisting language="text"><![CDATA[
zf configure dbadapter "adapter=Pdo_Mysql&username=test&password=test&dbname=test"
]]></programlisting>

            <para>
                Isto assume que você deseja armazenar estas informações no
                espaço de 'production' do arquivo de configuração da aplicação. O comando seguinte
                irá demonstrar uma configuração para sqlite, na sessão 'development' do arquivo de
                configuração da aplicação.
            </para>

            <programlisting language="text"><![CDATA[
zf configure dbadapter "adapter=Pdo_Sqlite&dbname=../data/test.db" development
zf configure dbadapter "adapter=Pdo_Sqlite&dbname=../data/test.db" -s development
]]></programlisting>
        </sect3>

        <sect3 id="zend.tool.usage.cli.project-specific-commands.db-table">
            <title>DbTable</title>

            <para>
                O provider DbTable é responsável por criar arquivos de modelo
                <classname>Zend_Db_Table</classname>/dados de acesso para a sua aplicação consumir,
                com o nome da classe adequada e em local apropriado na aplicação.
                As duas importantes peças de informação são o <emphasis>nome da DbTable</emphasis>,
                e o <emphasis>nome da tabela atual banco de dados</emphasis>. Por exemplo:
            </para>

            <programlisting language="text"><![CDATA[
zf create dbtable User user
zf create dbtable User -a user

// também aceita a opção force para sobreescrever arquivos existentes
zf create dbtable User user -f
zf create dbtable User user --force-overwrite
]]></programlisting>

            <para>
                O provider DbTable é também capaz de criar os arquivos apropriadamente
                mapeando o banco de dados configurado com o provider DbAdapter abaixo.
            </para>

            <programlisting language="text"><![CDATA[
zf create dbtable.from-database
]]></programlisting>

            <para>
                Ao executar o acima exposto, pode ser fazer sentido usar primeiro a flag de simulação
                "-p" para que você possa ver o que seria feito, e que tablelas podem
                ser encontradas no banco da dados.
            </para>

            <programlisting language="text"><![CDATA[
zf -p create dbtable.from-database
]]></programlisting>
        </sect3>

        <sect3 id="zend.tool.usage.cli.project-specific-commands.layout">
            <title>Layout</title>

            <para>
                Atualmente, a única ação suportada para layout é simplesmente permitir-lhes,
                então configurar apropriadamente o arquivo application.ini para o aplicativo trabalhar,
                e criar os diretórios e arquivos layout.phtml.
            </para>

            <programlisting language="text"><![CDATA[
zf enable layout
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.tool.usage.cli.environment-customization">
        <title>Personalização do Ambiente</title>

        <sect3 id="zend.tool.usage.cli.environment-customization.storage-directory">
            <title>O Storage Directory</title>

            <para>
               O storage directory é importante para que os providers poderem ter um lugar para encontrar
               a lógica do usuário personalizada gerada que pode mudar a maneira como eles se comportam.
               Um exemplo pode ser encontrado abaixo é a colocação de um arquivo profile do projeto.
            </para>

            <programlisting language="text"><![CDATA[
zf --setup storage-directory
]]></programlisting>
        </sect3>

        <sect3 id="zend.tool.usage.cli.environment-customization.configuration-file">
            <title>O Arquivo de Configuração</title>

            <para>
                Isto irá criar o arquivo zf.ini adequado. Este <emphasis> deve </emphasis>
                ser executado após <command>zf --setup storage-directory</command>. Se não for,
                será localizado dentro do diretório home do usuário. Se for, ele será localizado
                dentro do storage directory do usuário.
            </para>

            <programlisting language="text"><![CDATA[
zf --setup config-file
]]></programlisting>
        </sect3>

        <sect3 id="zend.tool.usage.cli.environment-customization.environment-locations">
            <title>Environment Locations</title>

            <para>
                Estes devem ser configurados, se você deseja substituir os locais padrão onde o zf
                tentará de ler os seus valores.
            </para>

            <itemizedlist>
                <listitem>
                    <para>ZF_HOME</para>

                    <itemizedlist>
                        <listitem>
                            <para>o diretório onde a ferramenta irá procurar um diretório home</para>
                        </listitem>

                        <listitem><para>o diretório deve existir</para></listitem>

                        <listitem>
                            <para>ordem de pesquisa:</para>

                            <itemizedlist>
                                <listitem><para>variável de ambiente ZF_HOME</para></listitem>
                                <listitem><para>variável de ambiente HOME</para></listitem>
                                <listitem><para>então a variável de ambiente HOMEPATH</para></listitem>
                            </itemizedlist>
                        </listitem>
                    </itemizedlist>
                </listitem>

                <listitem>
                    <para>ZF_STORAGE_DIRECTORY</para>

                    <itemizedlist>
                        <listitem>
                            <para>onde esta ferramenta vai procurar por um storage directory</para>
                        </listitem>

                        <listitem><para>o diretório deve existir</para></listitem>

                        <listitem>
                            <para>ordem de pesquisa:</para>

                            <itemizedlist>
                                <listitem>
                                    <para>variável de ambiente ZF_STORAGE_DIRECTORY</para>
                                </listitem>

                                <listitem><para>diretório $homeDirectory/.zf/</para></listitem>
                            </itemizedlist>
                        </listitem>
                    </itemizedlist>
                </listitem>

                <listitem>
                    <para>ZF_CONFIG_FILE</para>

                    <itemizedlist>
                        <listitem>
                            <para>onde esta ferramenta vai procurar pelo arquivo de configuração</para>
                        </listitem>

                        <listitem>
                            <para>ordem de pesquisa:</para>

                            <itemizedlist>
                                <listitem>
                                    <para>variável de ambiente ZF_CONFIG_FILE</para>
                                </listitem>

                                <listitem>
                                    <para>se existir o arquivo $homeDirectory/.zf.ini</para>
                                </listitem>

                                <listitem>
                                    <para>se existir o arquivo $storageDirectory/zf.ini</para>
                                </listitem>
                            </itemizedlist>
                        </listitem>
                    </itemizedlist>
                </listitem>

                <listitem>
                    <para>ZEND_TOOL_INCLUDE_PATH</para>

                    <itemizedlist>
                        <listitem>
                            <para>configura o include_path para esta ferramenta usar este valor</para>
                        </listitem>

                        <listitem>
                            <para>comportamento original:</para>

                            <itemizedlist>
                                <listitem>
                                    <para>
                                        usa o include_path do <acronym>PHP</acronym> para procurar o ZF
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>usa a variável de ambiente ZEND_TOOL_INCLUDE_PATH</para>
                                </listitem>

                                <listitem>
                                    <para>
                                        usa o caminho ../library (relativo para zf.php) para procurar o ZF
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </listitem>
                    </itemizedlist>
                </listitem>

                <listitem>
                    <para>ZF_TOOL_INCLUDE_PATH_PREPEND</para>

                    <itemizedlist>
                        <listitem>
                            <para>precede o php.ini include_path atual com este valor</para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>
</sect1>