Створення маршрутів zr атрибутів

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)
    ;
};

Cпівставлення 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',
        // 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
    }
}

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 до сервісів, які ви хочете використати в умовах маршруту:

Copy

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(), щоб послатися на цей сервіс всередині умов:

Copy

1
2
3
4

// Контролер (з використанням псевдоніма):
#[Route(condition: "service('route_checker').check(request)")]
// або без псевадоніма:
#[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. Вона корисна для того, щоб дізнатися, чому якийсь URL не виконує дію контролера, як ви того очікуєте:

1
2
3

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

  [OK] Route "app_lucky_number" matches

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

Уявіть, що ваш застосунок має маршрут 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+ - це регулярний вираз, який співпадає з однозначним числом будь-якої довжини. Тепер:

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

// 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\Requirement\Requirement;

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

1
2
3
4
5
6

# config/routes.yaml
blog_list:
    path:       /blog/{page}
    controller: App\Controller\BlogController::list
    requirements:
        page: !php/const Symfony\Component\Routing\Requirement\Requirement::DIGITS

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

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

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

Якщо ви хочете, вимоги можна вбудувати в кожний параметр, використовуючи синтаксис {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".

Тепер залиште попередню конфігурацію маршрута, але змініть аргументи дії контролера. Замість 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.

Перегляньте :ref:`Документацію з перетворення параметрів Doctrine <doctrine-entity-value-resolver>', щоб дізнатися про атрибут #[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: 'The "%alias_id%" route alias is deprecated. Do not use it anymore.'

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">
            The "%alias_id%" route alias is deprecated. Do not use it anymore.
        </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',
        'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
    )
;

У цьому прикладі, кожний раз, коли використовується псевдонім 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

# 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

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/');
};

Тепер ви отримаєте очікувані результати при генеруванні 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

// 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'
    }
}