repo_zf1/documentation/manual/pt-br/module_specs/Zend_Controller-QuickStart.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.controller.quickstart">
    <title>Guia de Início Rápido do Zend_Controller</title>

    <sect2 id="zend.controller.quickstart.introduction">
        <title>Introdução</title>

        <para>
            <classname>Zend_Controller</classname> é o coração do sistema <acronym>MVC</acronym>
            do Zend Framework. <acronym>MVC</acronym> significa <ulink
            url="http://en.wikipedia.org/wiki/Model-view-controller">Model-View-Controller</ulink>
            e é um padrão de projeto voltado para a separação da lógica de aplicação da lógica
            de visualização. <classname>Zend_Controller_Front</classname> implementa o padrão
            <ulink url="http://www.martinfowler.com/eaaCatalog/frontController.html">Front
            Controller</ulink>, no qual todos os pedidos são interceptados pelo controlador
            frontal e despachados individualmente para ações baseadas no
            <acronym>URL</acronym> requerido.
        </para>

        <para>
            O sistema <classname>Zend_Controller</classname> foi construído com a extensibilidade
            em mente, tanto por derivação das classes existentes, como escrevendo novas classes
            que implementam as várias interfaces e classes abstratas que formam a fundação da
            família de classes controladoras, ou escrevendo plugins ou auxiliadores de ação para
            aumentar ou manipular a funcionalidade do sistema.
        </para>
    </sect2>

    <sect2 id="zend.controller.quickstart.go">
        <title>Início Rápido</title>

        <para>
            Se você necessita de informações mais detalhadas, veja as seções seguintes.
            Se você quiser apenas começar rápido, continue lendo.
        </para>

        <sect3 id="zend.controller.quickstart.go.directory">
            <title>Criando a Estrutura de Arquivos</title>

            <para>
                O primeiro passo é criar sua estrutura de arquivos.
                A estrutura típica é a seguinte:
            </para>

            <programlisting language="php"><![CDATA[
application/
    controllers/
        IndexController.php
    models/
    views/
        scripts/
            index/
                index.phtml
        helpers/
        filters/
html/
    .htaccess
    index.php
]]></programlisting>
        </sect3>

        <sect3 id="zend.controller.quickstart.go.docroot">
            <title>Estabelecendo seu Documento Raiz</title>

            <para>
                No seu servidor web, defina seu documento raiz para o diretório
                <filename>html/</filename> da estrutura de arquivos acima mencionada.
            </para>
        </sect3>

        <sect3 id="zend.controller.quickstart.go.rewrite">
            <title>Criando as Regras de Reescrita</title>

            <para>
                Edite o arquivo <filename>html/.htaccess</filename> acima para ficar como:
            </para>

            <programlisting language="php"><![CDATA[
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ index.php [NC,L]
]]></programlisting>

            <note>
                <title>Saiba mais sobre o mod_rewrite</title>

                <para>
                    As regras de reescrita acima permitem o acesso a qualquer arquivo no documento
                    raiz de seu host virtual. Se houver arquivos que você não quer expor desta
                    maneira, você pode ser mais restritivo em suas regras. Vá até o site do Apache
                    para <ulink
                        url="http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html">aprender mais
                        sobre o mod_rewrite</ulink>.
                </para>
            </note>

            <para>
                Se estiver usando o <acronym>IIS</acronym> 7.0, utilize o seguinte como sua
                configuração de reescrita:
            </para>

            <programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
     <system.webServer>
         <rewrite>
             <rules>
                 <rule name="Imported Rule 1" stopProcessing="true">
                     <match url="^.*$" />
                     <conditions logicalGrouping="MatchAny">
                         <add input="{REQUEST_FILENAME}"
                             matchType="IsFile" pattern=""
                             ignoreCase="false" />
                         <add input="{REQUEST_FILENAME}"
                             matchType="IsDirectory"
                             pattern="" ignoreCase="false" />
                     </conditions>
                     <action type="None" />
                 </rule>
                 <rule name="Imported Rule 2" stopProcessing="true">
                     <match url="^.*$" />
                     <action type="Rewrite" url="index.php" />
                 </rule>
             </rules>
         </rewrite>
     </system.webServer>
</configuration>
]]></programlisting>

            <para>
                As regras acima irão encaminhar os pedidos de recursos existentes (links
                simbólicos existentes, arquivos não vazios, ou diretórios não vazios) nesse
                sentido, e todos os outros pedidos para o controlador frontal.
            </para>

            <note>
                <para>
                    As regras de reescrita acima são para o Apache, para exemplos de regras de
                    reescrita de outros servidores web, consulte a <link
                    linkend="zend.controller.router.introduction">documentação do roteador</link>.
                </para>
            </note>
        </sect3>

        <sect3 id="zend.controller.quickstart.go.bootstrap">
            <title>Criando o Arquivo de Inicialização</title>

            <para>
                O arquivo de inicialização é a página onde passam todas as requisições
                -- <filename>html/index.php</filename> no caso. Abra o arquivo
                <filename>html/index.php</filename> em um editor de sua escolha
                e adicione o seguinte:
            </para>

            <programlisting language="php"><![CDATA[
Zend_Controller_Front::run('/path/to/app/controllers');
]]></programlisting>

            <para>
                Isto irá instanciar e despachar o controlador frontal, que irá encaminhar as
                requisições para os controladores de ação.
            </para>
        </sect3>

        <sect3 id="zend.controller.quickstart.go.controller">
            <title>Criando o Controlador de Ação Padrão</title>

            <para>
                Antes de discutir sobre os controladores de ação, você deve primeiro entender como
                as requisições são roteadas no Zend Framework. Por padrão, o primeiro seguimento
                de um caminho de um <acronym>URL</acronym> aponta para um controlador, o segundo
                para uma ação. Por exemplo, dado o <acronym>URL</acronym>
                <filename>http://framework.zend.com/roadmap/components</filename>, o caminho é
                <filename>/roadmap/components</filename>, que irá apontar para o controlador
                <emphasis>roadmap</emphasis> e para a ação <emphasis>components</emphasis>. Se
                nenhuma ação for informada, a ação <emphasis>index</emphasis> é assumida, e se
                nenhum controlador for informado, o controlador <emphasis>index</emphasis> é
                assumido (seguindo a convenção do Apache que mapeia um
                <emphasis>DirectoryIndex</emphasis> automaticamente).
            </para>

            <para>
                O despachador do <classname>Zend_Controller</classname> toma o valor do
                controlador e mapeia-o para uma classe. Por padrão, ele pega o nome do
                controlador, com a primeira letra em maiúsculo, e acrescenta a palavra
                <emphasis>Controller</emphasis>. Sendo assim, em nosso exemplo acima, o
                controlador <emphasis>roadmap</emphasis> é mapeado para a classe
                <classname>RoadmapController</classname>.
            </para>

            <para>
                Semelhantemente, o valor da ação é mapeado para um método da classe do controlador.
                Por padrão, o valor é transformado em letras minúsculas, e a palavra
                <emphasis>Action</emphasis> é acrescentada. Sendo assim, em nosso exemplo acima, a
                ação <emphasis>components</emphasis> torna-se
                <methodname>componentsAction()</methodname>, e o método final chamado é
                <methodname>RoadmapController::componentsAction()</methodname>.
            </para>

            <para>
                Então, seguindo em frente, vamos agora criar um controlador de ação padrão e um
                método de ação. Como mencionado anteriormente, o controlador padrão e a ação são
                ambos chamados <emphasis>index</emphasis>. Abra o arquivo
                <filename>application/controllers/IndexController.php</filename>, e introduza
                o seguinte:
            </para>

            <programlisting language="php"><![CDATA[
/** Zend_Controller_Action */
class IndexController extends Zend_Controller_Action
{
    public function indexAction()
    {
    }
}
]]></programlisting>

            <para>
                O auxiliar de ação <link
                    linkend="zend.controller.actionhelpers.viewrenderer">ViewRenderer</link> é
                habilitado por padrão. Isto significa que apenas definindo um método de ação
                simples e o script de visão correspondente, você terá o seu conteúdo mostrador
                imediatamente. Por padrão, <classname>Zend_View</classname> é usado como a camada
                de Visualização do <acronym>MVC</acronym>. O <emphasis>ViewRenderer</emphasis>
                faz alguma mágica, e usa o nome do controlador (ex.: <emphasis>index</emphasis>)
                e o nome da ação atual (ex.: <emphasis>index</emphasis>) para determinar qual
                modelo mostrar. Por padrão, modelos terminam com a extensão
                <filename>.phtml</filename>, então isto significa que, no exemplo acima o modelo
                <filename>index/index.phtml</filename> será mostrado. Adicionalmente, o
                <emphasis>ViewRenderer</emphasis> automaticamente assume que o diretório
                <filename>views/</filename>, que está no mesmo nível que do diretório do
                controlador, será o diretório base de visualização, e que o atual script de
                visualização estará no subdiretório <filename>views/scripts/</filename>, Sendo
                assim, o modelo mostrado é encontrado em
                <filename>application/views/scripts/index/index.phtml</filename>.
            </para>
        </sect3>

        <sect3 id="zend.controller.quickstart.go.view">
            <title>Criando o Script de Visualização</title>

            <para>
                Com mensionado <link linkend="zend.controller.quickstart.go.controller">na seção
                anterior</link>, scripts de visualização são encontrados em
                <filename>application/views/scripts/</filename>; O script padrão para o
                controlador e ação padrão está em
                <filename>application/views/scripts/index/index.phtml</filename>. Crie este
                arquivo e escreva nele algum <acronym>HTML</acronym>:
            </para>

            <programlisting language="php"><![CDATA[
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <title>Meu primeiro aplicativo em Zend Framework</title>
</head>
<body>
    <h1>Olá, Mundo!</h1>
</body>
</html>
]]></programlisting>
        </sect3>

        <sect3 id="zend.controller.quickstart.go.errorhandler">
            <title>Criando o Controlador de Erro</title>

            <para>
                Por padrão, o <link linkend="zend.controller.plugins.standard.errorhandler">plugin
                do manipulador de erro</link> é registrado. Este plugin espera que um controlador
                para manipular erros exista. Por padrão, ele assume um
                <emphasis>ErrorController</emphasis> no módulo padrão com um método
                <methodname>errorAction()</methodname>:
            </para>

            <programlisting language="php"><![CDATA[
class ErrorController extends Zend_Controller_Action
{
    public function errorAction()
    {
    }
}
]]></programlisting>

            <para>
                Assumindo a estrutura de diretório já discutida, este arquivo estará em
                <filename>application/controllers/ErrorController.php</filename>. Você também
                precisará criar o script de visualização em
                <filename>application/views/scripts/error/error.phtml</filename>; o conteúdo
                do exemplo parecerá com:
            </para>

            <programlisting language="php"><![CDATA[
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <title>Erro</title>
</head>
<body>
    <h1>Ocorreu um erro</h1>
    <p>Ocorreu um erro; por favor, tente novamente mais tarde.</p>
</body>
</html>
]]></programlisting>
        </sect3>

        <sect3 id="zend.controller.quickstart.go.finish">
            <title>Veja o Site!</title>

            <para>
                Com o seu primeiro controlador e visualizador em suas mãos, você agora pode abrir
                o seu navegador e navegar até o site. Assumindo que o seu domínio é
                <filename>example.com</filename>, qualquer dos seguintes <acronym>URL</acronym>s
                irão mostrar a página que acabamos de criar:
            </para>

            <itemizedlist>
                <listitem>
                    <para><filename>http://example.com/</filename></para>
                </listitem>

                <listitem>
                    <para><filename>http://example.com/index</filename></para>
                </listitem>

                <listitem>
                    <para><filename>http://example.com/index/index</filename></para>
                </listitem>
            </itemizedlist>

            <para>
                Agora você está pronto para iniciar a criação de mais controladores
                e metódos de ação. Parabéns!
            </para>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->