Создание маршрутов как атрибутов

PHP-атрибуты позволяют определять маршруты рядом с кодом контроллеров, ассоциированных с этими маршрутами. Атрибуты нативны в PHP 8 и новее, поэтому вы можете использовать их сразу же.

Вам нужно добавить немного конфигурации к вашему проекту перед их использованием. Если ваш проект использует 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

Эта конфигурация сообщает Symfony искать маршруты, определенные как атрибуты, в классах, объявленных в пространстве имен App\Controller, и хранящихся в каталоге src/Controller/, которая следует стандарту PSR-4. Ядро тоже может действовать как контроллер, что особенно полезно для маленьких приложений, которые используют Symfony в качестве микрофеймворка.

Представьте, что вы хотите определить маршрут для URL /blog в вашем приложении. Чтобы сделать это, создайте класс контроллера как показано ниже:

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\Attribute\Route;

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

Эта конфигурация определяет маршрут под названием blog_list, который совпадает, когда пользователь запрашивает URL /blog. Когда происходит совпадение, приложение выполняет метод list() класса BlogController.

Имя маршрута (blog_list) сейчас не важно, но будет иметь значение позже, когда вы будете генерировать URL . Вам нужно только иметь в виду, что каждое имя маршрута должно быть уникальным в приложении.

Создание маршрутов в файлах YAML, XML или PHP

Вместо определения маршрутов в классах контроллера, вы можете определять их в отдельном файле YAML, XML или PHP. Главное преимущество - они не будут требовать никаких дополнительных зависимостей. Главный недостаток - вам нужно работать с несколькими файлами при проверке маршрутизации какого-то действия контроллера.

Следующий пример показывает, как определять в YAML/XML/PHP маршрут под названием blog_list, который ассоциирует URL /blog с действием list() BlogController:

1
2
3
4
5
6
7
8
9

# config/routes.yaml
blog_list:
    path: /blog
    # значение контроллера ммеет формат 'controller_class::method_name'
    controller: App\Controller\BlogController::list

    # еслм действие реализуется как метод __invoke() класса контроллера,
    # вы можете пропустить часть '::method_name':
    # controller: App\Controller\BlogController

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- config/routes.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <!-- значение контроллера ммеет формат 'controller_class::method_name' -->
    <route id="blog_list" path="/blog"
           controller="App\Controller\BlogController::list"/>

    <!-- еслм действие реализуется как метод __invoke() класса контроллера,
         вы можете пропустить часть '::method_name':
         controller="App\Controller\BlogController"/> -->
</routes>

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// config/routes.php
use App\Controller\BlogController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes): void {
    $routes->add('blog_list', '/blog')
        // значение контроллера ммеет формат [controller_class, method_name]
        ->controller([BlogController::class, 'list'])

        // еслм действие реализуется как метод __invoke() класса контроллера,
        // вы можете пропустить часть '::method_name':
        // ->controller(BlogController::class)
    ;
};

Сопоставление HTTP-методов

По умолчанию, маршруты совпадают с любым глаголом HTTP (GET, POST, PUT, и др.). Используйте опцию methods, чтобы ограничить глаголы, на которые долшжен реагировать каждый маршрут:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// src/Controller/BlogApiController.php
namespace App\Controller;

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

class BlogApiController extends AbstractController
{
    #[Route('/api/posts/{id}', methods: ['GET', 'HEAD'])]
    public function show(int $id): Response
    {
        // ... вернуть JSON-ответ с постом
    }

    #[Route('/api/posts/{id}', methods: ['PUT'])]
    public function edit(int $id): Response
    {
        // ... отредактировать пост
    }
}

1
2
3
4
5
6
7
8
9
10

# config/routes.yaml
api_post_show:
    path:       /api/posts/{id}
    controller: App\Controller\BlogApiController::show
    methods:    GET|HEAD

api_post_edit:
    path:       /api/posts/{id}
    controller: App\Controller\BlogApiController::edit
    methods:    PUT

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- config/routes.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="api_post_show" path="/api/posts/{id}"
        controller="App\Controller\BlogApiController::show"
        methods="GET|HEAD"/>

    <route id="api_post_edit" path="/api/posts/{id}"
        controller="App\Controller\BlogApiController::edit"
        methods="PUT"/>
</routes>

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// config/routes.php
use App\Controller\BlogApiController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes): void {
    $routes->add('api_post_show', '/api/posts/{id}')
        ->controller([BlogApiController::class, 'show'])
        ->methods(['GET', 'HEAD'])
    ;
    $routes->add('api_post_edit', '/api/posts/{id}')
        ->controller([BlogApiController::class, 'edit'])
        ->methods(['PUT'])
    ;
};

Сопоставление выражений

Используйте опцию condition, если вам нужно, чтобы какой-то маршрут совпадал, основываясь на некоторой произвольной логике совпадения:

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\Attribute\Route;

class DefaultController extends AbstractController
{
    #[Route(
        '/contact',
        name: 'contact',
        condition: "context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'",
        // выражения также могут включать в себя параметры конфигурации:
        // condition: "request.headers.get('User-Agent') matches '%app.allowed_browsers%'"
    )]
    public function contact(): Response
    {
        // ...
    }

    #[Route(
        '/posts/{id}',
        name: 'post_show',
        // выражения могут извлекать значения параметра маршрута, используя переменную "params"
        condition: "params['id'] < 1000"
    )]
    public function showPost(int $id): Response
    {
        // ... вернуть ответ JSON с постом
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# config/routes.yaml
contact:
    path:       /contact
    controller: 'App\Controller\DefaultController::contact'
    condition:  "context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'"
    # выражения также могут включать в себя параметры конфигурации:
    # condition: "request.headers.get('User-Agent') matches '%app.allowed_browsers%'"
    # выражения даже могут использовать переменные окружения:
    # condition: "context.getHost() == env('APP_MAIN_HOST')"

post_show:
    path:       /posts/{id}
    controller: 'App\Controller\DefaultController::showPost'
    # выражения могут извлекать значения параметра маршрута, используя переменную "params"
    condition:  "params['id'] < 1000"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<!-- config/routes.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="contact" path="/contact" controller="App\Controller\DefaultController::contact">
        <condition>context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'</condition>
        <!-- выражения также могут включать в себя параметры конфигурации: -->
        <!-- <condition>request.headers.get('User-Agent') matches '%app.allowed_browsers%'</condition> -->
        <!--выражения даже могут использовать переменные окружения: -->
        <!-- <condition>context.getHost() == env('APP_MAIN_HOST')</condition> -->
    </route>

    <route id="post_show" path="/posts/{id}" controller="App\Controller\DefaultController::showPost">
        <!-- выражения могут извлекать значения параметра маршрута, используя переменную "params" -->
        <condition>params['id'] &lt; 1000</condition>
    </route>
</routes>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// config/routes.php
use App\Controller\DefaultController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes): void {
    $routes->add('contact', '/contact')
        ->controller([DefaultController::class, 'contact'])
        ->condition('context.getMethod() in ["GET", "HEAD"] and request.headers.get("User-Agent") matches "/firefox/i"')
        // выражения также могут включать в себя параметры конфигурации:
        // ->condition('request.headers.get("User-Agent") matches "%app.allowed_browsers%"')
        // выражения даже могут использовать переменные окружения:
        // ->condition('context.getHost() == env("APP_MAIN_HOST")')
    ;
    $routes->add('post_show', '/posts/{id}')
        ->controller([DefaultController::class, 'showPost'])
        // выражения могут извлекать значения параметра маршрута, используя переменную "params"
        ->condition('params["id"] < 1000')
    ;
};

Значение опции condition - это любое валдиное выражение ExpressionLanguage и может использовать любую из этих переменных, созданных Symfony:

context

Экземпляр RequestContext, который содержит наиболее фунламентальную информацию о сопоставляемом маршруте.

request

Объект Запроса Symfony , который представляет текущий запрос.

params

Массив совпадающих параметров маршрута для текущего маршрута.

Вы также можете использовать эти функции:

env(string $name)

Возвращает значение переменной, используя Процессоры переменных окружения

service(string $alias)

Возвращает сервис условий маршрутизации.

Для начала, добавьте атрибут #[AsRoutingConditionService] или тег routing.condition_service к сервисам, которые вы хотите использовать в условиях маршрута:

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

Затем, используйте функцию 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)")]

За кулисами. выражения компилируются в чистый PHP. Из-за этого, использование ключа condition не вызывает дополнительной нагрузки кроме времени, необходимого для выполнения низлежащего PHP.

Отладка маршрутов

По мере роста вашего приложения, у вас в итоге будет много маршрутов. Symfony включает в себя несколько команд, чтобы помочь вам с отладкой проблем маршрутизации. Для начала, команда debug:router перечисляет все маршруты вашего приложения в том же порядке, в котором их оценивает Symfony:

1
2
3
4
5
6
7
8
9
10
11
12

$ php bin/console debug:router

----------------  -------  -------  -----  --------------------------------------------
Имя               Метод    Схема    Хост   Путь
----------------  -------  -------  -----  --------------------------------------------
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}
----------------  -------  -------  -----  --------------------------------------------

Передайте имя (или его часть) какого-то маршрута этому аргументу, чтобы отобразить детали маршрута:

1
2
3
4
5
6
7
8
9
10
11

$ php bin/console debug:router app_lucky_number

+--------------+---------------------------------------------------------+
| Свойство     | Значение                                                |
+--------------+---------------------------------------------------------+
| Имя маршрута | app_lucky_number                                        |
| Путь         | /lucky/number/{max}                                     |
| ...          | ...                                                     |
| Опции        | compiler_class: Symfony\Component\Routing\RouteCompiler |
|              | utf8: true                                              |
+--------------+---------------------------------------------------------+

Другая команда называется router:match и она показывает, какой маршрут будет совпадать с заданным URL. It's useful to find out why some URL is not executing the controller action that you expect:

1
2
3

$ php bin/console router:match /lucky/number/8

  [OK] Route "app_lucky_number" совпадает

Валидация параметров

Представьте, что ваше приложение имеет маршрут blog_show (URL: /blog/{slug}) и маршрут blog_list (URL: /blog/{page}). Учитывая, что параметры маршрута принимают любые значения, нет возможности дифферинциировать эти два маршрута.

Если пользователь запрашивает /blog/my-first-post, оба маршрута совпадут, и Symfony будет использовать маршрут, который был определен первым. Чтобы исправить это, добавьте некоторую валидацию к параметру {page}, используя опцию requirements:

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\Attribute\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
    {
        // ...
    }
}

1
2
3
4
5
6
7
8
9
10

# config/routes.yaml
blog_list:
    path:       /blog/{page}
    controller: App\Controller\BlogController::list
    requirements:
        page: '\d+'

blog_show:
    path:       /blog/{slug}
    controller: App\Controller\BlogController::show

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<!-- config/routes.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="blog_list" path="/blog/{page}" controller="App\Controller\BlogController::list">
        <requirement key="page">\d+</requirement>
    </route>

    <route id="blog_show" path="/blog/{slug}"
           controller="App\Controller\BlogController::show"/>
</routes>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// config/routes.php
use App\Controller\BlogController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->add('blog_list', '/blog/{page}')
        ->controller([BlogController::class, 'list'])
        ->requirements(['page' => '\d+'])
    ;

    $routes->add('blog_show', '/blog/{slug}')
        ->controller([BlogController::class, 'show'])
    ;
    // ...
};

Опция requirements определяет регулярные PHP-выражения, которым должны соответствовать параметры маршрута для того, чтобы совпадал весь маршрут. В этом примере, \d+ - это регулярное выражение, которое совпадает с однозначным числом любой длины. Теперь:

Если вы хотите, требования можно встроить в каждый параметр, используя синтаксис {parameter_name<requirements>}. Эта функция делает конфигурацию более компактной, но может уменьшить читаемость маршрута, если требования сложные:

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\Attribute\Route;

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

1
2
3
4

# config/routes.yaml
blog_list:
    path:       /blog/{page<\d+>}
    controller: App\Controller\BlogController::list

1
2
3
4
5
6
7
8
9
10
11
12

<!-- config/routes.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="blog_list" path="/blog/{page<\d+>}"
           controller="App\Controller\BlogController::list"/>

    <!-- ... -->
</routes>

1
2
3
4
5
6
7
8
9
10

// config/routes.php
use App\Controller\BlogController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->add('blog_list', '/blog/{page<\d+>}')
        ->controller([BlogController::class, 'list'])
    ;
    // ...
};

Необязательные параметры

В предыдущем примере, URL blog_list - /blog/{page}. Если пользователи посещают /blog/1, он будет совпадать. Но если они посетят /blog, он не будет совпадать. Как только вы добавите к маршруту параметр, он должен иметь значение.

Вы также можете сделать так, чтобы blog_list снова совпадал, когда пользователь посещает /blog, добавив значение по умолчанию к параметру {page}. При использовании аннотаций, значения по умолчанию определяются в аргумнтах действия контроллера. В других форматах конфигурации они определяются опцией defaults:

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\Attribute\Route;

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

1
2
3
4
5
6
7
8
9
10
11

# config/routes.yaml
blog_list:
    path:       /blog/{page}
    controller: App\Controller\BlogController::list
    defaults:
        page: 1
    requirements:
        page: '\d+'

blog_show:
    # ...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- config/routes.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="blog_list" path="/blog/{page}" controller="App\Controller\BlogController::list">
        <default key="page">1</default>

        <requirement key="page">\d+</requirement>
    </route>

    <!-- ... -->
</routes>

1
2
3
4
5
6
7
8
9
10
11

// config/routes.php
use App\Controller\BlogController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->add('blog_list', '/blog/{page}')
        ->controller([BlogController::class, 'list'])
        ->defaults(['page' => 1])
        ->requirements(['page' => '\d+'])
    ;
};

Теперь, когда пользователь посещает /blog, маршрут blog_list будет совпадать, а $page по умолчанию будет иметь значение 1.

Если вы хотите всегда включать какое-то значение по умолчанию в сгенерированном URL (например, для генерирования /blog/1 вместо /blog в предыдущем примере), добавьте символ ! перед именем параметра: /blog/{!page}

Как это происходит с требованиями, значения по умолчанию также могут быть встроены в каждый параметр, используя синтаксис {parameter_name?default_value}. Эта функция совместима со встроенными требованиями, поэтому вы можете встроить обе в один параметр:

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\Attribute\Route;

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

1
2
3
4

# config/routes.yaml
blog_list:
    path:       /blog/{page<\d+>?1}
    controller: App\Controller\BlogController::list

1
2
3
4
5
6
7
8
9
10
11
12

<!-- config/routes.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="blog_list" path="/blog/{page<\d+>?1}"
           controller="App\Controller\BlogController::list"/>

    <!-- ... -->
</routes>

1
2
3
4
5
6
7
8
9

// config/routes.php
use App\Controller\BlogController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->add('blog_list', '/blog/{page<\d+>?1}')
        ->controller([BlogController::class, 'list'])
    ;
};

Параметр приоритетности

Symfony оценивает маршруты в порядке, котором они определены. Если путь маршрута совпадает со многими разными паттернами, он может предотвратить другие маршруты от совпадения. В YAML и XML вы можете перемещать определения маршрутов вверх и вниз в файле конфигурации, чтобы контролировать их приоритетность. В маршрутах, определенных как PHP-аннотации или атрибуты, это намного сложнее сделать, поэтому вы можете установить необязательный параметр priority в таких маршрутах, чтобы контролировать их приоритетность:

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\Attribute\Route;

class BlogController extends AbstractController
{
    /**
     * Этот маршрут имеет жадный паттерн и определяется первым.
     */
    #[Route('/blog/{slug}', name: 'blog_show')]
    public function show(string $slug): Response
    {
        // ...
    }

    /**
     * Этот маршрут не может быть сопоставлен без определения приоритета выше, чем 0.
     */
    #[Route('/blog/list', name: 'blog_list', priority: 2)]
    public function list(): Response
    {
        // ...
    }
}

Параметр приоритета ожидает целое значение. Маршруты с более высоким приоритетом сортируются до маршрутов с более низким приоритетом. Значение по умолчанию, если параметр не определен, - 0.

Конверсия параметров

Распространенной потребностью маршрутизации является конверсия значения, хранящегося в некотором параметре (например, целое число, действующее, как ID пользователя), в другое значение (например, объект, представляющий пользователя). Эта функция называется "param converter".

Чтобы добавить поддержку "param converters", нам нужен SensioFrameworkExtraBundle:

1

$ composer require sensio/framework-extra-bundle

Теперь сохраните предыдущую конфигурацию маршрута, но измените аргументы
действия контроллера. Вместо string$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\Attribute\Route;

class BlogController extends AbstractController
{
    // ...

    #[Route('/blog/{slug}', name: 'blog_show')]
    public function show(BlogPost $post): Response
    {
        // $post это объект, чей слаг сооветствует параметру маршрутизации

        // ...
    }
}

Если ваши аргументы контроллера включают в себя подсказки для объектов (BlogPost в этом случае), "param converter" делает запрос в базу данных, чтобы найти объект, использующий параметры запроса (slug в этом случае). Если объект не найден, Symfony автоматически генерирует ответ 404.

Прочтите документацию Doctrine по преобразованию параметров , чтобы узнать об атрибуте #[MapEntity], который может быть использован для настройки запросов базы данных, используемых для получения объектов из параметра маршрутов.

Подкрепленные параметры исчисления

В качестве параметров маршрута можно использовать подкрепленные исчисления PHP, поскольку Symfony
автоматически преобразует их в скалярные значения.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// src/Controller/OrderController.php
namespace App\Controller;

use App\Enum\OrderStatusEnum;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class OrderController extends AbstractController
{
    #[Route('/orders/list/{status}', name: 'list_orders_by_status')]
    public function list(OrderStatusEnum $status = OrderStatusEnum::Paid): Response
    {
        // ...
    }
}

Специальные параметры

В дополнение к вашим собственным параметрам, маршруты могут иметь любые следующие параметры, созданные Symfony:

_controller

Этот параметр используется для определения того, какой контроллер и действие выполняется при совпадении маршрута.

_format

Совпавшее значение используется для установки "request format" объекта Request. Это используется для таких вещей, как установка Content-Type ответа (например, формат json переводится в Content-Type для application/json).

_fragment

Используется для установки идентификатора фрагмента, что является последней необязательной частью URL, которая начинается с символа # и используется для идентификации части документа.

_locale

Используется для установки локали в запросе.

Вы можете добавить эти атрибуты (кроме _fragment) как в индивидуальных маршрутах, так и в импортированных. Symfony определяет некоторые особые атрибуты с одинаковым именем (кроме нижнего подчеркивания в начале), поэтому вам может быть легче их определить:

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

1
2
3
4
5
6
7
8
9

# config/routes.yaml
article_search:
  path:        /articles/{_locale}/search.{_format}
  controller:  App\Controller\ArticleController::search
  locale:      en
  format:      html
  requirements:
      _locale: en|fr
      _format: html|xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<!-- config/routes.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="article_search"
        path="/articles/{_locale}/search.{_format}"
        controller="App\Controller\ArticleController::search"
        locale="en"
        format="html">

        <requirement key="_locale">en|fr</requirement>
        <requirement key="_format">html|xml</requirement>

    </route>
</routes>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// config/routes.php
namespace Symfony\Component\Routing\Loader\Configurator;

use App\Controller\ArticleController;

return static function (RoutingConfigurator $routes): void {
    $routes->add('article_show', '/articles/{_locale}/search.{_format}')
        ->controller([ArticleController::class, 'search'])
        ->locale('en')
        ->format('html')
        ->requirements([
            '_locale' => 'en|fr',
            '_format' => 'html|xml',
        ])
    ;
};

Дополнительные параметры

В опции маршрута defaults вы можете по желанию определить параметры, не включенные в конфигурацию маршрута. Это полезно для передачи дополнительных аргументов контроллерам маршрутов:

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\Attribute\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
    {
        // ...
    }
}

1
2
3
4
5
6
7

# config/routes.yaml
blog_index:
    path:       /blog/{page}
    controller: App\Controller\BlogController::index
    defaults:
        page: 1
        title: "Hello world!"

1
2
3
4
5
6
7
8
9
10
11
12

<!-- config/routes.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="blog_index" path="/blog/{page}" controller="App\Controller\BlogController::index">
        <default key="page">1</default>
        <default key="title">Hello world!</default>
    </route>
</routes>

1
2
3
4
5
6
7
8
9
10
11
12
13

// config/routes.php
use App\Controller\BlogController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->add('blog_index', '/blog/{page}')
        ->controller([BlogController::class, 'index'])
        ->defaults([
            'page'  => 1,
            'title' => 'Hello world!',
        ])
    ;
};

Символы слеша в параметрах маршрута

Параметры маршрута могут содержать любые значения, кроме символа слеша /, потому что этот символ используется для разделения разных частей URL. Например, если значение token в маршруте /share/{token} содержит символ /, этот маршруте не будет совпадать.

Возможным решением будет изменение требований параметра, чтобы они были более вольными:

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\Attribute\Route;

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

1
2
3
4
5
6

# config/routes.yaml
share:
    path:       /share/{token}
    controller: App\Controller\DefaultController::share
    requirements:
        token: .+

1
2
3
4
5
6
7
8
9
10
11

<!-- config/routes.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="share" path="/share/{token}" controller="App\Controller\DefaultController::share">
        <requirement key="token">.+</requirement>
    </route>
</routes>

1
2
3
4
5
6
7
8
9
10
11
12

// config/routes.php
use App\Controller\DefaultController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->add('share', '/share/{token}')
        ->controller([DefaultController::class, 'share'])
        ->requirements([
            'token' => '.+',
        ])
    ;
};

Устаревание псевдонимов маршрута

Если какой-то псевдоним маршрута больше не стоит использовать (так как он устарел или вы решили больше его не поддерживать), вы можете объявить его определение устаревшим:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

new_route_name:
    alias: original_route_name

    # это выводит следующее общее сообщение об устаревании:
    # Начиная с acme/package 1.2: Псевдоним маршрута "new_route_name" устарел. Вы должны перестать использовать его, так как он будет удален в будущем.
    deprecated:
        package: 'acme/package'
        version: '1.2'

    # вы также можете определить пользовательское сообщение об устаревании (доступен заполнитель %alias_id%)
    deprecated:
        package: 'acme/package'
        version: '1.2'
        message: 'Псевдоним маршрута "%alias_id%" устарел. Не используйте его больше.'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<?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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="new_route_name" alias="original_route_name">
        <!-- это выводит следующее общее сообщение об устаревании:
             Начиная с acme/package 1.2: Псевдоним маршрута "new_route_name" устарел. Вы должны перестать использовать его, так как он будет удален в будущем. -->
        <deprecated package="acme/package" version="1.2"/>

        <!-- вы также можете определить пользовательское сообщение об устаревании (доступен заполнитель %alias_id%) -->
        <deprecated package="acme/package" version="1.2">
            Псевдоним маршрута "%alias_id%" устарел. Не используйте его больше.
        </deprecated>
    </route>
</routes>

1
2
3
4
5
6
7
8
9
10
11
12

$routes->alias('new_route_name', 'original_route_name')
    // это выводит следующее общее сообщение об устаревании:
    // Начиная с acme/package 1.2: Псевдоним маршрута "new_route_name" устарел. Вы должны перестать использовать его, так как он будет удален в будущем.
    ->deprecate('acme/package', '1.2', '')

    // вы также можете определить пользовательское сообщение об устаревании (доступен заполнитель %alias_id%)
    ->deprecate(
        'acme/package',
        '1.2',
        'Псевдоним маршрута "%alias_id%" устарел. Не используйте его больше.'
    )
;

В этом примере, каждый раз, когда используется псевдоним new_route_name, запускается уведомление об устаревании, советующее вам перестать использовать этот псевдоним.

Сообщение на самом деле является шаблоном сообщения, который заменяет явления заполнителя %alias_id% именем псевдонима маршрута. У вас должно быть хотя бы одно явление заполнителя %alias_id% в вашем шаблоне.

Отображение шаблона прямо из маршрута

Прочтите раздел об отображении шаблона из маршрута в главной статье о шаблонах Symfony.

Перенапрвоение на URL и маршруты прямо из маршрута

Используйте RedirectController, чтобы перенаправить на другие маршруты и 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

# config/routes.yaml
doc_shortcut:
    path: /doc
    controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController
    defaults:
        route: 'doc_page'
        # по желанию вы можете определить какие-то аргументы, переданные маршруту
        page: 'index'
        version: 'current'
        # перенаправляния временные по умолчанию (код 302), но вы можете сделать их постоянными (код 301)
        permanent: true
        # добавьтье это, чтобы сохранить изначальные параметры строки запроса при перенаправлении
        keepQueryParams: true
        # добавьте это, чтобы оставить метод HTTP при перенаправлении. Статус перенаправления изменяется
        # * для временных перенаправлений, используется статус-код 307 вместо 302
        # * для постоянных перенаправлений, используется статус-код 307 вместо 301
        keepRequestMethod: true
        # добавьте это, чтобы удалить все исходные атрибуты маршрутов при перенаправлении
        ignoreAttributes: true
        # or specify which attributes to ignore:
        # ignoreAttributes: ['offset', 'limit']


legacy_doc:
    path: /legacy/doc
    controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController
    defaults:
        # это значение может быть абсолютным путем или URL
        path: 'https://legacy.example.com/doc'
        permanent: true

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

<!-- config/routes.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="doc_shortcut" path="/doc"
           controller="Symfony\Bundle\FrameworkBundle\Controller\RedirectController">
        <default key="route">doc_page</default>
        <!-- по желанию вы можете определить какие-то аргументы, переданные маршруту -->
        <default key="page">index</default>
        <default key="version">current</default>
        <!-- перенаправляния временные по умолчанию (код 302), но вы можете сделать их постоянными (код 301)-->
        <default key="permanent">true</default>
        <!-- добавьтье это, чтобы сохранить изначальные параметры строки запроса при перенаправлении -->
        <default key="keepQueryParams">true</default>
        <!-- добавьте это, чтобы оставить метод HTTP при перенаправлении. Статус перенаправления изменяется:
             * для временных перенаправлений, используется статус-код 307 вместо 302
             * для постоянных перенаправлений, используется статус-код 307 вместо 301 -->
        <default key="keepRequestMethod">true</default>
    </route>

    <route id="legacy_doc" path="/legacy/doc"
           controller="Symfony\Bundle\FrameworkBundle\Controller\RedirectController">
        <!-- это значение может быть абсолютным путем или URL -->
        <default key="path">https://legacy.example.com/doc</default>
        <!-- перенаправления временнеые по умолчанию (код 302), но вы можете сделать их постоянными (код 301)-->
        <default key="permanent">true</default>
    </route>
</routes>

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

// config/routes.php
use App\Controller\DefaultController;
use Symfony\Bundle\FrameworkBundle\Controller\RedirectController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->add('doc_shortcut', '/doc')
        ->controller(RedirectController::class)
         ->defaults([
            'route' => 'doc_page',
            // по желанию вы можете определить какие-то аргументы, переданные маршруту
            'page' => 'index',
            'version' => 'current',
            // перенаправляния временные по умолчанию (код 302), но вы можете сделать их постоянными (код 301)
            'permanent' => true,
            // добавьтье это, чтобы сохранить изначальные параметры строки запроса при перенаправлении
            'keepQueryParams' => true,
            // добавьте это, чтобы оставить метод HTTP при перенаправлении. Статус перенаправления изменяется:
            // * для временных перенаправлений, используется статус-код 307 вместо 302
            // * для постоянных перенаправлений, используется статус-код 307 вместо 301
            'keepRequestMethod' => true,
        ])
    ;

    $routes->add('legacy_doc', '/legacy/doc')
        ->controller(RedirectController::class)
         ->defaults([
            // это значение может быть абсолютным путем или URL
            'path' => 'https://legacy.example.com/doc',
            // перенаправления временнеые по умолчанию (код 302), но вы можете сделать их постоянными (код 301)
            'permanent' => true,
        ])
    ;
};

Генерирование URL в контроллерах

Если ваш контроллер расширяется из 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\Attribute\Route;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;

class BlogController extends AbstractController
{
    #[Route('/blog', name: 'blog_list')]
    public function list(): Response
    {
        // сгенерируйте URL без аргументов маршрута
        $signUpPage = $this->generateUrl('sign_up');

        // сгенарируйте URL с аргументами марашрута
        $userProfilePage = $this->generateUrl('user_profile', [
            'username' => $user->getUserIdentifier(),
        ]);

        // сгенерированные URL являются "абсолютными путями" по умолчанию. Передайте третий необязательный
        // аргумент, чтобы сгенерировать другие URL (например, "абсолютный URL")
        $signUpPage = $this->generateUrl('sign_up', [], UrlGeneratorInterface::ABSOLUTE_URL);

        // когда маршрут локализован, Symfony по умолчанию использует текущую локаль запроса
        // передайте другое знаениче '_locale', если вы хотите установить локаль ясно
        $signUpPageInDutch = $this->generateUrl('sign_up', ['_locale' => 'nl']);

        // ...
    }
}

1
2
3

$this->generateUrl('blog', ['page' => 2, 'category' => 'Symfony']);
// маршрут 'blog' определяет только параметр 'page'; сгенерированный URL:
// /blog/2?category=Symfony

1

$this->generateUrl('blog', ['uuid' => (string) $entity->getUuid()]);

Если ваш контроллер не расширяется из AbstractController, вам понадобится извлечь сервисы в вашем контроллере и следовать инструции в следующем разделе.

Генерирование URL в сервисах

Внедрите сервис Symfony router в ваши собственные сервисы и используйте его метод generate(). При использовании автомонтирования сервисов, вам понадобится только добавить аргумент в конструктор сервиса и типизировать его классом 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
33

// src/Service/SomeService.php
namespace App\Service;

use Symfony\Component\Routing\Generator\UrlGeneratorInterface;

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

    public function someMethod(): void
    {
        // ...

        // сгенерируйте URL без аргументов маршрута
        $signUpPage = $this->router->generate('sign_up');

        // сгенерируйте URL с аргументами маршрута
        $userProfilePage = $this->router->generate('user_profile', [
            'username' => $user->getUserIdentifier(),
        ]);

        // сгенерированные URL являются "абсолютными путями" по умолчанию. Передайте третий необязательный
        // аргумент, чтобы сгенерировать другие URL (например, "абсолютный URL")
        $signUpPage = $this->router->generate('sign_up', [], UrlGeneratorInterface::ABSOLUTE_URL);

        // когда маршрут локализован, Symfony по умолчанию использует текущую локаль запроса
        // передайте другое знаениче '_locale', если вы хотите установить локаль ясно
        $signUpPageInDutch = $this->router->generate('sign_up', ['_locale' => 'nl']);
    }
}

Генерирование URL в шаблонах

Прочтите раздел о создании ссылок между страницами в главной статье о шаблонах Symfony.

Генерирование URL в JavaScript

Если ваш код JavaScript включен в шаблон Twig, вы можете использовать функции Twig path() и url(), чтобы сгенрировать URL и сохранить их в переменных JavaScript. Фильтр escape() необходим для экранирования любых небезопасных для JavaScript значений:

1
2
3

<script>
    const route = "{{ path('blog_show', {slug: 'my-blog-post'})|escape('js') }}";
</script>

Если вам нужно сгенерировать URL динамически или если вы используете чистый код JavaScript, это решение не работает. В таких случаях рассмотрите использование FOSJsRoutingBundle.

Генерирование URL в командах

Генерирование URL в командах работает так же, как генерирование URL в сервисах . Единственная разница в том, что команды не выполняются в HTTP-контексте. Следовательно, если вы генерируете абсолютные URL, вы получите http://localhost/ в качестве имени хоста вместо вашего реального имени хоста.

Решением будет сконфигурировать опцию default_uri, чтобы определить "контекст запроса", используемы командами, когда они генерируют URL:

1
2
3
4
5

# config/packages/routing.yaml
framework:
    router:
        # ...
        default_uri: 'https://example.org/my/path/'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<!-- config/packages/routing.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony
        https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:router default-uri="https://example.org/my/path/">
            <!-- ... -->
        </framework:router>
    </framework:config>
</container>

1
2
3
4
5
6

// config/packages/routing.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->router()->defaultUri('https://example.org/my/path/');
};

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

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

// 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;
// ...

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

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // сгенерируйте URL без аргументов маршрута
        $signUpPage = $this->router->generate('sign_up');

        // сгенерируйте URL с аргументами маршрута
        $userProfilePage = $this->router->generate('user_profile', [
            'username' => $user->getUserIdentifier(),
        ]);

        // сгенерированные URL являются "абсолютными путями" по умолчанию. Передайте третий необязательный
        // аргумент, чтобы сгенерировать другие URL (например, "абсолютный URL")
        $signUpPage = $this->router->generate('sign_up', [], UrlGeneratorInterface::ABSOLUTE_URL);

        // когда маршрут локализован, Symfony по умолчанию использует текущую локаль запроса
        // передайте другое знаениче '_locale', если вы хотите установить локаль ясно
        $signUpPageInDutch = $this->router->generate('sign_up', ['_locale' => 'nl']);

        // ...
    }
}

Проверка существования маршрута

В высокодинамичных приложениях может быть необходимо проверить, существует ли маршрут, до его использования для генерирования URL. В этих случаях, не используйте метод getRouteCollection(), потому что это регенерирует кеш маршрутизации и замедляет приложение.

Вместо этого, попоробуйте сгенрировать 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) {
    // маршрут не определен...
}

Форсирование HTTPS в сгенерированных URL

По умолчанию, сгенерированные URL используют ту же HTTP-схему, что и текущий запрос. В консольных командах, где нет HTTP-запроса, URL используют http по умолчанию. Вы можете изменить это для каждой команды (через метод маршрутизатора getContext()) или глобально со следующими параметрами конфигурации:

1
2
3
4

# config/services.yaml
parameters:
    router.request_context.scheme: 'https'
    asset.request_context.secure: true

1
2
3
4
5
6
7
8
9
10
11
12
13

<!-- config/services.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"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <parameters>
        <parameter key="router.request_context.scheme">https</parameter>
        <parameter key="asset.request_context.secure">true</parameter>
    </parameters>

</container>

1
2
3
4
5

// config/services.php
$container->parameters()
    ->set('router.request_context.scheme', 'https')
    ->set('asset.request_context.secure', true)
;

Вне конспольных команд, используйте опцию schemes, чтобы ясно определить схему каждого маршрута:

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\Attribute\Route;

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

1
2
3
4
5

# config/routes.yaml
login:
    path:       /login
    controller: App\Controller\SecurityController::login
    schemes:    [https]

1
2
3
4
5
6
7
8
9
10

<!-- config/routes.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 https://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="login" path="/login" schemes="https"
           controller="App\Controller\SecurityController::login"/>
</routes>

1
2
3
4
5
6
7
8
9
10

// config/routes.php
use App\Controller\SecurityController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->add('login', '/login')
        ->controller([SecurityController::class, 'login'])
        ->schemes(['https'])
    ;
};

URL, сгенерированный для маршрута login всегда будет использовать HTTPS. Это означает, что при использовании функции Twig path() для генерирования URL, вы можете получить абсолютный URL вместо относительного, если HTTP-схема изнчального запроса отличается от схемы, используемой маршрутом:

1
2
3
4
5
6

{# если текущая схема - HTTPS, генерирует относительный URL: /login #}
{{ path('login') }}

{# если текущая схема - HTTP, генерирует абсолютный URL для изменения
   схемы: https://example.com/login #}
{{ path('login') }}

Требование схемы также форсируется для входящих запросов. Если вы попробуете получить дотуп к URL /login с HTTP, вы автоматически будете перенаправлены на тот же URL, но с HTTPS-схемой.

Если вы хотите заставить группу маршрутов использовать HTTPS, вы можете определить схему по умолчанию при их импортировании. Следующий пример форсирует HTTPS на все маршруты, определенные как аннотации:

1
2
3
4
5

# config/routes/attributes.yaml
controllers:
    resource: '../../src/Controller/'
    type: attribute
    schemes: [https]

1
2
3
4
5
6
7
8
9

<!-- config/routes/attributes.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <import resource="../../src/Controller/" type="attribute" schemes="https"/>
</routes>

1
2
3
4
5
6
7
8

// config/routes/attributes.php
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->import('../../src/Controller/', 'attribute')
        ->schemes(['https'])
    ;
};

Подписание URI

Подписанный URI - это URI, содержащий хеш-значение, которое зависит от содержания
URI. Таким образом, впоследствии можно проверить целостность подписанного URI, повторно вычислив его хеш-значение и сравнив его с хешем, включенным в URI.

Symfony предоставляет утилиту для подписания URI с помощью сервиса UriSigner, который вы можете внедрить в свои сервисы или контроллеры:

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\HttpFoundation\UriSigner;

class SomeService
{
    public function __construct(
        private UriSigner $uriSigner,
    ) {
    }

    public function someMethod(): void
    {
        // ...

        // сгенерировать URL самостоятельно или получить его каким-то образом...
        $url = 'https://example.com/foo/bar?sort=desc';

        // подписать URL (добавляет параметр запроса под названием '_hash')
        $signedUrl = $this->uriSigner->sign($url);
        // $url = 'https://example.com/foo/bar?sort=desc&_hash=e4a21b9'

        // проверить подпись URL
        $uriSignatureIsValid = $this->uriSigner->check($signedUrl);
        // $uriSignatureIsValid = true

        // если у вас есть доступ к текущему объекту Request, вы можете использовать этот
        // другой метод, чтобы передать весь объект Request вместо URI:
        $uriSignatureIsValid = $this->uriSigner->checkRequest($request);
    }
}

По соображениям безопасности обычно принято заставлять подписанные URI заканчивать свое действие через некоторое время (например, при использовании их для сброса учетных данных пользователя). По умолчанию подписанные URI не заканчивают свое действие, но вы можете задать дату/время истечения срока действия, используя $expiration аргумента Symfony\\Component\\HttpFoundation\\UriSigner::sign():

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\HttpFoundation\UriSigner;

class SomeService
{
    public function __construct(
        private UriSigner $uriSigner,
    ) {
    }

    public function someMethod(): void
    {
        // ...

        // сгенерировать URL самостоятельно или получить его каким-то образом...
        $url = 'https://example.com/foo/bar?sort=desc';

        // подписать URL с явной датой истечения срока
        $signedUrl = $this->uriSigner->sign($url, new \DateTimeImmutable('2050-01-01'));
        // $signedUrl = 'https://example.com/foo/bar?sort=desc&_expiration=2524608000&_hash=e4a21b9'

        // если вы передадите \DateInterval, теперь он будет добавляться для получения даты истечения срока
        $signedUrl = $this->uriSigner->sign($url, new \DateInterval('PT10S'));  // валидный в течение 10 от сейчас
        // $signedUrl = 'https://example.com/foo/bar?sort=desc&_expiration=1712414278&_hash=e4a21b9'

        // вы также можете использовать временную метку в секундах
        $signedUrl = $this->uriSigner->sign($url, 4070908800); // временная метка для даты 2099-01-01
        // $signedUrl = 'https://example.com/foo/bar?sort=desc&_expiration=4070908800&_hash=e4a21b9'
    }
}