Skip to content

Trying to clarify redirecting article #3071

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 17, 2013
Merged

Trying to clarify redirecting article #3071

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 151 additions & 28 deletions cookbook/routing/redirect_in_config.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,163 @@
.. index::
single: Routing; Configure redirect to another route without a custom controller
single: Routing; Redirect using Framework:RedirectController

How to configure a redirect to another route without a custom controller
========================================================================
How to Configure a Redirect Without a Custom Controller
=======================================================

This guide explains how to configure a redirect from one route to another
without using a custom controller.
Sometimes, a URL needs to redirect to another URL. You can do that by creating
a new controller action which only task is to redirect, but using the
:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController` of
the FrameworkBundle, it's a lot easier.

Assume that there is no useful default controller for the ``/`` path of
your application and you want to redirect these requests to ``/app``.
You can redirect to a specific path (e.g. ``/about``) or to a specific route
using it's name (e.g. ``homepage``).

Your configuration will look like this:
Redirecting Using a Path
------------------------

.. code-block:: yaml
Assume there is no default controller for the ``/`` path of your application
and you want to redirect these requests to ``/app``. You will need to use the
:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::urlRedirect`
action to redirect to this new url:

AppBundle:
resource: "@App/Controller/"
type: annotation
prefix: /app
.. configuration-block::

root:
path: /
defaults:
_controller: FrameworkBundle:Redirect:urlRedirect
path: /app
permanent: true
.. code-block:: yaml

In this example, you configure a route for the ``/`` path and let :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController`
handle it. This controller comes standard with Symfony and offers two actions
for redirecting request:
# app/config/routing.yml

* ``urlRedirect`` redirects to another *path*. You must provide the ``path``
parameter containing the path of the resource you want to redirect to.
# loading the App controllers
AppBundle:
resource: "@AcmeAppBundle/Controller/"
type: annotation
prefix: /app

* ``redirect`` (not shown here) redirects to another *route*. You must provide the ``route``
parameter with the *name* of the route you want to redirect to.
# redirecting the root
root:
path: /
defaults:
_controller: FrameworkBundle:Redirect:urlRedirect
path: /app
permanent: true

The ``permanent`` switch tells both methods to issue a 301 HTTP status code
instead of the default ``302`` status code.
.. code-block:: xml

<!-- app/config/routing.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/routing
http://symfony.com/schema/routing/routing-1.0.xsd">

<!-- loading the App controllers -->
<import resource="@AcmeAppBundle/Controller/"
type="annotation"
prefix="/app"
/>

<!-- redirecting the root -->
<route id="root" path="/">
<default key="_controller">FrameworkBundle:Redirect:urlRedirect</default>
<default key="path">/app</default>
<default key="permanent">true</default>
</route>
</routes>

.. code-block:: php

// app/config/routing.php
use Symfony\Component\Routing\RouteCollection;
use Symfony\Component\Routing\Route;

$collection = new RouteCollection();

// loading the App controllers
$acmeApp = $loader->import(
"@AcmeAppBundle/Controller/",
"annotation"
);
$acmeApp->setPrefix('/app');

$collection->addCollection($acmeApp);

// redirecting the root
$collection->add('root', new Route('/', array(
'_controller' => 'FrameworkBundle:Redirect:urlRedirect',
'path' => '/app',
'permanent' => true,
)));

return $collection;

In this example, you configured a route for the ``/`` path and let the
``RedirectController`` handle it to redirect it to ``/app``. The ``permanent``
switch tells the action to issue a ``301`` HTTP status code instead of the
default ``302`` HTTP status code.

Redirecting Using a Route
-------------------------

Assume you are migrating your website from WordPress to Symfony, you want to
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice example :shipit:

redirect ``/wp-admin`` to the route ``sonata_admin_dashboard``. You don't know
the path, only the route name. This can be achieved using the
:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::redirect`
action:

.. configuration-block::

.. code-block:: yaml

# app/config/routing.yml

# ...

# redirecting the admin home
root:
path: /wp-admin
defaults:
_controller: FrameworkBundle:Redirect:redirect
route: sonata_admin_dashboard
permanent: true

.. code-block:: xml

<!-- app/config/routing.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/routing
http://symfony.com/schema/routing/routing-1.0.xsd">

<!-- ... -->

<!-- redirecting the admin home -->
<route id="root" path="/wp-admin">
<default key="_controller">FrameworkBundle:Redirect:redirect</default>
<default key="route">sonata_admin_dashboard</default>
<default key="permanent">true</default>
</route>
</routes>

.. code-block:: php

// app/config/routing.php
use Symfony\Component\Routing\RouteCollection;
use Symfony\Component\Routing\Route;

$collection = new RouteCollection();
// ...

// redirecting the root
$collection->add('root', new Route('/wp-admin', array(
'_controller' => 'FrameworkBundle:Redirect:redirect',
'route' => 'sonata_admin_dashboard',
'permanent' => true,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe a word on the permanent could improve understanding too

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's on line 92

)));

return $collection;

.. caution::

Because you are redirecting to a route instead of a path, the required
option is called ``route`` in the ``redirect`` action, instead of ``path``
in the ``urlRedirect`` action.