diff --git a/cookbook/index.rst b/cookbook/index.rst index 63f5dc08898..681d6dbe4c9 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -27,6 +27,7 @@ The Cookbook serializer service_container/index session/index + psr7 symfony1 templating/index testing/index diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 4316f0de726..abbf7eface6 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -195,6 +195,10 @@ * (configuration) :doc:`/cookbook/configuration/pdo_session_storage` * :doc:`/cookbook/session/avoid_session_start` +* **PSR-7** + + * :doc:`/cookbook/psr7` + * **symfony1** * :doc:`/cookbook/symfony1` diff --git a/cookbook/psr7.rst b/cookbook/psr7.rst new file mode 100644 index 00000000000..ece2040850b --- /dev/null +++ b/cookbook/psr7.rst @@ -0,0 +1,88 @@ +.. index:: + single: PSR-7 + +The PSR-7 Bridge +================ + + The PSR-7 bridge converts :doc:`HttpFoundation ` + objects from and to objects implementing HTTP message interfaces defined + by the `PSR-7`_. + +Installation +------------ + +You can install the component in 2 different ways: + +* :doc:`Install it via Composer ` (``symfony/psr-http-message-bridge`` on `Packagist`_); +* Use the official Git repository (https://github.com/symfony/psr-http-message-bridge). + +The bridge also needs a PSR-7 implementation to allow converting HttpFoundation +objects to PSR-7 objects. It provides native support for _`Zend Diactoros`_. +Use Composer (``zendframework/zend-diactoros`` on `Packagist`_) or refers to +the project documentation to install it. + +Usage +----- + +Converting from HttpFoundation Objects to PSR-7 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The bridge provides an interface of a factory called +:class:`Symfony\\Bridge\\PsrHttpMessage\\HttpMessageFactoryInterface` +that builds objects implementing PSR-7 interfaces from HttpFoundation objects. +It also provide a default implementation using Zend Diactoros internally. + +The following code snippet explain how to convert a :class:`Symfony\\Component\\HttpFoundation\\Request` +to a Zend Diactoros :class:`Zend\\Diactoros\\ServerRequest` implementing the +:class:`Psr\\Http\\Message\\ServerRequestInterface` interface:: + + use Symfony\Bridge\PsrHttpMessage\Factory\DiactorosFactory; + use Symfony\Component\HttpFoundation\Request; + + $symfonyRequest = new Request(array(), array(), array(), array(), array(), array('HTTP_HOST' => 'dunglas.fr'), 'Content'); + // The HTTP_HOST server key must be set to avoid an unexpected error + + $psr7Factory = new DiactorosFactory(); + $psrRequest = $psr7Factory->createRequest($symfonyRequest); + +And now from a :class:`Symfony\\Component\\HttpFoundation\\Response` to a Zend +Diactoros :class:`Zend\\Diactoros\\Response` implementing the :class:`Psr\\Http\\Message\\ResponseInterface` +interface:: + + use Symfony\Bridge\PsrHttpMessage\Factory\DiactorosFactory; + use Symfony\Component\HttpFoundation\Response; + + $symfonyResponse = new Response('Content'); + + $psr7Factory = new DiactorosFactory(); + $psrResponse = $psr7Factory->createResponse($symfonyResponse); + +Converting Objects implementing PSR-7 Interfaces to HttpFoundation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On the other hand, the bridge provide a factory interface called +:class:`Symfony\\Bridge\\PsrHttpMessage\\HttpFoundationFactoryInterface` +that builds HttpFoundation objects from objects implementing PSR-7 interfaces. + +The next snippet explain how to convert an object implementing the :class:`Psr\\Http\\Message\\ServerRequestInterface` +interface to a :class:`Symfony\\Component\\HttpFoundation\\Request` instance:: + + use Symfony\Bridge\PsrHttpMessage\Factory\HttpFoundationFactory; + + // $psrRequest is an instance of Psr\Http\Message\ServerRequestInterface + + $httpFoundationFactory = new HttpFoundationFactory(); + $symfonyRequest = $httpFoundationFactory->createRequest($psrRequest); + +From an object implementing the :class:`Psr\\Http\\Message\\ResponseInterface` +to a :class:`Symfony\\Component\\HttpFoundation\\Response` instance:: + + use Symfony\Bridge\PsrHttpMessage\Factory\HttpFoundationFactory; + + // $psrResponse is an instance of Psr\Http\Message\ResponseInterface + + $httpFoundationFactory = new HttpFoundationFactory(); + $symfonyResponse = $httpFoundationFactory->createResponse($psrResponse); + +.. _`PSR-7`: http://www.php-fig.org/psr/psr-7/ +.. _Packagist: https://packagist.org/packages/symfony/psr-http-message-bridge