Дата оновлення перекладу 2022-05-10

Контролер

Контролер - це створена вами PHP-функція, яка дивиться на об’єкт Request, створює та повертає об’єкт Response. Віповідь може бути HTML-сторінкою, JSON, XML, файлом для зберігання, перенаправленням, помилкою 404 або чимось іншим. Контролер може запускати будь-яку довільну логіку, яка потрібна вашому додатку для відображення змісту сторінки.

Tip

Якщо ви ще не створили свою першу робочу сторінку, прочитайте главу створення сторінки, а потім повертайтесь!

Простий контролер

В той час як контролер може бути будь-якой PHP-сутністю (функцією, методом об’екту або Closure), зазвичай контролер - це метод всередині класу контролера:

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

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class LuckyController
{
    /**
     * @Route("/lucky/number/{max}", name="app_lucky_number")
     */
    public function number($max)
    {
        $number = random_int(0, $max);

        return new Response(
            '<html><body>Lucky number: '.$number.'</body></html>'
        );
    }
}

Контролер - це метод number(), який розташовано всередині класу контролера LuckyController.

Цей контролер достатньо прямолінійний:

  • Рядок 2: Symfony використовує переваги простору імен PHP, щоб вказати простір імен для класу контролера.
  • Рядок 4: Symfony знов використовує переваги простору імен PHP: ключове слово use імпортує клас Response, який має повернути контролер.
  • Рядок 7: Технічно, клас можна назвати як завгодно, але за домовленістю, він має суфікс Controller.
  • Рядок 12: Методу дії дозволено мати аргумент $max, завдяки символу підстановки в маршруті {max}.
  • Рядок 16: Контролер створює та повертає об’єкт Response.

Зв’язування URL з контролером

Для того, щоб побачити результат цього контролера, вам знадобиться прив’язати URL до нього за допомогою маршруту. Це було зроблено вище за допомогою анотації маршруту @Route("/lucky/number/{max}").

Щоб побачити вашу сторінку, перейдіть на цей URL у вашому браузері: http://localhost:8000/lucky/number/100

Для того, щоб дізнатися більше про маршрутизацію, див. главу Маршрутизация.

Базовий клас контролера та сервіси

Для допомоги в розробці, Symfony включає в себе опціональний базовий клас AbstractController. Ви можете розширити його, щоб отримати доступ до методів-хелперів.

Додайте вираз use зверху класу контролера та змініть LuckyController, щоб розширити його:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
// src/Controller/LuckyController.php
namespace App\Controller;

+ use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

- class LuckyController
+ class LuckyController extends AbstractController
{
    // ...
}

Ось і все! Тепер у вас є доступ до таких методів як $this->render() і багатьом іншим, про які ви дізнаєтеся далі.

Генерування URL

Метод generateUrl() - це просто метод-хелпер, який генерує URL для заданого маршруту:

$url = $this->generateUrl('app_lucky_number', ['max' => 10]);

Перенаправлення

Якщо ви хочете перенаправити користувача на іншу сторінку, використовуйте методи

redirectToRoute() та redirect():

use Symfony\Component\HttpFoundation\RedirectResponse;

// ...
public function index()
{
    // перенаправлення на шлях "homepage"
    return $this->redirectToRoute('homepage');

    // redirectToRoute - скорочення для:
    // повернути новий RedirectResponse($this->generateUrl('homepage'));

    // робить постійне 301 перенаправлення
    return $this->redirectToRoute('homepage', [], 301);

    // перенаправлення на шлях з параметрами
    return $this->redirectToRoute('app_lucky_number', ['max' => 10]);

    // перенаправлення на шлях та збереження оригінальних параметрів запиту
    return $this->redirectToRoute('blog_show', $request->query->all());

    // перенаправлення на зовнішній сайт
    return $this->redirect('http://symfony.com/doc');
}

Caution

Метод redirect() ніяк не перевіряє місце призначення. Якщо ви перенаправляєте по URL, наданому кінцевими користувачами, ваш додаток може бути відкритий до вразливості безпеки невалідованих перенаправлень.

Відображення шаблонів

Якщо ви видаєте HTML, вам знадобиться уміння відображати шаблони. Метод render() відображає шабло та розміщує його зміст в об’єкті Response для вас:

// відорбажає templates/lucky/number.html.twig
return $this->render('lucky/number.html.twig', ['number' => $number]);

Шаблонізування та Twig пояснені детальніше в статті Створення та використання шаблонів.

Отримання сервісів

Symfony за замовчуванням наповнена великою кількістю корисних об’єктів, які називаються сервісами. Вони використовуються для відобрадення шаблонів, відправки пошти, запитів до бази даних та будь-якої іншої “роботи”, яку ви можете собі уявити.

Якщо вам потрібен сервіс в контролері, вкажіть клас або інтерфейс аргументу. Symfony автоматично передасть вам необхідний сервіс:

use Psr\Log\LoggerInterface;
use Symfony\Component\HttpFoundation\Response;
// ...

/**
 * @Route("/lucky/number/{max}")
 */
public function number(int $max, LoggerInterface $logger): Response
{
    $logger->info('We are logging!');
    // ...
}

Чудово!

Які ще сервіси можна підключити за допомогою вказання типу? Щоб побачити їх, запустить консольну команду debug:autowiring:

1
$ php bin/console debug:autowiring

Якщо вам необхідний контроль над точним значенням аргументу, ви можете зв’язати аргумент з його іменем:

  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    # config/services.yaml
    services:
        # ...
    
        # ясно сконфігуруйте сервіс
        App\Controller\LuckyController:
            tags: [controller.service_arguments]
            bind:
                # для будь-якого аргументу $logger, передайте цей конкретний сервіс
                $logger: '@monolog.logger.doctrine'
                # для будь-якого аргументу $projectDir, передайте це значення параметру
                $projectDir: '%kernel.project_dir%'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    <!-- 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">
    
        <services>
            <!-- ... -->
    
            <!-- Explicitly configure the service -->
            <service id="App\Controller\LuckyController">
                <tag name="controller.service_arguments"/>
                <bind key="$logger"
                    type="service"
                    id="monolog.logger.doctrine"
                />
                <bind key="$projectDir">%kernel.project_dir%</bind>
            </service>
        </services>
    </container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    // config/services.php
    use App\Controller\LuckyController;
    use Symfony\Component\DependencyInjection\Reference;
    
    $container->register(LuckyController::class)
        ->addTag('controller.service_arguments')
        ->setBindings([
            '$logger' => new Reference('monolog.logger.doctrine'),
            '$projectDir' => '%kernel.project_dir%'
        ])
    ;
    

Як і з усіма сервісами, ви можете використовувати звичайне впровадження через конструктор у ваших контролерах.

Щоб дізнатися більше про сервіси, див. статтю Service Container.

Генерування контролерів

Для економії часу, ви можете встановити Symfony Maker і сказати Symfony згенерувати новий клас контролера:

1
2
3
4
$ php bin/console make:controller BrandNewController

created: src/Controller/BrandNewController.php
created: templates/brandnew/index.html.twig

Якщо ви хочете згенерувати повний CRUD з прив’язкою до сутності Doctrine , запускайте:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
$ php bin/console make:crud Product

created: src/Controller/ProductController.php
created: src/Form/ProductType.php
created: templates/product/_delete_form.html.twig
created: templates/product/_form.html.twig
created: templates/product/edit.html.twig
created: templates/product/index.html.twig
created: templates/product/new.html.twig
created: templates/product/show.html.twig

New in version 1.2: Команда make:crud з’явилася в MakerBundle 1.2.

Управління помилками та сторінками 404

Коли щось не знайдено, ви повинні повернути відповідь 404. Щоб зробити це, викличте спецільний тип виключення:

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

// ...
public function index(): Response
{
    // добути об'єкт з бази даних
    $product = ...;
    if (!$product) {
        throw $this->createNotFoundException('The product does not exist');

        // написане вище - просто скорочення для:
        // викликати новий NotFoundHttpException('Продукт не существует');
    }

    return $this->render(...);
}

Метод createNotFoundException() - це лише скорочення для створення спеціального об’єкту NotFoundHttpException, який в кінцевому рахунку запускає відповідь 404 всередині Symfony.

Якщо ви викличете виключення, що розширює HttpException, Symfony буде використовувати відповідний статус-код HTTP. Інакше відповідь буде видавати статус-код HTTP 500:

// це виключення згенерує помилку з HTTP 500
throw new \Exception('Щось пішло не так!');

В обох випадках, кінцевому користувачу відображається сторінка помилки, а розробнику - повна сторінка налагодження помилки (наприклад, коли ви в режимі “налагодження” - див. Окружения конфигурации).

Для налаштування сторінки помилки, що відображається користувачу, див. статтю How to Customize Error Pages.

Об’єкт Request в якості аргументу контролера

Що ви будете робити, якщо вам знадобиться дізнатися параметри запиту, заголовок запиту або отримати доступ до завантаженого файлу? Вся ця інформація в Symfony міститься в об’єкті Request. Щоб отримати доступ до цієї інформації в контролері, просто додайте його в якості аргументу та додайте тип Request:

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
// ...

public function index(Request $request, string $firstName, string $lastName): Response
{
    $page = $request->query->get('page', 1);

    // ...
}

Продовжуйте читати для детальнішої інформації про використання об’єкту Запит.

Управління сесіями

Symfony надає сервіс сесії, який ви можете використовувати для зберігання інформації про користувача між запитами. Сесії увімкнені за замовчуваннями, але запустяться лише тоді, коли ви почнете читати або записувати в них.

Зберігання сесії та іншу конфігурацію можна контролювати в конфігурації framework.session в config/packages/framework.yaml.

Для отримання доступу до сесії, додайте аргумент та позначте його тип як SessionInterface:

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\SessionInterface;
// ...

public function index(SessionInterface $session): Response
{
    // зберігає атрибут для повторного використання пізніше в запиті користувача
    $session->set('foo', 'bar');

    // отримує атрибут, встановлений іншим контролером в іншому запиті
    $foobar = $session->get('foobar');

    // використовує значення за замовчуванням, якщо атрибут не існує
    $filters = $session->get('filters', []);

    // ...
}

Збережені атрибути зберігатимуться в сесії до завершення сесії користувача.

Щоб дізнатися більше, див. Sessions.

Флеш-повідомлення

Ви можете також зберігати спеціальні повідомлення, які називають флеш-повідомленнями, в користувацькій сесії. Згідно з задумкою, флеш-повідомелення передбачаються для використання лише одного разу: вони автоматично зникають з сесії, як тільки ви їх повертаєте. Ця особливість робить флеш-повідомлення особливо зручними для зберігання користувацьких сповіщень.

Для прикладу уявіть, що ви обробляєте відправку форми:

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
// ...

public function update(Request $request): Response
{
    // ...

    if ($form->isSubmitted() && $form->isValid()) {
        // проведіть якусь обробку

        $this->addFlash(
            'notice',
            'Ваші зміни збережені!'
        );
        // $this->addFlash() еквівалентно $request->getSession()->getFlashBag()->add()

        return $this->redirectToRoute(...);
    }

    return $this->render(...);
}

Після обробки запиту, контролер встановлює флеш-повідомлення в сесії, а потім виконує перенаправлення. Ключ до повідомлення (notice в цьому прикладі) може бути будь-яким: ви будете використовувати його для того, щоб отримати доступ до самого повідомлення.

В шаблоні наступної сторінки (або ще краще, в вашому базовому шаблоні), прочитайте будь-яке флеш-повідомлення з сесії, використовуючи метод flashes(), наданий глобальною змінною app в Twig:

 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
{# templates/base.html.twig #}

{# прочитати та відобразити лише один тип флеш-повідомлення #}
{% for message in app.flashes('notice') %}
    <div class="flash-notice">
        {{ message }}
    </div>
{% endfor %}

{# прочитати та відобразити декілька типів флеш-повідомлень #}
{% for label, messages in app.flashes(['success', 'warning']) %}
    {% for message in messages %}
        <div class="flash-{{ label }}">
            {{ message }}
        </div>
    {% endfor %}
{% endfor %}

{# прочитати та відобразити всі флеш-повідомлення #}
{% for label, messages in app.flashes %}
    {% for message in messages %}
        <div class="flash-{{ label }}">
            {{ message }}
        </div>
    {% endfor %}
{% endfor %}

Зазвичай використовують notice, warning та error в якості ключів для різних типів флеш-повідомлень, але ви можете використовувати будь-який ключ, який вам підходить.

Tip

В якості альтернативи ви можете використовувати метод peek(), щоб отримати повідомлення, не видаляючи його.

Об’єкти Request і Response

Как згадувалося раніше, Symfony передасть об’єкт Request будь-якому аргументу контролера, який буде типізовано по класу Request:

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

public function index(Request $request): Response
{
    $request->isXmlHttpRequest(); // це запит Ajax?

    $request->getPreferredLanguage(['en', 'fr']);

    // добуває змінні GET та POST віпдовідно
    $request->query->get('page');
    $request->request->get('page');

    // добуває змінні глобальної змінної SERVER
    $request->server->get('HTTP_HOST');

    // добуває об'єкт UploadedFile по ключу foo
    $request->files->get('foo');

    // добуває значення COOKIE
    $request->cookies->get('PHPSESSID');

    // добуває заголовок запиту HTTP з нормалізованими ключами малими літерами
    $request->headers->get('host');
    $request->headers->get('content-type');
}

У класа Request є декілька загальнодоступних властивостей та методів, які повертають будь-яку потрібну вам інформацію про запит.

Як і у Request, у об’єкту Response також є публічна властивість headers. Це об’єкт класу ResponseHeaderBag, який містить методи для читання та зміни заголовків відповідей. Імена заголовків нормалізовані. Таким чином, Content-Type еквівалениний іменам content-type і навіть content_type.

Єдине, що вимагається від контролера, - це повертати об’єкт Response:

use Symfony\Component\HttpFoundation\Response;

// створює простий Response зі статус-кодом 200 (за замовчуванням)
$response = new Response('Hello '.$name, Response::HTTP_OK);

// створює CSS-відповідь зі статус-кодом 200
$response = new Response('<style> ... </style>');
$response->headers->set('Content-Type', 'text/css');

Існують спеціальні класи, які полегшують деякі види відповідей. Деякі з них описані нижче. Щоб дізнатися більше про Request та Response (і спеціальні класи Response), див. документацію компоненту HttpFoundation.

Доступ до параметрів конфігурації

Для отримання значень будь-яких параметрів конфігурації з контролера, використовуйте метод getParameter():

// ...
public function index(): Response
{
    $contentsDir = $this->getParameter('kernel.project_dir').'/contents';
    // ...
}

Повернення JSON-відповіді

Щоб повернути JSON з контролера, використовуйте метод json(). Він повертає спеціальний об’єкт JsonResponse, який автоматично перетворює дані в json:

use Symfony\Component\HttpFoundation\Response;
// ...

public function index(): Response
{
    // повертає '{"username":"jane.doe"}' та встановлює правильний заголовок Content-Type
    return $this->json(['username' => 'jane.doe']);

    // скорочення визначає три необов'язкових аргументи
    // return $this->json($data, $status = 200, $headers = [], $context = []);
}

Якщо у вашому додатку включено сервіс серіалізації, то він буде використаний для серіалізації даних в JSON. В іншому випадку буде використано функцію json_encode.

Потокова передача файлів відопвідей

Ви можете використовувати метод file(), щоб видавати файл з контролера:

use Symfony\Component\HttpFoundation\Response;
// ...

public function download(): Response
{
    // відправити зміст файлу та змусити браузер завантажити його
    return $this->file('/path/to/some_file.pdf');
}

Метод file() надає деякі аргументи, щоб сконфігурувати його поведінку:

use Symfony\Component\HttpFoundation\File\File;
use Symfony\Component\HttpFoundation\ResponseHeaderBag;
// ...

public function download(): Response
{
    // завантажити файл з файлової системи
    $file = new File('/path/to/some_file.pdf');

    return $this->file($file);

    // перейменувати завантажений файл
    return $this->file($file, 'custom_name.pdf');

    // відобразити зміст файлу в браузері замість завантаження
    return $this->file('invoice_3241.pdf', 'my_invoice.pdf', ResponseHeaderBag::DISPOSITION_INLINE);
}

Висновок

В Symfony контролер - це зазвичай метод класу, який використовується для прийому запитів та видачі об’єкту Response. Якщо зв’язати його з URL, контролер стає доступним і його відповідь можна побачити.

Для допомоги в розробці контролерів, Symfony надає AbstractController. Він може бути використаний для розширення класу контролера, надаючи доступ до часто використованих функцій, таких як render() та redirectToRoute(). AbstractController також надає метод createNotFoundException(), який використовується для повернення відповіді “404. Не знайдено”.

В інших статтях ви дізнаєтеся, як використовувати спеціальні сервіси всередині вашого контролера, що допоможе вам зберігати та отримувати об’єкти з бази даних, обробляти відправлені форми, працювати з кешем тощо.

Продовжуйте!

Далі, дізнайтеся все про Відображення шаблонів за допомогою Twig.

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.