<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect3 id="zend.controller.actionhelpers.redirector">
    <title>Redirector</title>

    <sect4 id="zend.controller.actionhelper.redirector.introduction">
        <title>Introduction</title>

        <para>
            The <emphasis>Redirector</emphasis> helper allows you to use a redirector
            object to fulfill your application's needs for redirecting to a new
            <acronym>URL</acronym>. It provides numerous benefits over the
            <methodname>_redirect()</methodname> method, such as being able to preconfigure
            sitewide behavior into the redirector object or using the built in
            <methodname>gotoSimple($action, $controller, $module, $params)</methodname> interface
            similar to that of <methodname>Zend_Controller_Action::_forward()</methodname>.
        </para>

        <para>
            The <emphasis>Redirector</emphasis> has a number of methods that can be used
            to affect the behaviour at redirect:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setCode()</methodname> can be used to set the
                    <acronym>HTTP</acronym> response code to use during the redirect.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setExit()</methodname> can be used to force an
                    <methodname>exit()</methodname> following a redirect. By default this is
                    <constant>TRUE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setGotoSimple()</methodname> can be used to set a default
                    <acronym>URL</acronym> to use if none is passed to
                    <methodname>gotoSimple()</methodname>. Uses the <acronym>API</acronym>
                    of <methodname>Zend_Controller_Action::_forward()</methodname>:
                    <methodname>setGotoSimple($action, $controller = null, $module = null, array
                    $params = array())</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setGotoRoute()</methodname> can be used to set a
                    <acronym>URL</acronym> based on a registered route. Pass in an array of
                    key / value pairs and a route name, and it will assemble the
                    <acronym>URL</acronym> according to the route type and definition.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setGotoUrl()</methodname> can be used to set a default
                    <acronym>URL</acronym> to
                    use if none is passed to <methodname>gotoUrl()</methodname>. Accepts a
                    single <acronym>URL</acronym> string.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setPrependBase()</methodname> can be used to prepend the
                    request object's base <acronym>URL</acronym> to a <acronym>URL</acronym>
                    specified with
                    <methodname>setGotoUrl()</methodname>, <methodname>gotoUrl()</methodname>, or
                    <methodname>gotoUrlAndExit()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setUseAbsoluteUri()</methodname> can be used to force the
                    <emphasis>Redirector</emphasis> to use absolute <acronym>URI</acronym>s when
                    redirecting. When this option is set, it uses the value of
                    <varname>$_SERVER['HTTP_HOST']</varname>,
                    <varname>$_SERVER['SERVER_PORT']</varname>, and
                    <varname>$_SERVER['HTTPS']</varname> to form a full <acronym>URI</acronym>
                    to the <acronym>URL</acronym>
                    specified by one of the redirect methods. This option is off
                    by default, but may be enabled by default in later releases.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Additionally, there are a variety of methods in the redirector for
            performing the actual redirects:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>gotoSimple()</methodname> uses
                    <methodname>setGotoSimple()</methodname>
                    (<methodname>_forward()</methodname>-like <acronym>API</acronym>) to build a
                    <acronym>URL</acronym> and perform a redirect.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>gotoRoute()</methodname> uses
                    <methodname>setGotoRoute()</methodname>
                    (<emphasis>route-assembly</emphasis>) to build a <acronym>URL</acronym> and
                    perform a redirect.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>gotoUrl()</methodname> uses <methodname>setGotoUrl()</methodname>
                    (<emphasis><acronym>URL</acronym> string</emphasis>) to build a
                    <acronym>URL</acronym> and perform a redirect.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Finally, you can determine the current redirect <acronym>URL</acronym> at any time
            using <methodname>getRedirectUrl()</methodname>.
        </para>
    </sect4>

    <sect4 id="zend.controller.actionhelper.redirector.basicusage">
        <title>Basic Usage Examples</title>

        <example id="zend.controller.actionhelper.redirector.basicusage.example-1">
            <title>Setting Options</title>

            <para>
                This example overrides several options, including setting the
                <acronym>HTTP</acronym> status code to use in the redirect ('303'), not defaulting
                to exit on redirect, and defining a default <acronym>URL</acronym> to use when
                redirecting.
            </para>

            <programlisting language="php"><![CDATA[
class SomeController extends Zend_Controller_Action
{
    /**
     * Redirector - defined for code completion
     *
     * @var Zend_Controller_Action_Helper_Redirector
     */
    protected $_redirector = null;

    public function init()
    {
        $this->_redirector = $this->_helper->getHelper('Redirector');

        // Set the default options for the redirector
        // Since the object is registered in the helper broker, these
        // become relevant for all actions from this point forward
        $this->_redirector->setCode(303)
                          ->setExit(false)
                          ->setGotoSimple("this-action",
                                          "some-controller");
    }

    public function myAction()
    {
        /* do some stuff */

        // Redirect to a previously registered URL, and force an exit
        // to occur when done:
        $this->_redirector->redirectAndExit();
        return; // never reached
    }
}
]]></programlisting>
        </example>

        <example id="zend.controller.actionhelper.redirector.basicusage.example-2">
            <title>Using Defaults</title>

            <para>
                This example assumes that the defaults are used, which means
                that any redirect will result in an immediate
                <methodname>exit()</methodname>.
            </para>

            <programlisting language="php"><![CDATA[
// ALTERNATIVE EXAMPLE
class AlternativeController extends Zend_Controller_Action
{
    /**
     * Redirector - defined for code completion
     *
     * @var Zend_Controller_Action_Helper_Redirector
     */
    protected $_redirector = null;

    public function init()
    {
        $this->_redirector = $this->_helper->getHelper('Redirector');
    }

    public function myAction()
    {
        /* do some stuff */

        $this->_redirector
            ->gotoUrl('/my-controller/my-action/param1/test/param2/test2');
        return; // never reached since default is to goto and exit
    }
}
]]></programlisting>
        </example>

        <example id="zend.controller.actionhelper.redirector.basicusage.example-3">
            <title>Using goto()'s _forward() API</title>

            <para>
                <methodname>gotoSimple()</methodname>'s <acronym>API</acronym> mimics that of
                <methodname>Zend_Controller_Action::_forward()</methodname>. The primary
                difference is that it builds a <acronym>URL</acronym> from the parameters passed,
                and using the default <filename>:module/:controller/:action/*</filename>
                format of the default router. It then redirects instead of
                chaining the action.
            </para>

            <programlisting language="php"><![CDATA[
class ForwardController extends Zend_Controller_Action
{
    /**
     * Redirector - defined for code completion
     *
     * @var Zend_Controller_Action_Helper_Redirector
     */
    protected $_redirector = null;

    public function init()
    {
        $this->_redirector = $this->_helper->getHelper('Redirector');
    }

    public function myAction()
    {
        /* do some stuff */

        // Redirect to 'my-action' of 'my-controller' in the current
        // module, using the params param1 => test and param2 => test2
        $this->_redirector->gotoSimple('my-action',
                                       'my-controller',
                                       null,
                                       array('param1' => 'test',
                                             'param2' => 'test2'
                                             )
                                       );
    }
}
]]></programlisting>
        </example>

        <example id="zend.controller.actionhelper.redirector.basicusage.example-4">
            <title>Using Route Assembly with gotoRoute()</title>

            <para>
                The following example uses the <link
                    linkend="zend.controller.router">router's</link>
                <methodname>assemble()</methodname> method to create a <acronym>URL</acronym>
                based on an associative array of parameters passed. It assumes the following
                route has been registered:
            </para>

            <programlisting language="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'blog/:year/:month/:day/:id',
    array('controller' => 'archive',
          'module' => 'blog',
          'action' => 'view')
);
$router->addRoute('blogArchive', $route);
]]></programlisting>

            <para>
                Given an array with year set to 2006, month to 4, day to 24, and
                id to 42, it would then build the <acronym>URL</acronym>
                <filename>/blog/2006/4/24/42</filename>.
            </para>

            <programlisting language="php"><![CDATA[
class BlogAdminController extends Zend_Controller_Action
{
    /**
     * Redirector - defined for code completion
     *
     * @var Zend_Controller_Action_Helper_Redirector
     */
    protected $_redirector = null;

    public function init()
    {
        $this->_redirector = $this->_helper->getHelper('Redirector');
    }

    public function returnAction()
    {
        /* do some stuff */

        // Redirect to blog archive. Builds the following URL:
        // /blog/2006/4/24/42
        $this->_redirector->gotoRoute(
            array('year' => 2006,
                  'month' => 4,
                  'day' => 24,
                  'id' => 42),
            'blogArchive'
        );
    }
}
]]></programlisting>
        </example>
    </sect4>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->
