Routing

When your application receives a request, it calls a controller action to generate the response. The routing configuration defines which action to run for each incoming URL. It also provides other useful features, like generating SEO-friendly URLs (e.g. /read/intro-to-symfony instead of index.php?article_id=57).

アプリケーションがリクエストを受け取ると、コントローラ アクションを呼び出してレスポンスを生成します。ルーティング構成は、着信 URL ごとに実行するアクションを定義します。また、SEO に適した URL の生成など、他の便利な機能も提供します (index.php?article_id=57 の代わりに /read/intro-to-symfony など)。

Creating Routes

Routes can be configured in YAML, XML, PHP or using attributes. All formats provide the same features and performance, so choose your favorite. Symfony recommends attributes because it's convenient to put the route and controller in the same place.

ルートは、YAML、XML、PHP、または属性を使用して構成できます。すべての形式で同じ機能とパフォーマンスが提供されるため、お好みで選択してください。ルートとコントローラーを同じ場所に配置すると便利なため、Symfony は属性を推奨します。

Creating Routes as Attributes

PHP attributes allow to define routes next to the code of the controllers associated to those routes. Attributes are native in PHP 8 and higher versions, so you can use them right away.

PHP 属性を使用すると、ルートに関連付けられたコントローラのコードの横にルートを定義できます。属性は PHP 8 以降のバージョンではネイティブであるため、すぐに使用できます。

You need to add a bit of configuration to your project before using them. If your project uses Symfony Flex, this file is already created for you. Otherwise, create the following file manually:

それらを使用する前に、プロジェクトに少し構成を追加する必要があります。プロジェクトで Symfony Flex を使用している場合、このファイルは既に作成されています。それ以外の場合は、次のファイルを手動で作成します。
1
2
3
4
5
6
7
8
9
10
 
# config/routes/attributes.yaml
controllers:
    resource:
        path: ../../src/Controller/
        namespace: App\Controller
    type: attribute

kernel:
    resource: App\Kernel
    type: attribute

This configuration tells Symfony to look for routes defined as attributes on classes declared in the App\Controller namespace and stored in the src/Controller/ directory which follows the PSR-4 standard. The kernel can act as a controller too, which is especially useful for small applications that use Symfony as a microframework.

この構成は Symfony に、App\Controller 名前空間で宣言され、PSR-4 標準に従う src/Controller/ ディレクトリに格納されているクラスの属性として定義されたルートを探すように指示します。カーネルはコントローラーとしても機能します。これは、Symfony をマイクロフレームワークとして使用する小さなアプリケーションに特に役立ちます。

6.2

6.2

The feature to import routes from a PSR-4 namespace root was introduced in Symfony 6.2.

PSR-4 名前空間ルートからルートをインポートする機能は、Symfony 6.2 で導入されました。

Suppose you want to define a route for the /blog URL in your application. To do so, create a controller class like the following:

アプリケーションで /blog URL のルートを定義するとします。そうするには、次のようなコントローラー クラスを作成します。
  • Attributes
    属性
1
2
3
4
5
6
7
8
9
10
11
12
13
14
 
// src/Controller/BlogController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    #[Route('/blog', name: 'blog_list')]
    public function list(): Response
    {
        // ...
    }
}

This configuration defines a route called blog_list that matches when the user requests the /blog URL. When the match occurs, the application runs the list() method of the BlogController class.

この構成は、ユーザーが /blog URL を要求したときに一致する blog_list という名前のルートを定義します。一致すると、アプリケーションは BlogController クラスの list() メソッドを実行します。

Note

ノート

The query string of a URL is not considered when matching routes. In this example, URLs like /blog?foo=bar and /blog?foo=bar&bar=foo will also match the blog_list route.

Caution

注意

If you define multiple PHP classes in the same file, Symfony only loads the routes of the first class, ignoring all the other routes.

同じファイルで複数の PHP クラスを定義すると、Symfony は最初のクラスのルートのみをロードし、他のすべてのルートを無視します。

The route name (blog_list) is not important for now, but it will be essential later when generating URLs. You only have to keep in mind that each route name must be unique in the application.

ルート名 (blog_list) は今のところ重要ではありませんが、後で URL を生成するときに重要になります。各ルート名はアプリケーション内で一意でなければならないことに注意してください。

Creating Routes in YAML, XML or PHP Files

Instead of defining routes in the controller classes, you can define them in a separate YAML, XML or PHP file. The main advantage is that they don't require any extra dependency. The main drawback is that you have to work with multiple files when checking the routing of some controller action.

コントローラー クラスでルートを定義する代わりに、別の YAML、XML、または PHP ファイルでルートを定義できます。主な利点は、追加の依存関係を必要としないことです。主な欠点は、コントローラ アクションのルーティングをチェックするときに、複数のファイルを操作しなければならないことです。

The following example shows how to define in YAML/XML/PHP a route called blog_list that associates the /blog URL with the list() action of the BlogController:

次の例は、/blog URL を BlogController の list() アクションに関連付ける blog_list という名前のルートを YAML/XML/PHP で定義する方法を示しています。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
 
# config/routes.yaml
blog_list:
    path: /blog
    # the controller value has the format 'controller_class::method_name'
    controller: App\Controller\BlogController::list

    # if the action is implemented as the __invoke() method of the
    # controller class, you can skip the '::method_name' part:
    # controller: App\Controller\BlogController

Note

ノート

By default Symfony only loads the routes defined in YAML format. If you define routes in XML and/or PHP formats, you need to update the src/Kernel.php file.

デフォルトでは、Symfony は YAML 形式で定義されたルートのみをロードします。 XML や PHP 形式でルートを定義する場合は、src/Kernel.php ファイルを更新する必要があります。

Matching HTTP Methods

By default, routes match any HTTP verb (GET, POST, PUT, etc.) Use the methods option to restrict the verbs each route should respond to:

デフォルトでは、ルートは任意の HTTP 動詞 (GET、POST、PUT など) に一致します。methods オプションを使用して、各ルートが応答する動詞を制限します。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
// src/Controller/BlogApiController.php
namespace App\Controller;

// ...

class BlogApiController extends AbstractController
{
    #[Route('/api/posts/{id}', methods: ['GET', 'HEAD'])]
    public function show(int $id): Response
    {
        // ... return a JSON response with the post
    }

    #[Route('/api/posts/{id}', methods: ['PUT'])]
    public function edit(int $id): Response
    {
        // ... edit a post
    }
}

Tip

ヒント

HTML forms only support GET and POST methods. If you're calling a route with a different method from an HTML form, add a hidden field called _method with the method to use (e.g. <input type="hidden" name="_method" value="PUT">). If you create your forms with Symfony Forms this is done automatically for you when the framework.http_method_override option is true.

HTML フォームは、GET メソッドと POST メソッドのみをサポートします。 HTML フォームとは別のメソッドで aroute を呼び出す場合は、使用するメソッド (例: ) を含む隠しフィールド called_method を追加します。

Matching Expressions

Use the condition option if you need some route to match based on some arbitrary matching logic:

任意の一致ロジックに基づいて一致するルートが必要な場合は、条件オプションを使用します。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
// src/Controller/DefaultController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class DefaultController extends AbstractController
{
    #[Route(
        '/contact',
        name: 'contact',
        condition: "context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'",
        // expressions can also include config parameters:
        // condition: "request.headers.get('User-Agent') matches '%app.allowed_browsers%'"
    )]
    public function contact(): Response
    {
        // ...
    }

    #[Route(
        '/posts/{id}',
        name: 'post_show',
        // expressions can retrieve route parameter values using the "params" variable
        condition: "params['id'] < 1000"
    )]
    public function showPost(int $id): Response
    {
        // ... return a JSON response with the post
    }
}

The value of the condition option is any valid ExpressionLanguage expression and can use any of these variables created by Symfony:

condition オプションの値は任意の有効な ExpressionLanguage 式であり、Symfony によって作成されたこれらの変数のいずれかを使用できます。
context
An instance of RequestContext, which holds the most fundamental information about the route being matched.
一致するルートに関する最も基本的な情報を保持する RequestContext のインスタンス。
request
The Symfony Request object that represents the current request.
現在のリクエストを表す Symfony Request オブジェクト。
params
An array of matched route parameters for the current route.
現在のルートに一致するルート パラメーターの配列。

6.1

6.1

The params variable was introduced in Symfony 6.1.

params 変数は Symfony 6.1 で導入されました。

You can also use these functions:

次の機能も使用できます。
env(string $name)
Returns the value of a variable using Environment Variable Processors
環境変数プロセッサを使用して変数の値を返します
service(string $alias)

Returns a routing condition service.

ルーティング条件サービスを返します。

First, add the #[AsRoutingConditionService] attribute or routing.condition_service tag to the services that you want to use in route conditions:

まず、ルート条件で使用するサービスに #[AsRoutingConditionService] 属性または routing.condition_servicetag を追加します。
1
2
3
4
5
6
7
8
9
10
11
 
use Symfony\Bundle\FrameworkBundle\Routing\Attribute\AsRoutingConditionService;
use Symfony\Component\HttpFoundation\Request;

#[AsRoutingConditionService(alias: 'route_checker')]
class RouteChecker
{
    public function check(Request $request): bool
    {
        // ...
    }
}

Then, use the service() function to refer to that service inside conditions:

次に、service() 関数を使用して、条件内のそのサービスを参照します。
1
2
3
4
 
// Controller (using an alias):
#[Route(condition: "service('route_checker').check(request)")]
// Or without alias:
#[Route(condition: "service('Ap\\\Service\\\RouteChecker').check(request)")]

6.1

6.1

The service(string $alias) function and #[AsRoutingConditionService] attribute were introduced in Symfony 6.1.

service(string $alias) 関数と #[AsRoutingConditionService] 属性は Symfony 6.1 で導入されました。

Behind the scenes, expressions are compiled down to raw PHP. Because of this, using the condition key causes no extra overhead beyond the time it takes for the underlying PHP to execute.

バックグラウンドで、式は生の PHP にコンパイルされます。このため、条件キーを使用しても、基礎となる PHP の実行にかかる時間以外に余分なオーバーヘッドは発生しません。

Caution

注意

Conditions are not taken into account when generating URLs (which is explained later in this article).

URL の生成時に条件は考慮されません (これについては、この記事で後述します)。

Debugging Routes

As your application grows, you'll eventually have a lot of routes. Symfony includes some commands to help you debug routing issues. First, the debug:router command lists all your application routes in the same order in which Symfony evaluates them:

アプリケーションが成長するにつれて、最終的には多くのルートを持つことになります。 symfony には、ルーティングの問題をデバッグするのに役立ついくつかのコマンドが含まれています。最初に、debug:router コマンドは、Symfony がそれらを評価するのと同じ順序ですべてのアプリケーション ルートを一覧表示します。
1
2
3
4
5
6
7
8
9
10
11
12
 
$ php bin/console debug:router

----------------  -------  -------  -----  --------------------------------------------
Name              Method   Scheme   Host   Path
----------------  -------  -------  -----  --------------------------------------------
homepage          ANY      ANY      ANY    /
contact           GET      ANY      ANY    /contact
contact_process   POST     ANY      ANY    /contact
article_show      ANY      ANY      ANY    /articles/{_locale}/{year}/{title}.{_format}
blog              ANY      ANY      ANY    /blog/{page}
blog_show         ANY      ANY      ANY    /blog/{slug}
----------------  -------  -------  -----  --------------------------------------------

Pass the name (or part of the name) of some route to this argument to print the route details:

ルートの詳細を表示するには、ルートの名前 (または名前の一部) をこの引数に渡します。
1
2
3
4
5
6
7
8
9
10
11
 
$ php bin/console debug:router app_lucky_number

+-------------+---------------------------------------------------------+
| Property    | Value                                                   |
+-------------+---------------------------------------------------------+
| Route Name  | app_lucky_number                                        |
| Path        | /lucky/number/{max}                                     |
| ...         | ...                                                     |
| Options     | compiler_class: Symfony\Component\Routing\RouteCompiler |
|             | utf8: true                                              |
+-------------+---------------------------------------------------------+

The other command is called router:match and it shows which route will match the given URL. It's useful to find out why some URL is not executing the controller action that you expect:

もう 1 つのコマンドは router:match と呼ばれ、指定された URL に一致するルートを示します。一部の URL が予期したコントローラー アクションを実行していない理由を調べると便利です。
1
2
3
 
$ php bin/console router:match /lucky/number/8

  [OK] Route "app_lucky_number" matches

Route Parameters

The previous examples defined routes where the URL never changes (e.g. /blog). However, it's common to define routes where some parts are variable. For example, the URL to display some blog post will probably include the title or slug (e.g. /blog/my-first-post or /blog/all-about-symfony).

前の例では、URL が変更されないルート (例: /blog) を定義しました。ただし、一部の部分が可変であるルートを定義するのが一般的です。たとえば、ブログ投稿を表示する URL には、おそらくタイトルまたはスラッグが含まれます (例: /blog/my-first-post または /blog/all-about-symfony)。

In Symfony routes, variable parts are wrapped in { ... } and they must have a unique name. For example, the route to display the blog post contents is defined as /blog/{slug}:

Symfony ルートでは、変数部分は { ... } でラップされ、一意の名前が必要です。たとえば、ブログ投稿のコンテンツを表示するルートは /blog/{slug} として定義されます。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
 
// src/Controller/BlogController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    // ...

    #[Route('/blog/{slug}', name: 'blog_show')]
    public function show(string $slug): Response
    {
        // $slug will equal the dynamic part of the URL
        // e.g. at /blog/yay-routing, then $slug='yay-routing'

        // ...
    }
}

The name of the variable part ({slug} in this example) is used to create a PHP variable where that route content is stored and passed to the controller. If a user visits the /blog/my-first-post URL, Symfony executes the show() method in the BlogController class and passes a $slug = 'my-first-post' argument to the show() method.

変数部分の名前 (この例では {slug}) は、そのルート コンテンツが格納され、コントローラーに渡される PHP 変数を作成するために使用されます。ユーザーが /blog/my-first-post URL にアクセスすると、Symfony はBlogController クラスの show() メソッドを呼び出し、$slug = 'my-first-post' 引数を show() メソッドに渡します。

Routes can define any number of parameters, but each of them can only be used once on each route (e.g. /blog/posts-about-{category}/page/{pageNumber}).

ルートは任意の数のパラメーターを定義できますが、各パラメーターは各ルートで 1 回しか使用できません (例: /blog/posts-about-{category}/page/{pageNumber})。

Parameters Validation

Imagine that your application has a blog_show route (URL: /blog/{slug}) and a blog_list route (URL: /blog/{page}). Given that route parameters accept any value, there's no way to differentiate both routes.

アプリケーションに blog_show ルート (URL: /blog/{slug}) と blog_list ルート (URL: /blog/{page}) があるとします。ルート パラメーターが任意の値を受け入れる場合、両方のルートを区別する方法はありません。

If the user requests /blog/my-first-post, both routes will match and Symfony will use the route which was defined first. To fix this, add some validation to the {page} parameter using the requirements option:

ユーザーが /blog/my-first-post をリクエストすると、両方のルートが一致し、Symfony は最初に定義されたルートを使用します。これを修正するには、要件オプションを使用して {page} パラメータにいくつかの検証を追加します。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
// src/Controller/BlogController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    #[Route('/blog/{page}', name: 'blog_list', requirements: ['page' => '\d+'])]
    public function list(int $page): Response
    {
        // ...
    }

    #[Route('/blog/{slug}', name: 'blog_show')]
    public function show($slug): Response
    {
        // ...
    }
}

The requirements option defines the PHP regular expressions that route parameters must match for the entire route to match. In this example, \d+ is a regular expression that matches a digit of any length. Now:

requirements オプションは、ルート全体が一致するために routeparameters が一致しなければならない PHP 正規表現を定義します。この例では、\d+ は任意の長さの数字に一致する正規表現です。今：
URL Route Parameters
/blog/2 blog_list $page = 2
/blog/my-first-post blog_show $slug = my-first-post

Tip

ヒント

The Requirement enum contains a collection of commonly used regular-expression constants such as digits, dates and UUIDs which can be used as route parameter requirements.

要件列挙には、ルート パラメーター要件として使用できる、数字、日付、UUID などの一般的に使用される正規表現定数のコレクションが含まれています。

6.1

6.1

The Requirement enum was introduced in Symfony 6.1.

Requirement enum は Symfony 6.1 で導入されました。

Tip

ヒント

Route requirements (and route paths too) can include configuration parameters, which is useful to define complex regular expressions once and reuse them in multiple routes.

ルート要件 (およびルート パスも) には構成パラメーターを含めることができます。これは、複雑な正規表現を一度定義すると、それらを複数のルートで再利用するのに役立ちます。

Tip

ヒント

Parameters also support PCRE Unicode properties, which are escape sequences that match generic character types. For example, \p{Lu} matches any uppercase character in any language, \p{Greek} matches any Greek characters, etc.

パラメータは、汎用文字タイプに一致するエスケープシーケンスである PCRE Unicode プロパティもサポートします。たとえば、\p{Lu} は任意の言語の大文字に一致し、\p{Greek} は任意のギリシャ文字に一致します。

Note

ノート

When using regular expressions in route parameters, you can set the utf8 route option to true to make any . character match any UTF-8 characters instead of just a single byte.

ルート パラメーターで正規表現を使用する場合、utf8route オプションを true に設定して任意の .文字は、1 バイトだけでなく、任意の UTF-8 文字と一致します。

If you prefer, requirements can be inlined in each parameter using the syntax {parameter_name<requirements>}. This feature makes configuration more concise, but it can decrease route readability when requirements are complex:

必要に応じて、構文 {parameter_name} を使用して各パラメーターに要件をインライン化できます。この機能により構成がより簡潔になりますが、要件が複雑な場合はルートの可読性が低下する可能性があります。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
// src/Controller/BlogController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    #[Route('/blog/{page<\d+>}', name: 'blog_list')]
    public function list(int $page): Response
    {
        // ...
    }
}

Optional Parameters

In the previous example, the URL of blog_list is /blog/{page}. If users visit /blog/1, it will match. But if they visit /blog, it will not match. As soon as you add a parameter to a route, it must have a value.

前の例では、blog_list の URL は /blog/{page} です。ユーザーが /blog/1 にアクセスすると、一致します。しかし、彼らが /blog にアクセスすると、一致しません。パラメータをルートに追加するとすぐに、値が必要になります。

You can make blog_list once again match when the user visits /blog by adding a default value for the {page} parameter. When using annotations or attributes, default values are defined in the arguments of the controller action. In the other configuration formats they are defined with the defaults option:

{page} パラメータのデフォルト値を追加することで、ユーザーが /blog にアクセスしたときに再度 blog_list を一致させることができます。注釈または属性を使用する場合、デフォルト値はコントローラー アクションの引数で定義されます。他の構成形式では、デフォルト オプションで定義されます。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
// src/Controller/BlogController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    #[Route('/blog/{page}', name: 'blog_list', requirements: ['page' => '\d+'])]
    public function list(int $page = 1): Response
    {
        // ...
    }
}

Now, when the user visits /blog, the blog_list route will match and $page will default to a value of 1.

これで、ユーザーが /blog にアクセスすると、blog_list ルートが一致し、$page のデフォルト値は 1 になります。

Caution

注意

You can have more than one optional parameter (e.g. /blog/{slug}/{page}), but everything after an optional parameter must be optional. For example, /{page}/blog is a valid path, but page will always be required (i.e. /blog will not match this route).

複数のオプション パラメータ (例: /blog/{slug}/{page}) を指定できますが、オプション パラメータ以降はすべてオプションである必要があります。たとえば、/{page}/blog は有効なパスですが、ページは常に必要です (つまり、/blog はこのルートと一致しません)。

If you want to always include some default value in the generated URL (for example to force the generation of /blog/1 instead of /blog in the previous example) add the ! character before the parameter name: /blog/{!page}

生成される URL に常に何らかのデフォルト値を含めたい場合 (たとえば、前の例の /blog の代わりに /blog/1 の生成を強制する場合) は、!パラメータ名の前の文字: /blog/{!page}

As it happens with requirements, default values can also be inlined in each parameter using the syntax {parameter_name?default_value}. This feature is compatible with inlined requirements, so you can inline both in a single parameter:

要件で発生するように、構文 {parameter_name?default_value} を使用して、デフォルト値を各パラメーターにインライン化することもできます。この機能はインライン化された要件と互換性があるため、1 つのパラメーターで両方をインライン化できます。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
// src/Controller/BlogController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    #[Route('/blog/{page<\d+>?1}', name: 'blog_list')]
    public function list(int $page): Response
    {
        // ...
    }
}

Tip

ヒント

To give a null default value to any parameter, add nothing after the ? character (e.g. /blog/{page?}). If you do this, don't forget to update the types of the related controller arguments to allow passing null values (e.g. replace int $page by ?int $page).

パラメータに null のデフォルト値を指定するには、? の後に何も追加しません。文字 (例: /blog/{page?})。これを行う場合は、null 値を渡すことができるように、関連するコントローラー引数の型を更新することを忘れないでください (たとえば、int $page を ?int $page に置き換えます)。

Priority Parameter

Symfony evaluates routes in the order they are defined. If the path of a route matches many different patterns, it might prevent other routes from being matched. In YAML and XML you can move the route definitions up or down in the configuration file to control their priority. In routes defined as PHP annotations or attributes this is much harder to do, so you can set the optional priority parameter in those routes to control their priority:

symfony は、定義された順序でルートを評価します。ルートのパスが多くの異なるパターンに一致する場合、他のルートが一致するのを妨げる可能性があります。 YAML および XML では、構成ファイル内でルート定義を上下に移動して、それらの優先順位を制御できます。 PHP アノテーションまたは属性として定義されたルートでは、これを行うのは非常に難しいため、それらのルートでオプションの優先度パラメーターを設定して、優先度を制御できます。
  • Attributes
    属性
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
 
// src/Controller/BlogController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    /**
     * This route has a greedy pattern and is defined first.
     */
    #[Route('/blog/{slug}', name: 'blog_show')]
    public function show(string $slug): Response
    {
        // ...
    }

    /**
     * This route could not be matched without defining a higher priority than 0.
     */
    #[Route('/blog/list', name: 'blog_list', priority: 2)]
    public function list(): Response
    {
        // ...
    }
}

The priority parameter expects an integer value. Routes with higher priority are sorted before routes with lower priority. The default value when it is not defined is 0.

優先度パラメーターには整数値が必要です。優先度の高いルートは、優先度の低いルートの前にソートされます。定義されていない場合のデフォルト値は 0 です。

Parameter Conversion

A common routing need is to convert the value stored in some parameter (e.g. an integer acting as the user ID) into another value (e.g. the object that represents the user). This feature is called a "param converter".

一般的なルーティングの必要性は、いくつかのパラメーターに格納されている値 (ユーザー ID として機能する整数など) を別の値 (ユーザーを表すオブジェクトなど) に変換することです。この機能は「パラメータ コンバータ」と呼ばれます。

To add support for "param converters" we need SensioFrameworkExtraBundle:

「パラメータ コンバーター」のサポートを追加するには、SensioFrameworkExtraBundle が必要です。
1
 
$ composer require sensio/framework-extra-bundle

Now, keep the previous route configuration, but change the arguments of the controller action. Instead of string $slug, add BlogPost $post:

ここで、以前のルート構成を保持しますが、コントローラー アクションの引数を変更します。文字列 $slug の代わりに、BlogPost $post を追加します。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
 
// src/Controller/BlogController.php
namespace App\Controller;

use App\Entity\BlogPost;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    // ...

    #[Route('/blog/{slug}', name: 'blog_show')]
    public function show(BlogPost $post): Response
    {
        // $post is the object whose slug matches the routing parameter

        // ...
    }
}

If your controller arguments include type-hints for objects (BlogPost in this case), the "param converter" makes a database request to find the object using the request parameters (slug in this case). If no object is found, Symfony generates a 404 response automatically.

コントローラーの引数にオブジェクト (この場合は BlogPost) の型ヒントが含まれている場合、「パラメーター コンバーター」は、要求パラメーター (この場合は slug) を使用してオブジェクトを検索するデータベース要求を行います。オブジェクトが見つからない場合、Symfony は 404 レスポンスを自動的に生成します。

Read the full param converter documentation to learn about the converters provided by Symfony and how to configure them.

パラメータ コンバーターの完全なドキュメントを読んで、Symfony が提供するコンバーターとその構成方法について学んでください。

Special Parameters

In addition to your own parameters, routes can include any of the following special parameters created by Symfony:

独自のパラメーターに加えて、ルートには Symfony によって作成された次の特別なパラメーターのいずれかを含めることができます。
_controller
This parameter is used to determine which controller and action is executed when the route is matched.
このパラメーターは、ルートが一致したときに実行されるコントローラーとアクションを決定するために使用されます。
_format
The matched value is used to set the "request format" of the Request object. This is used for such things as setting the Content-Type of the response (e.g. a json format translates into a Content-Type of application/json).
一致した値は、Request オブジェクトの「要求形式」を設定するために使用されます。これは、応答の Content-Type の設定などに使用されます (たとえば、json 形式は application/json の Content-Type に変換されます)。
_fragment
Used to set the fragment identifier, which is the optional last part of a URL that starts with a # character and is used to identify a portion of a document.
フラグメント識別子を設定するために使用されます。これは、# 文字で始まる URL のオプションの最後の部分であり、ドキュメントの一部を識別するために使用されます。
_locale
Used to set the locale on the request.
リクエストにロケールを設定するために使用されます。

You can include these attributes (except _fragment) both in individual routes and in route imports. Symfony defines some special attributes with the same name (except for the leading underscore) so you can define them easier:

これらの属性 (_fragment を除く) は、個々のルートとルート インポートの両方に含めることができます。 symfony は、同じ名前 (先頭のアンダースコアを除く) を持ついくつかの特別な属性を定義しているため、それらをより簡単に定義できます。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
// src/Controller/ArticleController.php
namespace App\Controller;

// ...
class ArticleController extends AbstractController
{
    #[Route(
        path: '/articles/{_locale}/search.{_format}',
        locale: 'en',
        format: 'html',
        requirements: [
            '_locale' => 'en|fr',
            '_format' => 'html|xml',
        ],
    )]
    public function search(): Response
    {
    }
}

Extra Parameters

In the defaults option of a route you can optionally define parameters not included in the route configuration. This is useful to pass extra arguments to the controllers of the routes:

ルートのデフォルト オプションでは、ルート設定に含まれていないパラメータをオプションで定義できます。これは、追加の引数をルートのコントローラーに渡すのに役立ちます。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
// src/Controller/BlogController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    #[Route('/blog/{page}', name: 'blog_index', defaults: ['page' => 1, 'title' => 'Hello world!'])]
    public function index(int $page, string $title): Response
    {
        // ...
    }
}

Slash Characters in Route Parameters

Route parameters can contain any values except the / slash character, because that's the character used to separate the different parts of the URLs. For example, if the token value in the /share/{token} route contains a / character, this route won't match.

/ スラッシュ文字は URL のさまざまな部分を区切るために使用される文字であるため、ルート パラメーターには任意の値を含めることができます。たとえば、/share/{token} ルートのトークン値に / 文字が含まれている場合、このルートが優先されます。一致しません。

A possible solution is to change the parameter requirements to be more permissive:

考えられる解決策は、パラメーター要件をより寛容になるように変更することです。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
// src/Controller/DefaultController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class DefaultController extends AbstractController
{
    #[Route('/share/{token}', name: 'share', requirements: ['token' => '.+'])]
    public function share($token): Response
    {
        // ...
    }
}

Note

ノート

If the route defines several parameters and you apply this permissive regular expression to all of them, you might get unexpected results. For example, if the route definition is /share/{path}/{token} and both path and token accept /, then token will only get the last part and the rest is matched by path.

ルートでいくつかのパラメーターが定義されていて、この寛容な正規表現をそれらすべてに適用すると、予期しない結果が生じる可能性があります。たとえば、ルート定義が /share/{path}/{token} で、パスとトークンの両方が / を受け入れる場合、トークンは最後の部分のみを取得し、残りはパスによって照合されます。

Note

ノート

If the route includes the special {_format} parameter, you shouldn't use the .+ requirement for the parameters that allow slashes. For example, if the pattern is /share/{token}.{_format} and {token} allows any character, the /share/foo/bar.json URL will consider foo/bar.json as the token and the format will be empty. This can be solved by replacing the .+ requirement by [^.]+ to allow any character except dots.

ルートに特殊な {_format} パラメータが含まれている場合、スラッシュを許可するパラメータに .+ 要件を使用しないでください。たとえば、パターンが /share/{token}.{_format} で {token} が任意の文字を許可する場合、/share/foo/bar.json URL は foo/bar.json をトークンと見なし、形式は空になります。これは、.+ 要件を [^.]+ に置き換えて、ドット以外の任意の文字を許可することで解決できます。

Route Aliasing

Route alias allow you to have multiple name for the same route:

ルート エイリアスを使用すると、同じルートに複数の名前を付けることができます。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
 
# config/routes.yaml
new_route_name:
    alias: original_route_name

In this example, both original_route_name and new_route_name routes can be used in the application and will produce the same result.

この例では、original_route_name ルートと new_route_name ルートの両方をアプリケーションで使用でき、同じ結果が得られます。

Deprecating Route Aliases

If some route alias should no longer be used (because it is outdated or you decided not to maintain it anymore), you can deprecate its definition:

一部のルート エイリアスが使用されなくなった場合 (それが古くなった、またはもう維持しないことにしたため)、その定義を非推奨にすることができます。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
 
new_route_name:
    alias: original_route_name

    # this outputs the following generic deprecation message:
    # Since acme/package 1.2: The "new_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
    deprecated:
        package: 'acme/package'
        version: '1.2'

    # you can also define a custom deprecation message (%alias_id% placeholder is available)
    deprecated:
        package: 'acme/package'
        version: '1.2'
        message: 'The "%alias_id%" route alias is deprecated. Do not use it anymore.'

In this example, every time the new_route_name alias is used, a deprecation warning is triggered, advising you to stop using that alias.

この例では、new_route_name エイリアスが使用されるたびに非推奨警告がトリガーされ、そのエイリアスの使用を停止するようにアドバイスされます。

The message is actually a message template, which replaces occurrences of the %alias_id% placeholder by the route alias name. You must have at least one occurrence of the %alias_id% placeholder in your template.

メッセージは実際にはメッセージ テンプレートであり、%alias_id% プレースホルダーの出現箇所をルート エイリアス名に置き換えます。テンプレートには、%alias_id% プレースホルダーが少なくとも 1 回出現する必要があります。

Route Groups and Prefixes

It's common for a group of routes to share some options (e.g. all routes related to the blog start with /blog) That's why Symfony includes a feature to share route configuration.

ルートのグループがいくつかのオプションを共有するのはよくあることです (例えば、ブログに関連するすべてのルートは /blog で始まります)。そのため、Symfony にはルート構成を共有する機能が含まれています。

When defining routes as attributes, put the common configuration in the #[Route] attribute of the controller class. In other routing formats, define the common configuration using options when importing the routes.

ルートを属性として定義する場合は、コントローラ クラスの #[Route] 属性に共通の構成を配置します。その他のルーティング形式では、ルートのインポート時にオプションを使用して共通の構成を定義します。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
 
// src/Controller/BlogController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

#[Route('/blog', requirements: ['_locale' => 'en|es|fr'], name: 'blog_')]
class BlogController extends AbstractController
{
    #[Route('/{_locale}', name: 'index')]
    public function index(): Response
    {
        // ...
    }

    #[Route('/{_locale}/posts/{slug}', name: 'show')]
    public function show(string $slug): Response
    {
        // ...
    }
}

In this example, the route of the index() action will be called blog_index and its URL will be /blog/{_locale}. The route of the show() action will be called blog_show and its URL will be /blog/{_locale}/posts/{slug}. Both routes will also validate that the _locale parameter matches the regular expression defined in the class annotation.

この例では、index() アクションのルートは blog_index と呼ばれ、その URL は /blog/{_locale} になります。 show() アクションのルートは blog_show と呼ばれ、その URL は /blog/{_locale}/posts/{slug} になります。どちらのルートも、_locale パラメータがクラス アノテーションで定義された正規表現と一致することを検証します。

Note

ノート

If any of the prefixed routes defines an empty path, Symfony adds a trailing slash to it. In the previous example, an empty path prefixed with /blog will result in the /blog/ URL. If you want to avoid this behavior, set the trailing_slash_on_root option to false (this option is not available when using PHP attributes or annotations):

プレフィックス付きのルートのいずれかが空のパスを定義している場合、Symfony はそれに末尾のスラッシュを追加します。前の例では、/blog で始まる空のパスは /blog/ URL になります。この動作を回避したい場合は、trailing_slash_on_root オプションを false に設定します (このオプションは、PHP 属性または注釈を使用している場合は使用できません)。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
 
# config/routes/annotations.yaml
controllers:
    resource: '../../src/Controller/'
    type:     annotation
    prefix:   '/blog'
    trailing_slash_on_root: false
    # ...

See also

こちらもご覧ください

Symfony can import routes from different sources and you can even create your own route loader.

symfony はさまざまなソースからルートをインポートでき、独自のルート ローダーを作成することもできます。

Getting the Route Name and Parameters

The Request object created by Symfony stores all the route configuration (such as the name and parameters) in the "request attributes". You can get this information in a controller via the Request object:

Symfony によって作成された Request オブジェクトは、すべてのルート構成 (名前やパラメーターなど) を「リクエスト属性」に格納します。 Request オブジェクトを介してコントローラでこの情報を取得できます。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
 
// src/Controller/BlogController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    #[Route('/blog', name: 'blog_list')]
    public function list(Request $request): Response
    {
        $routeName = $request->attributes->get('_route');
        $routeParameters = $request->attributes->get('_route_params');

        // use this to get all the available attributes (not only routing ones):
        $allAttributes = $request->attributes->all();

        // ...
    }
}

You can get this information in services too injecting the request_stack service to get the Request object in a service. In templates, use the Twig global app variable to get the current route and its attributes:

この情報は、request_stackservice を注入してサービス内の Request オブジェクトを取得するサービスでも取得できます。テンプレートでは、Twig グローバル アプリ変数を使用して、現在のルートとその属性を取得します。
1
2
 
{% set route_name = app.current_route %}
{% set route_parameters = app.current_route_parameters %}

6.2

6.2

The app.current_route and app.current_route_parameters variables were introduced in Symfony 6.2. Before you had to access _route and _route_params request attributes using app.request.attributes.get().

app.current_route および app.current_route_parameters 変数は Symfony 6.2 で導入されました。それ以前は、app.request.attributes.get() を使用して _route および _route_params 要求属性にアクセスする必要がありました。

Special Routes

Symfony defines some special controllers to render templates and redirect to other routes from the route configuration so you don't have to create a controller action.

symfony は、テンプレートをレンダリングし、ルート構成から他のルートにリダイレクトする特別なコントローラーをいくつか定義しているため、コントローラー アクションを作成する必要はありません。

Rendering a Template Directly from a Route

Read the section about rendering a template from a route in the main article about Symfony templates.

Symfony テンプレートに関するメインの記事で、ルートからのテンプレートのレンダリングに関するセクションを読んでください。

Redirecting to URLs and Routes Directly from a Route

Use the RedirectController to redirect to other routes and URLs:

RedirectController を使用して、他のルートと URL にリダイレクトします。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
# config/routes.yaml
doc_shortcut:
    path: /doc
    controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController
    defaults:
        route: 'doc_page'
        # optionally you can define some arguments passed to the route
        page: 'index'
        version: 'current'
        # redirections are temporary by default (code 302) but you can make them permanent (code 301)
        permanent: true
        # add this to keep the original query string parameters when redirecting
        keepQueryParams: true
        # add this to keep the HTTP method when redirecting. The redirect status changes
        # * for temporary redirects, it uses the 307 status code instead of 302
        # * for permanent redirects, it uses the 308 status code instead of 301
        keepRequestMethod: true
        # add this to remove the original route attributes when redirecting
        ignoreAttributes: true

legacy_doc:
    path: /legacy/doc
    controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController
    defaults:
        # this value can be an absolute path or an absolute URL
        path: 'https://legacy.example.com/doc'
        permanent: true

Tip

ヒント

Symfony also provides some utilities to redirect inside controllers

symfony は、コントローラ内でリダイレクトするためのユーティリティもいくつか提供しています

Redirecting URLs with Trailing Slashes

Historically, URLs have followed the UNIX convention of adding trailing slashes for directories (e.g. https://example.com/foo/) and removing them to refer to files (https://example.com/foo). Although serving different contents for both URLs is OK, nowadays it's common to treat both URLs as the same URL and redirect between them.

歴史的に、URL は、ディレクトリの末尾にスラッシュを追加し (https://example.com/foo/ など)、ファイルを参照するためにそれらを削除するという UNIX の規則に従っていました (https://example.com/foo)。両方の URL に異なるコンテンツを提供することは問題ありませんが、最近では、両方の URL を同じ URL として扱い、それらの間でリダイレクトするのが一般的です。

Symfony follows this logic to redirect between URLs with and without trailing slashes (but only for GET and HEAD requests):

symfony はこのロジックに従って、末尾のスラッシュの有無にかかわらず URL 間をリダイレクトします (ただし、GET および HEAD リクエストの場合のみ):
Route URL If the requested URL is /foo If the requested URL is /foo/
/foo It matches (200 status response) It makes a 301 redirect to /foo
/foo/ It makes a 301 redirect to /foo/ It matches (200 status response)

Sub-Domain Routing

Routes can configure a host option to require that the HTTP host of the incoming requests matches some specific value. In the following example, both routes match the same path (/) but one of them only responds to a specific host name:

ルートは、着信要求の HTTP ホストが特定の値と一致することを要求するホスト オプションを構成できます。次の例では、両方のルートが同じパス (/) に一致しますが、そのうちの 1 つは特定のホスト名にのみ応答します。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
// src/Controller/MainController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class MainController extends AbstractController
{
    #[Route('/', name: 'mobile_homepage', host: 'm.example.com')]
    public function mobileHomepage(): Response
    {
        // ...
    }

    #[Route('/', name: 'homepage')]
    public function homepage(): Response
    {
        // ...
    }
}

The value of the host option can include parameters (which is useful in multi-tenant applications) and these parameters can be validated too with requirements:

ホスト オプションの値にはパラメーターを含めることができ (これはマルチテナント アプリケーションで役立ちます)、これらのパラメーターも要件で検証できます。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
// src/Controller/MainController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class MainController extends AbstractController
{
    #[Route(
        '/',
        name: 'mobile_homepage',
        host: '{subdomain}.example.com',
        defaults: ['subdomain' => 'm'],
        requirements: ['subdomain' => 'm|mobile'],
    )]
    public function mobileHomepage(): Response
    {
        // ...
    }

    #[Route('/', name: 'homepage')]
    public function homepage(): Response
    {
        // ...
    }
}

In the above example, the subdomain parameter defines a default value because otherwise you need to include a subdomain value each time you generate a URL using these routes.

上記の例では、サブドメイン パラメータでデフォルト値を定義しています。そうしないと、これらのルートを使用して URL を生成するたびにサブドメイン値を含める必要があるからです。

Tip

ヒント

You can also set the host option when importing routes to make all of them require that host name.

ルートをインポートするときにホスト オプションを設定して、すべてのルートがそのホスト名を必要とするようにすることもできます。

Note

ノート

When using sub-domain routing, you must set the Host HTTP headers in functional tests or routes won't match:

サブドメイン ルーティングを使用する場合は、ホスト HTTP ヘッダーを機能しないテストに設定する必要があります。そうしないと、ルートが一致しません。
1
2
3
4
5
6
7
8
9
 
$crawler = $client->request(
    'GET',
    '/',
    [],
    [],
    ['HTTP_HOST' => 'm.example.com']
    // or get the value from some configuration parameter:
    // ['HTTP_HOST' => 'm.'.$client->getContainer()->getParameter('domain')]
);

Tip

ヒント

You can also use the inline defaults and requirements format in the host option: {subdomain<m|mobile>?m}.example.com

また、ホスト オプションでインラインのデフォルトと要件の形式を使用することもできます: {subdomain?m}.example.com

Localized Routes (i18n)

If your application is translated into multiple languages, each route can define a different URL per each translation locale. This avoids the need for duplicating routes, which also reduces the potential bugs:

アプリケーションが複数の言語に翻訳されている場合、各ルートは各翻訳ロケールごとに異なる URL を定義できます。これにより、ルートを複製する必要がなくなり、潜在的なバグも減少します。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
 
// src/Controller/CompanyController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class CompanyController extends AbstractController
{
    #[Route(path: [
        'en' => '/about-us',
        'nl' => '/over-ons'
    ], name: 'about_us')]
    public function about(): Response
    {
        // ...
    }
}

Note

ノート

When using PHP attributes for localized routes, you have to use the path named parameter to specify the array of paths.

ローカライズされたルートに PHP 属性を使用する場合、pathnamed パラメータを使用してパスの配列を指定する必要があります。

When a localized route is matched, Symfony uses the same locale automatically during the entire request.

ローカライズされたルートが一致すると、Symfony はリクエスト全体で同じロケールを自動的に使用します。

Tip

ヒント

When the application uses full "language + territory" locales (e.g. fr_FR, fr_BE), if the URLs are the same in all related locales, routes can use only the language part (e.g. fr) to avoid repeating the same URLs.

アプリケーションが完全な「言語 + 地域」ロケール (例: fr_FR、fr_BE) を使用する場合、関連するすべてのロケールで URL が同じ場合、ルートは言語部分 (例: fr) のみを使用して、同じ URL の繰り返しを避けることができます。

A common requirement for internationalized applications is to prefix all routes with a locale. This can be done by defining a different prefix for each locale (and setting an empty prefix for your default locale if you prefer it):

国際化されたアプリケーションの一般的な要件は、すべてのルートにロケールのプレフィックスを付けることです。これは、ロケールごとに異なるプレフィックスを定義することで実行できます (必要に応じて、既定のロケールに空のプレフィックスを設定します)。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
 
# config/routes/annotations.yaml
controllers:
    resource: '../../src/Controller/'
    type: annotation
    prefix:
        en: '' # don't prefix URLs for English, the default locale
        nl: '/nl'

Another common requirement is to host the website on a different domain according to the locale. This can be done by defining a different host for each locale.

もう 1 つの一般的な要件は、ロケールに応じて別のドメインで Web サイトをホストすることです。これは、ロケールごとに異なるホストを定義することで実行できます。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
 
# config/routes/annotations.yaml
controllers:
    resource: '../../src/Controller/'
    type: annotation
    host:
        en: 'https://www.example.com'
        nl: 'https://www.example.nl'

Stateless Routes

Sometimes, when an HTTP response should be cached, it is important to ensure that can happen. However, whenever a session is started during a request, Symfony turns the response into a private non-cacheable response.

場合によっては、HTTP 応答をキャッシュする必要がある場合、それが確実に行われるようにすることが重要です。ただし、リクエスト中にセッションが開始されるたびに、Symfony はレスポンスをプライベートでキャッシュ不可のレスポンスに変換します。

For details, see HTTP Cache.

詳細については、HTTP キャッシュを参照してください。

Routes can configure a stateless boolean option in order to declare that the session shouldn't be used when matching a request:

ルートは、リクエストに一致するときにセッションを使用しないことを宣言するために、ステートレスのブール値オプションを設定できます。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
 
// src/Controller/MainController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

class MainController extends AbstractController
{
    #[Route('/', name: 'homepage', stateless: true)]
    public function homepage(): Response
    {
        // ...
    }
}

Now, if the session is used, the application will report it based on your kernel.debug parameter:

ここで、セッションが使用されている場合、アプリケーションは yourkernel.debug パラメータに基づいてそれを報告します:
  • enabled: will throw an UnexpectedSessionUsageException exception
    有効: UnexpectedSessionUsageException 例外をスローします
  • disabled: will log a warning
    無効: 警告をログに記録します

It will help you understand and hopefully fixing unexpected behavior in your application.

アプリケーションの予期しない動作を理解し、できれば修正するのに役立ちます。

Generating URLs

Routing systems are bidirectional: 1) they associate URLs with controllers (as explained in the previous sections); 2) they generate URLs for a given route. Generating URLs from routes allows you to not write the <a href="..."> values manually in your HTML templates. Also, if the URL of some route changes, you only have to update the route configuration and all links will be updated.

ルーティング システムは双方向です。1) URL をコントローラーに関連付けます (前のセクションで説明したように)。 2) 特定のルートの URL を生成します。ルートから URL を生成すると、HTML テンプレートに手動で値を書き込まなくても済みます。また、一部のルートの URL が変更された場合、ルート構成を更新するだけで、すべてのリンクが更新されます。

To generate a URL, you need to specify the name of the route (e.g. blog_show) and the values of the parameters defined by the route (e.g. slug = my-blog-post).

URL を生成するには、ルートの名前 (例: blog_show) とルートによって定義されたパラメーターの値 (例: slug = my-blog-post) を指定する必要があります。

For that reason each route has an internal name that must be unique in the application. If you don't set the route name explicitly with the name option, Symfony generates an automatic name based on the controller and action.

そのため、各ルートには、アプリケーション内で一意でなければならない内部名があります。 name オプションでルート名を明示的に設定しない場合、Symfony はコントローラーとアクションに基づいて自動名前を生成します。

Generating URLs in Controllers

If your controller extends from the AbstractController, use the generateUrl() helper:

コントローラーが AbstractController から拡張されている場合は、generateUrl() ヘルパーを使用します。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
// src/Controller/BlogController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;

class BlogController extends AbstractController
{
    #[Route('/blog', name: 'blog_list')]
    public function list(): Response
    {
        // generate a URL with no route arguments
        $signUpPage = $this->generateUrl('sign_up');

        // generate a URL with route arguments
        $userProfilePage = $this->generateUrl('user_profile', [
            'username' => $user->getUserIdentifier(),
        ]);

        // generated URLs are "absolute paths" by default. Pass a third optional
        // argument to generate different URLs (e.g. an "absolute URL")
        $signUpPage = $this->generateUrl('sign_up', [], UrlGeneratorInterface::ABSOLUTE_URL);

        // when a route is localized, Symfony uses by default the current request locale
        // pass a different '_locale' value if you want to set the locale explicitly
        $signUpPageInDutch = $this->generateUrl('sign_up', ['_locale' => 'nl']);

        // ...
    }
}

Note

ノート

If you pass to the generateUrl() method some parameters that are not part of the route definition, they are included in the generated URL as a query string:

ルート定義の一部ではないいくつかのパラメーターを generateUrl() メソッドに渡すと、それらはクエリ文字列として生成された URL に含まれます。
1
2
3
 
$this->generateUrl('blog', ['page' => 2, 'category' => 'Symfony']);
// the 'blog' route only defines the 'page' parameter; the generated URL is:
// /blog/2?category=Symfony

Caution

注意

While objects are converted to string when used as placeholders, they are not converted when used as extra parameters. So, if you're passing an object (e.g. an Uuid) as value of an extra parameter, you need to explicitly convert it to a string:

オブジェクトは、プレースホルダーとして使用される場合は文字列に変換されますが、追加のパラメーターとして使用される場合は変換されません。したがって、オブジェクト (Uuid など) を追加パラメーターの値として渡す場合は、明示的に文字列に変換する必要があります。
1
 
$this->generateUrl('blog', ['uuid' => (string) $entity->getUuid()]);

If your controller does not extend from AbstractController, you'll need to fetch services in your controller and follow the instructions of the next section.

コントローラーが AbstractController から拡張されていない場合は、コントローラーでサービスをフェッチし、次のセクションの手順に従う必要があります。

Generating URLs in Services

Inject the router Symfony service into your own services and use its generate() method. When using service autowiring you only need to add an argument in the service constructor and type-hint it with the UrlGeneratorInterface class:

ルーター Symfony サービスを独自のサービスに注入し、その生成() メソッドを使用します。サービス オートワイヤリングを使用する場合は、サービス コンストラクターに引数を追加し、UrlGeneratorInterface クラスで型ヒントを指定するだけです。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
// src/Service/SomeService.php
namespace App\Service;

use Symfony\Component\Routing\Generator\UrlGeneratorInterface;

class SomeService
{
    public function __construct(private UrlGeneratorInterface $router)
    {
    }

    public function someMethod()
    {
        // ...

        // generate a URL with no route arguments
        $signUpPage = $this->router->generate('sign_up');

        // generate a URL with route arguments
        $userProfilePage = $this->router->generate('user_profile', [
            'username' => $user->getUserIdentifier(),
        ]);

        // generated URLs are "absolute paths" by default. Pass a third optional
        // argument to generate different URLs (e.g. an "absolute URL")
        $signUpPage = $this->router->generate('sign_up', [], UrlGeneratorInterface::ABSOLUTE_URL);

        // when a route is localized, Symfony uses by default the current request locale
        // pass a different '_locale' value if you want to set the locale explicitly
        $signUpPageInDutch = $this->router->generate('sign_up', ['_locale' => 'nl']);
    }
}

Generating URLs in Templates

Read the section about creating links between pages in the main article about Symfony templates.

Symfony テンプレートに関するメイン記事のページ間のリンクの作成に関するセクションを読んでください。

Generating URLs in JavaScript

If your JavaScript code is included in a Twig template, you can use the path() and url() Twig functions to generate the URLs and store them in JavaScript variables. The escape() filter is needed to escape any non-JavaScript-safe values:

JavaScript コードが Twig テンプレートに含まれている場合、path() および url() Twig 関数を使用して URL を生成し、それらを JavaScript 変数に保存できます。 JavaScript で安全でない値をエスケープするには、escape() フィルターが必要です。
1
2
3
 
<script>
    const route = "{{ path('blog_show', {slug: 'my-blog-post'})|escape('js') }}";
</script>

If you need to generate URLs dynamically or if you are using pure JavaScript code, this solution doesn't work. In those cases, consider using the FOSJsRoutingBundle.

URL を動的に生成する必要がある場合、または純粋な JavaScript コードを使用している場合、このソリューションは機能しません。そのような場合は、FOSJsRoutingBundle の使用を検討してください。

Generating URLs in Commands

Generating URLs in commands works the same as generating URLs in services. The only difference is that commands are not executed in the HTTP context. Therefore, if you generate absolute URLs, you'll get http://localhost/ as the host name instead of your real host name.

コマンドでの URL の生成は、サービスでの URL の生成と同じように機能します。唯一の違いは、コマンドが HTTP コンテキストで実行されないことです。したがって、絶対 URL を生成すると、実際のホスト名ではなく、ホスト名として http://localhost/ が取得されます。

The solution is to configure the default_uri option to define the "request context" used by commands when they generate URLs:

解決策は、default_uri オプションを設定して、コマンドが URL を生成するときに使用する「リクエスト コンテキスト」を定義することです。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
 
# config/packages/routing.yaml
framework:
    router:
        # ...
        default_uri: 'https://example.org/my/path/'

Now you'll get the expected results when generating URLs in your commands:

コマンドで URL を生成すると、期待どおりの結果が得られます。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
// src/Command/SomeCommand.php
namespace App\Command;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Routing\RouterInterface;
// ...

class SomeCommand extends Command
{
    public function __construct(private RouterInterface $router)
    {
        parent::__construct();
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // generate a URL with no route arguments
        $signUpPage = $this->router->generate('sign_up');

        // generate a URL with route arguments
        $userProfilePage = $this->router->generate('user_profile', [
            'username' => $user->getUserIdentifier(),
        ]);

        // generated URLs are "absolute paths" by default. Pass a third optional
        // argument to generate different URLs (e.g. an "absolute URL")
        $signUpPage = $this->router->generate('sign_up', [], UrlGeneratorInterface::ABSOLUTE_URL);

        // when a route is localized, Symfony uses by default the current request locale
        // pass a different '_locale' value if you want to set the locale explicitly
        $signUpPageInDutch = $this->router->generate('sign_up', ['_locale' => 'nl']);

        // ...
    }
}

Note

ノート

By default, the URLs generated for web assets use the same default_uri value, but you can change it with the asset.request_context.base_path and asset.request_context.secure container parameters.

デフォルトでは、Web アセット用に生成された URL は同じ default_urivalue を使用しますが、asset.request_context.base_path および asset.request_context.secure コンテナー パラメーターで変更できます。

Checking if a Route Exists

In highly dynamic applications, it may be necessary to check whether a route exists before using it to generate a URL. In those cases, don't use the getRouteCollection() method because that regenerates the routing cache and slows down the application.

非常に動的なアプリケーションでは、ルートを使用して URL を生成する前に、ルートが存在するかどうかを確認する必要がある場合があります。そのような場合、getRouteCollection() メソッドを使用しないでください。ルーティング キャッシュが再生成され、アプリケーションの速度が低下するためです。

Instead, try to generate the URL and catch the RouteNotFoundException thrown when the route doesn't exist:

代わりに、URL を生成して、ルートが存在しない場合にスローされる RouteNotFoundException をキャッチしてみてください。
1
2
3
4
5
6
7
8
9
 
use Symfony\Component\Routing\Exception\RouteNotFoundException;

// ...

try {
    $url = $this->router->generate($routeName, $routeParameters);
} catch (RouteNotFoundException $e) {
    // the route is not defined...
}

Forcing HTTPS on Generated URLs

By default, generated URLs use the same HTTP scheme as the current request. In console commands, where there is no HTTP request, URLs use http by default. You can change this per command (via the router's getContext() method) or globally with these configuration parameters:

デフォルトでは、生成された URL は現在のリクエストと同じ HTTP スキームを使用します。HTTP リクエストがないコンソール コマンドでは、URL はデフォルトで http を使用します。これは、コマンドごとに (ルーターの getContext() メソッドを介して)、または次の構成パラメーターを使用してグローバルに変更できます。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
 
# config/services.yaml
parameters:
    router.request_context.scheme: 'https'
    asset.request_context.secure: true

Outside of console commands, use the schemes option to define the scheme of each route explicitly:

コンソール コマンドの外で、schemes オプションを使用して、各ルートのスキームを明示的に定義します。
  • Attributes
    属性
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
// src/Controller/SecurityController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class SecurityController extends AbstractController
{
    #[Route('/login', name: 'login', schemes: ['https'])]
    public function login(): Response
    {
        // ...
    }
}

The URL generated for the login route will always use HTTPS. This means that when using the path() Twig function to generate URLs, you may get an absolute URL instead of a relative URL if the HTTP scheme of the original request is different from the scheme used by the route:

ログイン ルート用に生成された URL は、常に HTTPS を使用します。これは、path() Twig 関数を使用して URL を生成する場合、元のリクエストの HTTP スキームがルートで使用されるスキームと異なる場合、相対 URL ではなく絶対 URL を取得する可能性があることを意味します。
1
2
3
4
5
6
 
{# if the current scheme is HTTPS, generates a relative URL: /login #}
{{ path('login') }}

{# if the current scheme is HTTP, generates an absolute URL to change
   the scheme: https://example.com/login #}
{{ path('login') }}

The scheme requirement is also enforced for incoming requests. If you try to access the /login URL with HTTP, you will automatically be redirected to the same URL, but with the HTTPS scheme.

スキーム要件は、着信要求にも適用されます。 /login URL に HTTP でアクセスしようとすると、同じ URL に自動的にリダイレクトされますが、HTTPS スキームが使用されます。

If you want to force a group of routes to use HTTPS, you can define the default scheme when importing them. The following example forces HTTPS on all routes defined as annotations:

ルートのグループに強制的に HTTPS を使用させたい場合は、それらをインポートするときに defaultscheme を定義できます。次の例では、アノテーションとして定義されたすべてのルートで HTTPS を強制します。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
 
# config/routes/annotations.yaml
controllers:
    resource: '../../src/Controller/'
    type: annotation
    defaults:
        schemes: [https]

Note

ノート

The Security component provides another way to enforce HTTP or HTTPS via the requires_channel setting.

Security コンポーネントは、requires_channel 設定を介して HTTP または HTTPS を強制する別の方法を提供します。

Troubleshooting

Here are some common errors you might see while working with routing:

ルーティングの作業中に発生する可能性のある一般的なエラーを次に示します。

Controller "App\Controller\BlogController::show()" requires that you provide a value for the "$slug" argument.

コントローラ "App\Controller\BlogController::show()" では、"$slug" 引数に値を指定する必要があります。

This happens when your controller method has an argument (e.g. $slug):

これは、コントローラ メソッドに引数 (例: $slug) がある場合に発生します。
1
2
3
4
 
public function show(string $slug): Response
{
    // ...
}

But your route path does not have a {slug} parameter (e.g. it is /blog/show). Add a {slug} to your route path: /blog/show/{slug} or give the argument a default value (i.e. $slug = null).

ただし、ルート パスには {slug} パラメータがありません (例: /blog/show)。ルート パスに {slug} を追加します: /blog/show/{slug} または引数にデフォルト値を指定します (つまり、$slug = null)。

Some mandatory parameters are missing ("slug") to generate a URL for route "blog_show".

ルート「blog_show」の URL を生成するためのいくつかの必須パラメーター (「slug」) が欠落しています。

This means that you're trying to generate a URL to the blog_show route but you are not passing a slug value (which is required, because it has a {slug} parameter in the route path). To fix this, pass a slug value when generating the route:

これは、blog_show ルートへの URL を生成しようとしているが、slug 値を渡していないことを意味します (ルート パスに {slug} パラメータがあるため、これは必須です)。これを修正するには、ルートを生成するときにスラッグ値を渡します。
1
 
$this->generateUrl('blog_show', ['slug' => 'slug-value']);

or, in Twig:

または、小枝で：
1
 
{{ path('blog_show', {slug: 'slug-value'}) }}

Learn more about Routing