Symfony2 Internals

.. toctree::

:maxdepth: 2

overview

kernel

.. index::

single: Internals; Kernel

Kernel

:class:`Symfony\\Components\\HttpKernel\\HttpKernel` is the class responsible

for handling client requests. Its main goal is to "convert"

:class:`Symfony\\Components\\HttpFoundation\\Request` objects to

:class:`Symfony\\Components\\HttpFoundation\\Response` ones.

All Symfony2 Kernels implement

:class:`Symfony\\Components\\HttpKernel\\HttpKernelInterface`::

.. index::

single: Internals; Controller Resolver

Controllers

To convert a Request to a Response, the Kernel relies on a "Controller". A

Controller can be any valid PHP callable.

The Kernel delegates the selection of the Controller to execute to an

implementation of

:class:`Symfony\\Components\\HttpKernel\\Controller\\ControllerResolverInterface`::

The

:method:`Symfony\\Components\\HttpKernel\\Controller\\ControllerResolverInterface::getController`

method returns the Controller (a PHP callable) associated with the given

Request. The default implementation

(:class:`Symfony\\Components\\HttpKernel\\Controller\\ControllerResolver`)

looks for a ``_controller`` request attribute that represents the controller

name (a "class::method" string, like

``Bundle\BlogBundle\PostController:indexAction``).

.. tip::

The default implementation uses the

:class:`Symfony\\Bundle\\FrameworkBundle\\RequestListener`

to define the ``_controller`` Request attribute (see below).

The

:method:`Symfony\\Components\\HttpKernel\\Controller\\ControllerResolverInterface::getArguments`

method returns an array of arguments to pass to the Controller callable. The

default implementation automatically resolves the method arguments, based on

the Request attributes.

.. sidebar:: Matching Controller method arguments from Request attributes

For each method argument, Symfony2 tries to get the value of a Request

attribute with the same name. If it is not defined, the argument default

value is used if defined::

.. index::

single: Internals; Request Handling

Handling Requests

The ``handle()`` method takes a Request and *always* returns a Response. To

convert the Request, ``handle()`` relies on the Resolver and an ordered chain

of Event notifications (see the next section for more information about each

Event):

1. Before doing anything else, the ``core.request`` event is notified -- if

one of the listener returns a Response, it jumps to step 8 directly;

2. The Resolver is called to determine the Controller to execute;

3. Listeners of the ``core.controller`` event can now manipulate the

Controller callable the way they want (change it, wrap it, ...);

4. The Kernel checks that the Controller is actually a valid PHP callable;

5. The Resolver is called to determine the arguments to pass to the

Controller;

6. The Kernel calls the Controller;

7. Listeners of the ``core.view`` event can change the Controller return value

(to convert it to a Response for instance);

8. Listeners of the ``core.response`` event can manipulate the Response

(content and headers);

9. The Response is returned.

If an Exception is thrown during processing, the ``core.exception`` is

notified and listeners are given a change to convert the Exception to a

Response. If that works, the ``core.response`` event is notified; if not the

Exception is re-thrown.

If you don't want Exceptions to be caught (for embedded requests for

instance), disable the ``core.exception`` event by passing ``true`` as the

third argument to the ``handle()`` method.

.. index::

single: Internals; Internal Requests

Internal Requests

At any time during the handling of a request (the 'master' one), a sub-request

can be handled (a forwarded or an embedded one). You can pass the request type

to the ``handle()`` method (its second argument):

* ``HttpKernelInterface::MASTER_REQUEST``;

* ``HttpKernelInterface::FORWARDED_REQUEST``;

* ``HttpKernelInterface::EMBEDDED_REQUEST``.

The type is passed to all events and listeners can act accordingly (some

processing must only occurs on the master request).

.. index::

pair: Kernel; Event

Events

All events have a ``request_type`` parameter, which allows listeners to know

the type of the request. For instance, if a listener must only be active for

master requests, add the following code at the beginning of your listener

method::

.. tip::

If you are not yet familiar with the Symfony2 Event Dispatcher, read the

:doc:`dedicated chapter </guides/event/overview>` first.

.. index::

single: Event; core.request

``core.request`` Event

*Type*: ``notifyUntil()``

*Parameters*: ``request_type`` and ``request``

As the event is notified with the ``notifyUntil()`` method, if a listener

returns a Response object, other listeners won't be called.

This event is used by ``FrameworkBundle`` to populate the ``_controller``

Request attribute, via the

:class:`Symfony\\Bundle\\FrameworkBundle\\RequestListener`. RequestListener

uses a :class:`Symfony\\Components\\Routing\\RouterInterface` object to match

the Request and determine the Controller name (stored in the ``_controller``

Request attribute).

.. index::

single: Event; core.controller

``core.controller`` Event

*Type*: ``filter``

*Arguments*: ``request_type`` and ``request``

*Value to filter*: The Controller value

This event is not used by ``FrameworkBundle``.

.. index::

single: Event; core.view

``core.view`` Event

*Type*: ``filter``

*Arguments*: ``request_type`` and ``request``

*Value to filter*: The Controller returned value

This event is not used by ``FrameworkBundle``. It can be used to implement a

view sub-system.

.. index::

single: Event; core.response

``core.response`` Event

*Type*: ``filter``

*Arguments*: ``request_type`` and ``request``

*Value to filter*: The Response instance

``FrameworkBundle`` registers several listeners:

* :class:`Symfony\\Components\\HttpKernel\\Profiler\\ProfilerListener`:

collects data for the current request;

* :class:`Symfony\\Components\\HttpKernel\\Profiler\\WebDebugToolbarListener`:

injects the Web Debug Toolbar;

* :class:`Symfony\\Components\\HttpKernel\\ResponseListener`: fixes the

Response ``Content-Type``;

* :class:`Symfony\\Components\\HttpKernel\\Cache\\EsiListener`: adds a

``Surrogate-Control`` HTTP header when the Response needs to be parsed for

ESI tags.

.. index::

single: Event; core.exception

``core.exception`` Event

*Type*: ``notifyUntil``

*Arguments*: ``request_type``, ``request``, and ``exception``

``FrameworkBundle`` registers a

:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\ExceptionListener` that

forwards the Request to a given Controller (the value of the

``exception_listener.controller`` parameter -- must be in the

``class::method`` notation).

.. _kernel_listener_tag:

Enabling Custom Listeners

To enable a custom listener, add it as a regular service in one of your

configuration, and tag it with ``kernel.listener``:

.. configuration-block::

.. code-block:: yaml

.. code-block:: xml

.. code-block:: php

The Listener must have a ``register()`` method that takes an

``EventDispatcher`` as its argument and registers itself::

.. index::

single: Internals

Internals Overview

Looks like you want to understand how Symfony2 works and how to extend it.

That makes me very happy! This section is an in-depth explanation of the

Symfony2 internals.

.. note::

You only need to read this section if you want to understand how Symfony2

works behind the scene, or if you want to extend Symfony2.

The Symfony2 code is made of several independent layers. Each layer is built

on top of the previous one.

.. tip::

Autoloading is not managed by the framework directly; it's done

independently with the help of the

:class:`Symfony\\Framework\\UniversalClassLoader` class and the

``src/autoload.php`` file. Read the :doc:`dedicated chapter

</guides/tools/autoloader>` for more information.

``HttpFoundation`` Component

The deepest level is the :namespace:`Symfony\\Components\\HttpFoundation`

component. HttpFoundation provides the main objects needed to deal with HTTP.

It is an Object-Oriented abstraction of some native PHP functions and

variables:

* The :class:`Symfony\\Components\\HttpFoundation\\Request` class abstracts

the main PHP global variables like ``$_GET``, ``$_POST``, ``$_COOKIE``,

``$_FILES``, and ``$_SERVER``;

* The :class:`Symfony\\Components\\HttpFoundation\\Response` class abstracts

some PHP functions like ``header()``, ``setcookie()``, and ``echo``;

* The :class:`Symfony\\Components\\HttpFoundation\\Session` and

:class:`Symfony\\Components\\HttpFoundation\\Session\\SessionStorageInterface`

class abstracts session management ``session_*()`` functions.

.. seealso:: Read more about the :doc:`HttpFoundation Component

<http_foundation>`.

``HttpKernel`` Component

On top of HttpFoundation is the :namespace:`Symfony\\Components\\HttpKernel`

component. HttpKernel handles the dynamic part of HTTP; it is a thin wrapper

on top of the Request and Response classes to standardize the way Requests are

handled. It also provides extension points and tools that makes it the ideal

starting point to create a Web framework without too much overhead.

.. seealso:: Read more about the :doc:`HttpKernel Component <kernel>`.

``Framework``

The :namespace:`Symfony\\Framework` adds configurability and extensibility to

the HttpKernel component, thanks to the Dependency Injection component and a

powerful plugin system (bundles).

.. seealso:: Read more about :doc:`Dependency Injection

</guides/dependency_injection/index>` and :doc:`Bundles

</guides/bundles/index>`.

``FrameworkBundle`` Bundle

:namespace:`Symfony\\Bundle\\FrameworkBundle` is the bundle that ties the main

components and libraries together to make a lightweight and fast MVC

framework. It comes with a sensible default configuration and conventions to

ease the learning curve.