Компонент HttpFoundation¶

На самом глубоком уровне находится компонент :namespace:`Symfony\\Component\\HttpFoundation`. HttpFoundation предоставляет основные объекты, необходимые для работы с HTTP. Это объектно-ориентированная абстракция некоторых встроенных PHP функций и переменных:

• Класс Symfony\Component\HttpFoundation\Request абстрагирует основные глобальные переменные в PHP, такие как $_GET, $_POST, $_COOKIE, $_FILES и $_SERVER;
• Класс Symfony\Component\HttpFoundation\Response абстрагирует некоторые PHP функции типа header(), setcookie() и echo;
• Класс Symfony\Component\HttpFoundation\Session и Symfony\Component\HttpFoundation\SessionStorage\SessionStorageInterface абстрагируют функции session_*() для управления сессией.

Компонент HttpKernel¶

Поверх HttpFoundation располагается компонент :namespace:`Symfony\\Component\\HttpKernel`. HttpKernel управляет динамической частью HTTP; это тонкая обёртка поверх классов Request и Response, которая приводит способы обработки запросов к стандарту. Компонент также предоставляет точки для расширений и инструменты, делающие его идеальной стартовой площадкой для создания Web фреймворка без лишних проблем.

Также, дополнительно, он добавляет настраиваемость и расширяемость благодаря компоненту Dependency Injection и мощной системе пакетов (Bundles).

Пакет FrameworkBundle¶

:namespace:`Symfony\\Bundle\\FrameworkBundle` это пакет, связывающий основные компоненты и библиотеки вместе, что создаёт лёгкий и быстрый MVC фреймворк. Он поставляется с правильной первоначальной конфигурацией и соглашениями для облегчения изучения.

Контроллеры (Controllers)¶

При преобразования запроса в ответ, Kernel полагается на “Controller”. Контроллер может быть любой валидной PHP-сущностью, которую можно вызвать тем или иным образом.

Ядро делегирует право выбора запустить тот или иной контроллер классу, реализующему интерфейс Symfony\Component\HttpKernel\Controller\ControllerResolverInterface:

public function getController(Request $request);

public function getArguments(Request $request, $controller);

Метод :method:`Symfony\\Component\\HttpKernel\\Controller\\ControllerResolverInterface::getController` возвращает контроллер (PHP callable - функцию, метод, замыкание...), ассоциированный с данным запросом. Каноническая реализация (Symfony\Component\HttpKernel\Controller\ControllerResolver) ищет атрибут запроса _controller, который хранит наименование контроллера (строку “class::method”, например Bundle\BlogBundle\PostController:indexAction).

Метод :method:`Symfony\\Component\\HttpKernel\\Controller\\ControllerResolverInterface::getArguments` возвращает массив аргументов для передачи их в контроллер. Реализация по умолчанию автоматически определяет аргументы, основываясь на атрибутах запроса.

// Symfony2 будет искать обязательный атрибут 'id'
// и опциональный атрибут 'admin'
public function showAction($id, $admin = true)
{
    // ...
}

Обработка запросов¶

Метод handle() принимает Request и всегда возвращает Response. При конвертации объекта Request, handle() полагается на Resolver и упорядоченную цепь нотификаций о событиях (Event notifications, см. следующую секцию для более подробной информации о каждом событии из этой цепи):

1. Перед тем как что-либо делать, срабатывает нотификация о событии kernel.request – если один из слушателей (listeners) возвращает объект Response, процесс сразу переходит к шагу 8;
2. Вызывается Resolver для определения Контроллера, который необходимо выполнить;
3. Слушатели события kernel.controller теперь могут манипулировать методом Контроллера (изменить, обернуть...);
4. Kernel проверяет, что Контроллер представляет собой валидный PHP callable;
5. Для определения аргументов Контроллера вызывается Resolver;
6. Kernel выполняет Контроллер;
7. Если Контроллер не возвращает объект Response, слушатели события kernel.view могут конвертировать данные, которые вернул Контроллер в объект Response;
8. Слушатели события kernel.response могут манипулировать объектом Response ( контент и заголовки);
9. Возвращается Ответ.

Если во время этого процесса возникает исключительная ситуация, срабатывает событие kernel.exception и его слушатели получают возможность конвертировать исключение (Exception) в Ответ. Если это удаётся, событие уведомляется, если нет, исключение вызывается повторно.

Если вы не хотите, чтобы возникали исключения (для вложенных запросов, к примеру), отключите событие kernel.exception передав false в качестве третьего аргумента метода handle().

Внутренние Запросы¶

В любой момент во время обработки запроса (назовём его ‘мастер’), может быть обработан подзапрос. Вы можете передать тип запроса в метод handle() его вторым параметром:

• HttpKernelInterface::MASTER_REQUEST;
• HttpKernelInterface::SUB_REQUEST.

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

События¶

Каждое событие, создаваемое в Kernel, это дочерний класс Symfony\Component\HttpKernel\Event\KernelEvent. Это означает, что каждое событие имеет доступ к одной и той же базовой информации:

• getRequestType() - возвращает тип запроса (HttpKernelInterface::MASTER_REQUEST или HttpKernelInterface::SUB_REQUEST);
• getKernel() - возвращает экземпляр Kernel, обрабатывающий этот запрос;
• getRequest() - возвращает объект Request, соответствующий обрабатываемому запросу;

<?php
use Symfony\Component\HttpKernel\HttpKernelInterface;

if (HttpKernelInterface::MASTER_REQUEST !== $event->getRequestType()) {
    // немедленно возвращаемся
    return;
}

<?php
use Symfony\Component\HttpKernel\Event\FilterControllerEvent;

public function onKernelController(FilterControllerEvent $event)
{
    $controller = $event->getController();
    // ...

    // the controller can be changed to any PHP callable
    $event->setController($controller);
}

<?php
use Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent;
use Symfony\Component\HttpFoundation\Response;

public function onKernelView(GetResponseForControllerResultEvent $event)
{
    $val = $event->getReturnValue();
    $response = new Response();
    // код получения объекта Response из полученного значения

    $event->setResponse($response);
}

<?php
public function onKernelResponse(FilterResponseEvent $event)
{
    $response = $event->getResponse();
    // .. modify the response object
}

<?php
use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
use Symfony\Component\HttpFoundation\Response;

public function onKernelException(GetResponseForExceptionEvent $event)
{
    $exception = $event->getException();
    $response = new Response();
    // Настраиваем объект Response, основываясь на перехваченном исключении
    $event->setResponse($response);

    // как вариант - вы можете создать новое исключение
    // $exception = new \Exception('Some special exception');
    // $event->setException($exception);
}

События¶

Когда сообщение отправлено, оно идентифицируется по уникальному имени (например, kernel.response), которое могут ожидать некоторое число слушателей. Также создаётся экземпляр класса Symfony\Component\EventDispatcher\Event, который затем передаётся всем слушателям. Как вы увидите чуть позже, объект Event часто содержит данные о направляемом событии.

Диспетчер¶

Диспетчер - это центральный объект системы обработки событий. Как правило, создаётся единственный диспетчер, который обслуживает реестр слушателей. Когда событие поступает к диспетчеру - он уведомляет всех слушателей, подписанных на это событие.

<?php
use Symfony\Component\EventDispatcher\EventDispatcher;

$dispatcher = new EventDispatcher();

Подключаем Слушателей¶

Для того, чтобы отреагировать на некое существующее событие, вам необходимо подключить слушателя к диспетчеру, чтобы последний имел возможность сообщить о появлении нужного события. Вызов метода диспетчера addListener() ассоциирует любую исполнимую функцию/метод с событием:

<?php
$listener = new AcmeListener();
$dispatcher->addListener('foo.action', array($listener, 'onFooAction'));

Метод addListener() получает три аргумента:

• Наименование события, которое слушатель будет ожидать;
• Некий объект (функцию, в общем же случае PHP callable), который будет вызван при наступлении события;
• Опциональный приоритет (чем больше - тем более важный), который определяет очерёдность вызова слушателей (по умолчанию 0). Если два слушателя имеют одинаковый приоритет, они выполняются в порядке их добавления.

<?php
use Symfony\Component\EventDispatcher\Event;

$dispatcher->addListener('foo.action', function (Event $event) {
    // этот код будет вызван при обработке события foo.action
});

Когда слушатель зарегистрирован диспетчером, он ожидает наступления события. В примере выше, когда появляется событие foo.action, диспетчер вызывает метод AcmeListener::onFooAction и передаёт объекту Event один аргумент:

<?php
use Symfony\Component\EventDispatcher\Event;

class AcmeListener
{
    // ...

    public function onFooAction(Event $event)
    {
        // do something
    }
}

Во многих случаях, слушателю передаётся специализированный дочерний класс Event. Это даёт слушателю доступ к информации о событии. Сверяйтесь с документацией или реализацией каждого конкретного события для определения какой именно экземпляр Symfony\Component\EventDispatcher\Event будет передан. Например, событие kernel.event передаёт экземпляр класса Symfony\Component\HttpKernel\Event\FilterResponseEvent:

<?php
use Symfony\Component\HttpKernel\Event\FilterResponseEvent

public function onKernelResponse(FilterResponseEvent $event)
{
    $response = $event->getResponse();
    $request = $event->getRequest();

    // ...
}

Создание и обработка события¶

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

<?php
namespace Acme\StoreBundle;

final class StoreEvents
{
    /**
     * Событие store.order создаётся всякий раз, когда в системе создаётся заказ.
     *
     * Слушатель получит экземпляр Acme\StoreBundle\Event\FilterOrderEvent
     *
     * @var string
     */
    const onStoreOrder = 'store.order';
}

<?php
namespace Acme\StoreBundle\Event;

use Symfony\Component\EventDispatcher\Event;
use Acme\StoreBundle\Order;

class FilterOrderEvent extends Event
{
    protected $order;

    public function __construct(Order $order)
    {
        $this->order = $order;
    }

    public function getOrder()
    {
        return $this->order;
    }
}

<?php
use Acme\StoreBundle\StoreEvents;
use Acme\StoreBundle\Order;
use Acme\StoreBundle\Event\FilterOrderEvent;

// заказ как-то создаётся или получается
$order = new Order();
// ...

// создаём FilterOrderEvent и его отправка
$event = new FilterOrderEvent($order);
$dispatcher->dispatch(StoreEvents::onStoreOrder, $event);

<?php
// какой-то слушатель, подписанный на событие store.order методом onStoreOrder
use Acme\StoreBundle\Event\FilterOrderEvent;

public function onStoreOrder(FilterOrderEvent $event)
{
    $order = $event->getOrder();
    // далее выполняются какие-то действия с заказом
}

Внутри объекта Диспетчера событий¶

Если вы взглянете на класс EventDispatcher, вы увидите, что этот класс работает не как Singleton (нет статического метода getInstance()). Это сделано преднамеренно, так как вам, возможно, потребуется иметь несколько конкурирующих диспетчеров в рамках одного запроса. Но это также означает, что вам нужен способ для передачи диспетчеру объектов, которые нужно подключить или которые надо уведомить о событии.

Общепринятой практикой является внедрение объекта диспетчера в ваши объекты, т.е. внедрение зависимости.

Вы можете использовать внедрение в конструктор:

class Foo
{
    protected $dispatcher = null;

    public function __construct(EventDispatcher $dispatcher)
    {
        $this->dispatcher = $dispatcher;
    }
}

Или же внедрение через метод (setter injection):

class Foo
{
    protected $dispatcher = null;

    public function setEventDispatcher(EventDispatcher $dispatcher)
    {
        $this->dispatcher = $dispatcher;
    }
}

Выбор того или иного метода - это дело вкуса. Многие предпочитают метод с конструктором, так как объекты полностью инициализируются во время создания. Но когда у вас имеется длинный список зависимостей, использовать метод-сеттер это тоже вариант, особенно для опциональных зависимостей.

Подписка на события¶

Типичный способ ожидать возникновение события - зарегистрировать слушателя события при помощи диспетчера. Этот слушатель может слушать одно или несколько событий и уведомляется каждый раз при отправке нужного события.

Альтернативным способом для ожидания событий - использование подписчика события. Подписчик - это PHP класс, который имеет возможность сообщить диспетчеру на какие события он подписывается. Подписчик должен реализовывать интерфейс Symfony\Component\EventDispatcher\EventSubscriberInterface, который требует наличие одного статического метода getSubscribedEvents. Рассмотрим пример подписчика, который подписывается на события kernel.response и store.order:

<?php
namespace Acme\StoreBundle\Event;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\FilterResponseEvent;

class StoreSubscriber implements EventSubscriberInterface
{
    static public function getSubscribedEvents()
    {
        return array(
            'kernel.response' => 'onKernelResponse',
            'store.order'     => 'onStoreOrder',
        );
    }

    public function onKernelResponse(FilterResponseEvent $event)
    {
        // ...
    }

    public function onStoreOrder(FilterOrderEvent $event)
    {
        // ...
    }
}

Этот класс похож на класс слушателя, за исключением того, что он сам может сообщить диспетчеру, на какие именно события он подписывается (будет слушать). Для регистрации подписчика в диспетчере необходимо использовать метод :method:`Symfony\\Component\\EventDispatcher\\EventDispatcher::addSubscriber`:

<?php
use Acme\StoreBundle\Event\StoreSubscriber;

$subscriber = new StoreSubscriber();
$dispatcher->addSubscriber($subscriber);

Диспетчер автоматически зарегистрирует подписчика для каждого события, возвращаемого методом getSubscribedEvents. Этот метод возвращает массив, индексами которого служат наименования событий, а значениями служат либо наименования методов, которые будут вызваны, либо массивы с именем метода и его приоритетом при обработке события.

Прекращение обработки событий¶

В некоторых случаях, один из слушателей может затребовать прекращение обработки события другими слушателями. Другими словами, слушатель должен иметь возможность сообщить диспетчеру, что он должен остановить обработку события всеми оставшимися слушателями (не уведомлять их о событии). Этого можно достигнуть внутри слушателя при помощи метода :method:`Symfony\\Component\\EventDispatcher\\Event::stopPropagation`:

<?php
use Acme\StoreBundle\Event\FilterOrderEvent;

public function onStoreOrder(FilterOrderEvent $event)
{
    // ...

    $event->stopPropagation();
}

Теперь, все слушатели store.order, которые ещё не были уведомлены о событии, уведомляться уже не будут.

Визуализация данных профайлера¶

$profile = $container->get('profiler')->loadProfileFromResponse($response);

$profile = $container->get('profiler')->loadProfile($token);

// получить 10 последних токенов
$tokens = $container->get('profiler')->find('', '', 10);

// получить последние 10 токенов для всех URL, содержащих /admin/
$tokens = $container->get('profiler')->find('', '/admin/', 10);

// получить последние 10 токенов для локальных запросов
$tokens = $container->get('profiler')->find('127.0.0.1', '', 10);

// в prod окружении
$profile = $container->get('profiler')->loadProfile($token);
$data = $profiler->export($profile);

// в dev окружении
$profiler->import($data);