路由

2.8 版本

维护中的版本

3.4 current 4.2 master

难易度：中等

对于任何严谨的web应用程序而言美观的URL是绝对必须的。这意味着index.php?article_id=57这类丑陋的URL要被/read/intro-to-symfony取代。

拥有灵活性是更加重要的。你将页面的URL从/blog改为/news时需要做些什么？你需要跟踪和更新多少链接以做出改变？如果你使用Symfony的路由，这就很容易了。

Symfony路由器允许你定义创造性的url，映射到应用程序的不同区域。在本章结束时，你将可以做到：

创建复杂的路由，它们将映射到控制器
在模板和控制器中生成URL
从Bundle中（也可以从其它地方）加载路由资源
对路由除错

---路由样例---

一个路由，是指一个URL路径（path)到一个控制器(controller）的映射。例如，你想匹配一些URL：/blog/my-post 和 /blog/all-about-symfony，并且发送路由到一个“能够查询和渲染那一篇博文”的控制器上。路由简单的很：

// src/AppBundle/Controller/BlogController.php
namespace AppBundle\Controller;
 
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
 
class BlogController extends Controller
{
    /**
     * @Route("/blog/{slug}", name="blog_show")
     */
    public function showAction($slug)
    {
        // ...
    }
}

# app/config/routing.yml
blog_show:
    path:      /blog/{slug}
    defaults:  { _controller: AppBundle:Blog:show }

<!-- 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">
 
    <route id="blog_show" path="/blog/{slug}">
        <default key="_controller">AppBundle:Blog:show</default>
    </route>
</routes>

// app/config/routing.php
use Symfony\Component\Routing\RouteCollection;
use Symfony\Component\Routing\Route;
 
$collection = new RouteCollection();
$collection->add('blog_show', new Route('/blog/{slug}', array(
    '_controller' => 'AppBundle:Blog:show',
)));
 
return $collection;

定义blog_show路由模式，用于匹配像/blog/*的URL，把相关参数或通配符用slug表示并传入。对于/blog/my-blog-post这样的URL，slug变量得到my-blog-post的值，并供你控制器使用。美观blog_show是一个内部名称，他没什么实际的意义就是一个唯一的标识。以后，你可用他来生成一些URL。

如果你不想去使用注释方式，因为你不喜欢他们，或者因为你不希望依赖于SensioFrameworkExtraBundle，你也可以使用YAML，XML或者PHP。在这些格式中，_controller参数是一个特殊的键，它告诉symfony路由指定的URL应该执行哪个控制器。_controller字符串称为逻辑名。它遵循规则指向一个特定的php类和方法，AppBundle\Controller\BlogController::showAction方法。

恭喜！你刚刚创建了一个路由并把它连接到控制器。现在，当你访问/blog/my-post，showAction控制器将被执行并且$slug变量就等于my-post。

Symfony路由的目标：将请求的URL映射到控制器。遵循这一目标，你将学习到各式各样的技巧，甚至使映射大多数复杂的URL变得简单。

---路由：深入了解---

当一个请求发送到你的应用程序，它包含一个确切的“资源”的客户端请求地址。该地址被称为URL（或URI），它可以是/contact、/blog/read-me或其它任何东西。下面是一个HTTP请求的例子：

1	GET /blog/my-blog-post

symfony路由系统的目的是解析url，并确定调用哪个控制器。整个过程是这样的：

由Symfony的前端控制器（如app.php）来处理请求。
symfony的核心（Kernel内核）要求路由器来检查请求。
路由将输入的URL匹配到一个特定的路由,并返回路由信息，其中包括要执行的控制器信息。
Symfony内核执行控制器并最终返回Response对象。

request-flow

路由是将一个输入URL转换成特定的工具来执行控制器。

---创建路由---

Symfony从一个单一的路由配置文件中加载所有的路由到你的应用程序。美观路由配置文件通常是app/config/routing.yml,但你也可以通过应用程序配置文件将该文件放置在任何地方（包括xml或php格式的配置文件）。

# app/config/config.yml
framework:
    # ...
    router: { resource: '%kernel.root_dir%/config/routing.yml' }

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony
        http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <framework:config>
        <!-- ... -->
        <framework:router resource="%kernel.root_dir%/config/routing.xml" />
    </framework:config>
</container>

// app/config/config.php
$container->loadFromExtension('framework', array(
    // ...
    'router' => array(
        'resource' => '%kernel.root_dir%/config/routing.php',
    ),
));

Tip

尽管所有的路由都可以从一个文件加载，但是通常的做法是包含额外的路由资源。为此，你要把外部的路由文件配置到主要路由文件中。具体信息可查看本章：包含外部路由资源。

---基本的路由配置---1

定义一个路由是容易的，一个典型的应用程序也应该有很多的路由。一个基本的路由包含两个部分：path 匹配和defaults数组：

// src/AppBundle/Controller/MainController.php
 
// ...
class MainController extends Controller
{
    /**
     * @Route("/")
     */
    public function homepageAction()
    {
        // ...
    }
}

# app/config/routing.yml
_welcome:
    path:      /
    defaults:  { _controller: AppBundle:Main:homepage }

<!-- 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">
 
    <route id="_welcome" path="/">
        <default key="_controller">AppBundle:Main:homepage</default>
    </route>
 
</routes>

// app/config/routing.php
use Symfony\Component\Routing\RouteCollection;
use Symfony\Component\Routing\Route;
 
$collection = new RouteCollection();
$collection->add('_welcome', new Route('/', array(
    '_controller' => 'AppBundle:Main:homepage',
)));
 
return $collection;

该路由匹配首页（/）并将它映射到AppBundle:Main:homepage 控制器。_controller字符串被Symfony转换成PHP函数去执行。美观过程在本章（控制器命名模式）中被简短提及。

---带参数的路由---2

路由系统支持很多有趣的路由写法。许多的路由都可以包含一个或者多个“参数或通配符”占位符：

// src/AppBundle/Controller/BlogController.php
 
// ...
class BlogController extends Controller
{
    /**
     * @Route("/blog/{slug}")
     */
    public function showAction($slug)
    {
        // ...
    }
}

# app/config/routing.yml
blog_show:
    path:      /blog/{slug}
    defaults:  { _controller: AppBundle:Blog:show }

<!-- 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">
 
    <route id="blog_show" path="/blog/{slug}">
        <default key="_controller">AppBundle:Blog:show</default>
    </route>
</routes>

// app/config/routing.php
use Symfony\Component\Routing\RouteCollection;
use Symfony\Component\Routing\Route;
 
$collection = new RouteCollection();
$collection->add('blog_show', new Route('/blog/{slug}', array(
    '_controller' => 'AppBundle:Blog:show',
)));
 
return $collection;

美观路径将匹配任何/blog/*的URL。更妙的是，美观{slug}占位符将自动匹配到控制器中。换句话说，如果该URL是/blog/hello-world，控制器中$slug变量的值就是hello-world。这可以用来，匹配博客文章标题的字符串。

然而这种方式路由将不会匹配/blog这样的URL，因为默认情况下，所有的占位符都是必填的。当然这也是可以变通的，可以在defaults数组中添加占位符（参数）的值来实现。

---添加{通配符}的条件---

快速浏览一下已经创建的路由：

// src/AppBundle/Controller/BlogController.php
 
// ...
class BlogController extends Controller
{
    /**
     * @Route("/blog/{page}", defaults={"page" = 1})
     */
    public function indexAction($page)
    {
        // ...
    }
 
    /**
     * @Route("/blog/{slug}")
     */
    public function showAction($slug)
    {
        // ...
    }
}

# app/config/routing.yml
blog:
    path:      /blog/{page}
    defaults:  { _controller: AppBundle:Blog:index, page: 1 }

blog_show:
    path:      /blog/{slug}
    defaults:  { _controller: AppBundle:Blog:show }

<!-- 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">
 
    <route id="blog" path="/blog/{page}">
        <default key="_controller">AppBundle:Blog:index</default>
        <default key="page">1</default>
    </route>
 
    <route id="blog_show" path="/blog/{slug}">
        <default key="_controller">AppBundle:Blog:show</default>
    </route>
</routes>

// app/config/routing.php
use Symfony\Component\Routing\RouteCollection;
use Symfony\Component\Routing\Route;
 
$collection = new RouteCollection();
$collection->add('blog', new Route('/blog/{page}', array(
    '_controller' => 'AppBundle:Blog:index',
    'page'        => 1,
)));
 
$collection->add('blog_show', new Route('/blog/{show}', array(
    '_controller' => 'AppBundle:Blog:show',
)));
 
return $collection;

你能发现问题吗？两个路由都匹配类似/blog/*的URL。Symfony路由总是选择它第一个匹配的（blog）路由。换句话说，该blog_show路由永远被匹配。相反，像一个/blog/my-blog-post的URL会匹配第一个（blog）路由，并返回一个my-blog-post的值给{page}参数。

URL	Route	Parameters
`/blog/2`	`blog_list`	`$page` = `2`
`/blog/my-blog-post`	`blog_show`	`$slug` = `my-blog-post`

---给{通配符}一个默认值---

---高级的路由样例---1

在Symfony中你可以通过创建一个强大的路由结构来实现你所需的一切。下面是一个示例来展示路由系统是如何的灵活：

// src/AppBundle/Controller/ArticleController.php
 
// ...
class ArticleController extends Controller
{
    /**
     * @Route(
     *     "/articles/{_locale}/{year}/{title}.{_format}",
     *     defaults={"_format": "html"},
     *     requirements={
     *         "_locale": "en|fr",
     *         "_format": "html|rss",
     *         "year": "\d+"
     *     }
     * )
     */
    public function showAction($_locale, $year, $title)
    {
    }
}

# app/config/routing.yml
article_show:
  path:     /articles/{_locale}/{year}/{title}.{_format}
  defaults: { _controller: AppBundle:Article:show, _format: html }
  requirements:
      _locale:  en|fr
      _format:  html|rss
      year:     \d+

<!-- 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">
 
    <route id="article_show"
        path="/articles/{_locale}/{year}/{title}.{_format}">
 
        <default key="_controller">AppBundle:Article:show</default>
        <default key="_format">html</default>
        <requirement key="_locale">en|fr</requirement>
        <requirement key="_format">html|rss</requirement>
        <requirement key="year">\d+</requirement>
 
    </route>
</routes>

// app/config/routing.php
use Symfony\Component\Routing\RouteCollection;
use Symfony\Component\Routing\Route;
 
$collection = new RouteCollection();
$collection->add(
    'article_show',
    new Route('/articles/{_locale}/{year}/{title}.{_format}', array(
        '_controller' => 'AppBundle:Article:show',
        '_format'     => 'html',
    ), array(
        '_locale' => 'en|fr',
        '_format' => 'html|rss',
        'year'    => '\d+',
    ))
);
 
return $collection;

正如你所看到的，美观路由只匹配一部分URL也就是满足{_locale}为（en或者fr）和 {year}是数字的。该路由还向你展示了你可以使用一个句号来分割两个占位符。上面路由匹配的URL如下：

/articles/en/2010/my-post
/articles/fr/2010/my-post.rss
/articles/en/2013/my-latest-post.html

特殊的_format路由参数

这个示例也突显了特殊的_format路由参数。当使用这个参数时，匹配值将成为Request对象的“request format”（请求格式）。

最终，请求格式被用在“设置响应的Content-Type”这种地方（如一个json请求格式将转换成application/json的Content-Type）。它也可以在控制器中使用，根据不同的_format值去渲染不同的模板。_format参数是一种非常强大的方式，把相同的内容以不同格式来渲染（译注：即输出）。

在symfony3.0之前的版本中，可以覆写request（对象）中的格式参数（_format），通过添加名为“_format”的query参数即可（例：/foo/bar?_format=json）。滥用这种行为被认为是很不好的实践，而且还会令你的程序在升级到symfony3时“特别复杂”。

Note

有时，你想要令路由中的某些部分成为“全局配置”。symfony可以利用服务容器参数来做到这一点。参考如何在路由中使用服务容器的参数以了解更多。

---特殊的路由参数---2

正如你所看到的，每个路由参数或默认值都可以作为控制器方法的参数。此外，有三个参数是特殊的：在你的应用程序中每个都是给你的应用增加一个独特的功能：

_controller: 正如你所看到的，这个参数是用来决定“当路由匹配时”要执行哪个控制器的。
_format: 用于设置请求格式（request format。了解详情)。
_locale: 用于设置请求的locale (了解详情).

---控制器命名模式---

如果你使用YAML，XML或PHP的路由配置，那么每个路由都必须有一个_controller参数，用于指示当路匹配时应执行哪个控制器。这个参数使用一个简单的字符串pattern，叫做控制器逻辑名（logical controller name），Symfony用它来映射一个特定的PHP方法或类。此pattern有三个部分，用冒号隔开：

bundle:controller:action

假设，一个_controller值是一个AppBundle:Blog:show那么意味着：

Bundle	Controller Class	Method Name
`AppBundle`	`BlogController`	`showAction`

该控制器可能是这样的：

// src/AppBundle/Controller/BlogController.php
namespace AppBundle\Controller;
 
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
 
class BlogController extends Controller
{
    public function showAction($slug)
    {
        // ...
    }
}

注意，Symfony在Blog上添加了字符串Controller作为类名（Blog=>BlogController），添加字符串Action作为方法名（show=>showAction）。

你也可以使用它的FQCN类名及方法来指定这个类：AppBundle\Controller\BlogController::showAction。但如果你遵循一些简单的命名约定，逻辑名将更加简洁也更加灵活。

Note

除了使用逻辑名和FQCN类名之外，Symfony也支持第三种指定控制器的方式。这种方式只使用一个冒号分隔（如service_name:indexAction），并将控制器作为一个服务来引用（参见如何把控制器定义为服务）。

---路由参数和控制器参数---

路由参数（如{slug}是非常重要的，因为它（们）都被用作控制器方法的参数：

public function showAction($slug)
{
  // ...
}

现实中，defaults集将参数值一起合并成一个表单数组。该数组中的每个键都被做为控制器的参数。

换句话说，对于控制器方法的每个参数，Symfony2都会根据该名称来查找路由参数，并将其值指向到控制器作为参数。在上面的高级示例当中，下列变量的任何组合（以任意方式）都被用作showAction()方法的参数：

$_locale
$year
$title
$_format
$_controller
$_route

占位符和defaults集被合并在一起，就就算是$_controller变量也是可用的。更多细节的讨论，请参见作为控制器–把路由参数传入控制器。

Tip

你也可以使用指定的$_route变量，它的值是被匹配的路由名。

你甚至可以在你的路由中定义额外的信息并在你的控制器中访问它。关于更多信息请阅读如何从路由向控制器传递额外的信息

---生成URL---

路由系统也用于生成URL。在现实中，路由是一个双向系统：映射URL到控制器+参数以及映射路由+参数返回URL。match()和generate()方法构成了这个双向系统。使用之前的blog_show的例子：

$params = $this->get('router')->match('/blog/my-blog-post');
// array(
//     'slug'        => 'my-blog-post',
//     '_controller' => 'AppBundle:Blog:show',
// )
 
$uri = $this->get('router')->generate('blog_show', array(
    'slug' => 'my-blog-post'
));
// /blog/my-blog-post

要生成一个URL，你需要指定路由的名称（如blog_show）以及任意的通配符（如slug = my-blog-post）。有个这些信息，任何URL就可以很容易的生成了：

class MainController extends Controller
{
    public function showAction($slug)
    {
        // ...
 
        $url = $this->generateUrl(
            'blog_show',
            array('slug' => 'my-blog-post')
        );
    }
}

在控制器中你没有继承symfony的父类Controller，那么你不可以使用generateUrl()快捷方法，但你可以使用router的generate()服务方法：

$url = $this->container->get('router')->generate(
    'blog_show',
    array('slug' => 'my-blog-post')
);

在即将到来的部分中，你将学会如何在模板中生成URL地址。

如果你的应用程序前端使用的是ajax请求，你可能希望根据你的路由配置，在JavaScript中生成URL。通过使用FOSJsRoutingBundle，你就可以做到：

var url = Routing.generate(
    'blog_show',
    {"slug": 'my-blog-post'}
);

更多信息请阅读这个bundle文档。

---生成带有Query Strings的URL---1

这个generate方法采用通配符数组来生成URL。但是如果在其中添加了额外的键值对，他们将会被添加成Query Strings来生成一个新的URL：

$this->get('router')->generate('blog', array(
    'page' => 2,
    'category' => 'Symfony'
));
// /blog/2?category=Symfony

---在模板里生成URL---2

在应用程序页面之间进行连接时，最常见的地方就是从模板中生成URL。这样做其实和以前一样，但是使用的是一个模板助手函数：

Twig
PHP

1
2
3

<a href="{{ path('blog_show', {'slug': 'my-blog-post'}) }}">
  Read this blog post.
</a>

<a href="<?php echo $view['router']->path('blog_show', array(
    'slug' => 'my-blog-post',
)) ?>">
    Read this blog post.
</a>

---生成绝对的URL---3

默认情况下，路由器会产生相对的URL（如/blog）。在控制器中，很简单的把generateUrl()方法的第三参数设置成UrlGeneratorInterface::ABSOLUTE_URL即可。

use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
 
$this->generateUrl('blog_show', array('slug' => 'my-blog-post'), UrlGeneratorInterface::ABSOLUTE_URL);
// http://www.example.com/blog/my-blog-post

在模板引擎Twig中，要使用url()函数（生成一个绝对的URL），而不是path()函数（生成一个相对的URL）。在php中，需要要在generateUrl()中传入UrlGeneratorInterface::ABSOLUTE_URL:

Twig
PHP

1
2
3

<a href="{{ url('blog_show', {'slug': 'my-blog-post'}) }}">
  Read this blog post.
</a>

<a href="<?php echo $view['router']->url('blog_show', array(
    'slug' => 'my-blog-post',
)) ?>">
    Read this blog post.
</a>

Note

当生成一个绝对URL链接时，所使用的主机自动检测当前使用的Request对象。当生成从web环境外的绝对URL（例如一个控制台命令）这是行不通的。请参见如何从控制台生成URL 来学习如何解决这个问题。

---总结---

路由是一个将传入的请求之URL映射到用来处理该请求的控制器函数的系统。它允许你指定一个美观的URL，并使应用程序的功能与URL“脱钩”。路由是一个双向的机制，意味着它也可以用来生成URL。

---Keep Going!---

路由，核对完毕！现在，去解封控制器的力量。

了解更多¶

本文，包括例程代码在内，采用的是 Creative Commons BY-SA 3.0 创作共用授权。

登录symfonychina 发表评论或留下问题（我们会尽量回复）

起步

指南

组件

培训

官方技能认证

路由

---路由样例---

---路由：深入了解---

---创建路由---

---基本的路由配置---1

---带参数的路由---2

---添加{通配符}的条件---

---给{通配符}一个默认值---

---高级的路由样例---1

特殊的_format路由参数

---特殊的路由参数---2

---控制器命名模式---

---路由参数和控制器参数---

---生成URL---

---生成带有Query Strings的URL---1

---在模板里生成URL---2

---生成绝对的URL---3

---总结---

---Keep Going!---

了解更多¶

Symfony 4.2：cookie安全的自动化 2019-01-22

Symfony 4.2：改进的表单类型扩展（翻译中） 2019-01-22

Symfony 4.2：IntlMessageFormatter 2019-01-22

Symfony3技能认证，现已在全球4000余家考点展开！包括国际考试代理机构的中国考点...

社区

官方博客