Skip to content

Commit

Permalink
feature #3402 Added documentation about new requests formats configur…
Browse files Browse the repository at this point in the history 
…ation (gquemener)

This PR was merged into the master branch.

Discussion
----------

Added documentation about new requests formats configuration

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes (symfony/symfony#9862)
| Applies to    | 2.5
| Fixed tickets | symfony/symfony#8934

Commits
-------

6adf160 Added documentation about new requests formats configuration
  • Loading branch information
@weaverryan
weaverryan committed Mar 18, 2014
2 parents 842fd30 + 6adf160 commit dcf8e6e
Showing 1 changed file with 81 additions and 55 deletions.
136 changes: 81 additions & 55 deletions cookbook/request/mime_type.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,81 +15,107 @@ object. Internally, Symfony contains a map of the most common formats (e.g.
easily be added. This document will show how you can add the ``jsonp`` format
and corresponding MIME type.

Create a ``kernel.request`` Listener
-------------------------------------
.. versionadded:: 2.5
The possibility to configure request formats was introduced in Symfony 2.5.

The key to defining a new MIME type is to create a class that will "listen" to
the ``kernel.request`` event dispatched by the Symfony kernel. The
``kernel.request`` event is dispatched early in Symfony's request handling
process and allows you to modify the request object.

Create the following class, replacing the path with a path to a bundle in your
project::

// src/Acme/DemoBundle/RequestListener.php
namespace Acme\DemoBundle;

use Symfony\Component\HttpKernel\HttpKernelInterface;
use Symfony\Component\HttpKernel\Event\GetResponseEvent;

class RequestListener
{
public function onKernelRequest(GetResponseEvent $event)
{
$event->getRequest()->setFormat('jsonp', 'application/javascript');
}
}

Registering your Listener
Configure your New Format
-------------------------

As with any other listener, you need to add it in one of your configuration
files and register it as a listener by adding the ``kernel.event_listener`` tag:
The FrameworkBundle registers a subscriber that will add formats to incomming requests.

All you have to do is to configure the ``jsonp`` format:

.. configuration-block::

.. code-block:: yaml
# app/config/config.yml
services:
acme.demobundle.listener.request:
class: Acme\DemoBundle\RequestListener
tags:
- { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }
framework:
request:
formats:
jsonp: 'application/javascript'
.. code-block:: xml
<!-- app/config/config.xml -->
<?xml version="1.0" ?>
<?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 http://symfony.com/schema/dic/services/services-1.0.xsd">
<services>
<service id="acme.demobundle.listener.request"
class="Acme\DemoBundle\RequestListener">
<tag name="kernel.event_listener"
event="kernel.request"
method="onKernelRequest"
/>
</service>
</services>
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
>
<framework:config>
<framework:request>
<framework:format name="jsonp">
<framework:mime-type>application/javascript</framework:mime-type>
</framework:format>
</framework:request>
</framework:config>
</container>
.. code-block:: php
# app/config/config.php
$definition = new Definition('Acme\DemoBundle\RequestListener');
$definition->addTag('kernel.event_listener', array(
'event' => 'kernel.request',
'method' => 'onKernelRequest',
// app/config/config.php
$container->loadFromExtension('framework', array(
'request' => array(
'formats' => array(
'jsonp' => 'application/javascript',
),
),
));
$container->setDefinition('acme.demobundle.listener.request', $definition);
At this point, the ``acme.demobundle.listener.request`` service has been
configured and will be notified when the Symfony kernel dispatches the
``kernel.request`` event.
.. tip::

You can also register the listener in a configuration extension class (see
:ref:`service-container-extension-configuration` for more information).
You can also associate multiple mime types to a format, but please note that
the preferred one must be the first as it will be used as the content type:

.. configuration-block::

.. code-block:: yaml
# app/config/config.yml
framework:
request:
formats:
csv: ['text/csv', 'text/plain']
.. code-block:: xml
<!-- app/config/config.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
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
>
<framework:config>
<framework:request>
<framework:format name="csv">
<framework:mime-type>text/csv</framework:mime-type>
<framework:mime-type>text/plain</framework:mime-type>
</framework:format>
</framework:request>
</framework:config>
</container>
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('framework', array(
'request' => array(
'formats' => array(
'jsonp' => array(
'text/csv',
'text/plain',
),
),
),
));

0 comments on commit dcf8e6e

Please sign in to comment.