Skip to content

Commit 959a2c3

Browse files
weaverryanweaverryan
committed
Merge branch 'WouterJ-clearify_redirectcontroller' into 2.2
2 parents aca771e + 37b13e1 commit 959a2c3

File tree

1 file changed

+151
-28
lines changed

1 file changed

+151
-28
lines changed

‎cookbook/routing/redirect_in_config.rst

+151-28
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,163 @@
11
.. index::
2-
single: Routing; Configure redirect to another route without a custom controller
2+
single: Routing; Redirect using Framework:RedirectController
33

4-
How to configure a redirect to another route without a custom controller
5-
========================================================================
4+
How to Configure a Redirect without a Custom Controller
5+
=======================================================
66

7-
This guide explains how to configure a redirect from one route to another
8-
without using a custom controller.
7+
Sometimes, a URL needs to redirect to another URL. You can do that by creating
8+
a new controller action whose only task is to redirect, but using the
9+
:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController` of
10+
the FrameworkBundle is even easier.
911

10-
Assume that there is no useful default controller for the ``/`` path of
11-
your application and you want to redirect these requests to ``/app``.
12+
You can redirect to a specific path (e.g. ``/about``) or to a specific route
13+
using its name (e.g. ``homepage``).
1214

13-
Your configuration will look like this:
15+
Redirecting Using a Path
16+
------------------------
1417

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

17-
AppBundle:
18-
resource: "@App/Controller/"
19-
type: annotation
20-
prefix: /app
23+
.. configuration-block::
2124

22-
root:
23-
path: /
24-
defaults:
25-
_controller: FrameworkBundle:Redirect:urlRedirect
26-
path: /app
27-
permanent: true
25+
.. code-block:: yaml
2826
29-
In this example, you configure a route for the ``/`` path and let :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController`
30-
handle it. This controller comes standard with Symfony and offers two actions
31-
for redirecting request:
27+
# app/config/routing.yml
3228
33-
* ``urlRedirect`` redirects to another *path*. You must provide the ``path``
34-
parameter containing the path of the resource you want to redirect to.
29+
# load some routes - one should ultimately have the path "/app"
30+
AppBundle:
31+
resource: "@AcmeAppBundle/Controller/"
32+
type: annotation
33+
prefix: /app
3534
36-
* ``redirect`` (not shown here) redirects to another *route*. You must provide the ``route``
37-
parameter with the *name* of the route you want to redirect to.
35+
# redirecting the root
36+
root:
37+
path: /
38+
defaults:
39+
_controller: FrameworkBundle:Redirect:urlRedirect
40+
path: /app
41+
permanent: true
3842
39-
The ``permanent`` switch tells both methods to issue a 301 HTTP status code
40-
instead of the default ``302`` status code.
43+
.. code-block:: xml
44+
45+
<!-- app/config/routing.xml -->
46+
<?xml version="1.0" encoding="UTF-8" ?>
47+
<routes xmlns="http://symfony.com/schema/routing"
48+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
49+
xsi:schemaLocation="http://symfony.com/schema/routing
50+
http://symfony.com/schema/routing/routing-1.0.xsd">
51+
52+
<!-- load some routes - one should ultimately have the path "/app" -->
53+
<import resource="@AcmeAppBundle/Controller/"
54+
type="annotation"
55+
prefix="/app"
56+
/>
57+
58+
<!-- redirecting the root -->
59+
<route id="root" path="/">
60+
<default key="_controller">FrameworkBundle:Redirect:urlRedirect</default>
61+
<default key="path">/app</default>
62+
<default key="permanent">true</default>
63+
</route>
64+
</routes>
65+
66+
.. code-block:: php
67+
68+
// app/config/routing.php
69+
use Symfony\Component\Routing\RouteCollection;
70+
use Symfony\Component\Routing\Route;
71+
72+
$collection = new RouteCollection();
73+
74+
// load some routes - one should ultimately have the path "/app"
75+
$acmeApp = $loader->import(
76+
"@AcmeAppBundle/Controller/",
77+
"annotation"
78+
);
79+
$acmeApp->setPrefix('/app');
80+
81+
$collection->addCollection($acmeApp);
82+
83+
// redirecting the root
84+
$collection->add('root', new Route('/', array(
85+
'_controller' => 'FrameworkBundle:Redirect:urlRedirect',
86+
'path' => '/app',
87+
'permanent' => true,
88+
)));
89+
90+
return $collection;
91+
92+
In this example, you configured a route for the ``/`` path and let the
93+
``RedirectController`` redirect it to ``/app``. The ``permanent`` switch
94+
tells the action to issue a ``301`` HTTP status code instead of the default
95+
``302`` HTTP status code.
96+
97+
Redirecting Using a Route
98+
-------------------------
99+
100+
Assume you are migrating your website from WordPress to Symfony, you want to
101+
redirect ``/wp-admin`` to the route ``sonata_admin_dashboard``. You don't know
102+
the path, only the route name. This can be achieved using the
103+
:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::redirect`
104+
action:
105+
106+
.. configuration-block::
107+
108+
.. code-block:: yaml
109+
110+
# app/config/routing.yml
111+
112+
# ...
113+
114+
# redirecting the admin home
115+
root:
116+
path: /wp-admin
117+
defaults:
118+
_controller: FrameworkBundle:Redirect:redirect
119+
route: sonata_admin_dashboard
120+
permanent: true
121+
122+
.. code-block:: xml
123+
124+
<!-- app/config/routing.xml -->
125+
<?xml version="1.0" encoding="UTF-8" ?>
126+
<routes xmlns="http://symfony.com/schema/routing"
127+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
128+
xsi:schemaLocation="http://symfony.com/schema/routing
129+
http://symfony.com/schema/routing/routing-1.0.xsd">
130+
131+
<!-- ... -->
132+
133+
<!-- redirecting the admin home -->
134+
<route id="root" path="/wp-admin">
135+
<default key="_controller">FrameworkBundle:Redirect:redirect</default>
136+
<default key="route">sonata_admin_dashboard</default>
137+
<default key="permanent">true</default>
138+
</route>
139+
</routes>
140+
141+
.. code-block:: php
142+
143+
// app/config/routing.php
144+
use Symfony\Component\Routing\RouteCollection;
145+
use Symfony\Component\Routing\Route;
146+
147+
$collection = new RouteCollection();
148+
// ...
149+
150+
// redirecting the root
151+
$collection->add('root', new Route('/wp-admin', array(
152+
'_controller' => 'FrameworkBundle:Redirect:redirect',
153+
'route' => 'sonata_admin_dashboard',
154+
'permanent' => true,
155+
)));
156+
157+
return $collection;
158+
159+
.. caution::
160+
161+
Because you are redirecting to a route instead of a path, the required
162+
option is called ``route`` in the ``redirect`` action, instead of ``path``
163+
in the ``urlRedirect`` action.

0 commit comments

Comments
 (0)