# Redirector

## Introduction

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

The Redirector has a number of methods that can be used to affect the behaviour at redirect:

- `setCode()` can be used to set the HTTP response code to use during the redirect.

- `setExit()` can be used to force an `exit()` following a redirect. By default this is `TRUE`.

- `setGotoSimple()` can be used to set a default URL to use if none is passed to `gotoSimple()`. Uses the API of `Zend_Controller_Action::_forward()`: `setGotoSimple($action, $controller = null, $module = null, array $params = array())`

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

- `setGotoUrl()` can be used to set a default URL to use if none is passed to `gotoUrl()`. Accepts a single URL string.

- `setPrependBase()` can be used to prepend the request object's base URL to a URL specified with `setGotoUrl()`, `gotoUrl()`, or `gotoUrlAndExit()`.

- `setUseAbsoluteUri()` can be used to force the Redirector to use absolute URIs when redirecting. When this option is set, it uses the value of `$_SERVER['HTTP_HOST']`, `$_SERVER['SERVER_PORT']`, and `$_SERVER['HTTPS']` to form a full URI to the URL specified by one of the redirect methods. This option is off by default, but may be enabled by default in later releases.

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

- `gotoSimple()` uses `setGotoSimple()` (`_forward()`-like API) to build a URL and perform a redirect.

- `gotoRoute()` uses `setGotoRoute()` (route-assembly) to build a URL and perform a redirect.

- `gotoUrl()` uses `setGotoUrl()` (URL string) to build a URL and perform a redirect.

Finally, you can determine the current redirect URL at any time using `getRedirectUrl()`.

## Basic Usage Examples

### Setting Options

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

    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
        }
    }

### Using Defaults

This example assumes that the defaults are used, which means that any redirect will result in an immediate `exit()`.

    // 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
        }
    }

### Using goto()'s _forward() API

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

    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'
                                                 )
                                           );
        }
    }

### Using Route Assembly with gotoRoute()

The following example uses the router's `assemble()` method to create a URL based on an associative array of parameters passed. It assumes the following route has been registered:

    $route = new Zend_Controller_Router_Route(
        'blog/:year/:month/:day/:id',
        array('controller' => 'archive',
              'module' => 'blog',
              'action' => 'view')
    );
    $router->addRoute('blogArchive', $route);

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

    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'
            );
        }
    }