From 1c82b7d106f5f8d0141060162cc31858fbba507e Mon Sep 17 00:00:00 2001 From: Michael Hoffmann Date: Wed, 1 Mar 2017 22:38:56 +0100 Subject: [PATCH 1/4] Clarify how to handle response bodies and add withStringBody docs --- en/controllers/request-response.rst | 97 ++++++++++++++++++----------- 1 file changed, 62 insertions(+), 35 deletions(-) diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index 5d9c0fba7d..7237d176d0 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -540,41 +540,6 @@ ics generated on the fly from a string:: return $response; } -Streaming Resources -------------------- - -You can stream responses from files using diactoros streams:: - - // To stream from a file - use Zend\Diactoros\Stream; - - $stream = new Stream('/path/to/file', 'rb'); - $response = $response->withStream($stream); - -You can also stream responses from a callback using the ``CallbackStream`` this -is useful when you have resources like images, CSV files or PDFs you need to -stream to the client:: - - // Streaming from a callback - use Cake\Http\CallbackStream; - - // Create an image. - $img = imagecreate(100, 100); - // ... - - $stream = new CallbackStream(function () use ($img) { - imagepng($img); - }); - $response = $response->withStream($stream); - - // Prior to 3.4.0 you can use the following to create streaming responses. - $file = fopen('/some/file.png', 'r'); - $this->response->body(function () use ($file) { - rewind($file); - fpassthru($file); - fclose($file); - }); - Callbacks can also return the body as a string:: $path = '/some/file.png'; @@ -611,6 +576,68 @@ You can now use the convenience method :php:meth:`Cake\\Http\\Response::withLocation()` to directly set or get the redirect location header. +Setting the Body +---------------- + +.. php:method:: withBody($body) + +To set the response body, use the `withBody()` method, which is provided by the +:php:class:`Zend\\Diactoros\\MessageTrait`:: + + $response = $response->withBody($stream); + + // Prior to 3.4.0 - Set the body + $this->response->body('My Body'); + +Be sure that `$stream` is a :php:class:`Psr\\Http\\Message\\StreamInterface` object. +See below on how to create a new stream. + +.. php:method:: withStringBody($string) + +In most use cases, it is simpler to set a string as the response body:: + + // Set a string into the body + $response = $response->withStringBody('My Body'); + + //If you want a json response + $response = $response->withType('application/json') + ->withBody(json_encode(['Foo' => 'bar'])); + +.. versionadded:: 3.4.3 + `withStringBody()` was added in 3.4.3 + +You can also stream responses from files using diactoros streams:: + + // To stream from a file + use Zend\Diactoros\Stream; + + $stream = new Stream('/path/to/file', 'rb'); + $response = $response->withBody($stream); + +You can also stream responses from a callback using the ``CallbackStream`` this +is useful when you have resources like images, CSV files or PDFs you need to +stream to the client:: + + // Streaming from a callback + use Cake\Http\CallbackStream; + + // Create an image. + $img = imagecreate(100, 100); + // ... + + $stream = new CallbackStream(function () use ($img) { + imagepng($img); + }); + $response = $response->withBody($stream); + + // Prior to 3.4.0 you can use the following to create streaming responses. + $file = fopen('/some/file.png', 'r'); + $this->response->body(function () use ($file) { + rewind($file); + fpassthru($file); + fclose($file); + }); + Setting the Character Set ------------------------- From 53ba8115301211a565fe1255d4c45f89486d0494 Mon Sep 17 00:00:00 2001 From: Michael Hoffmann Date: Thu, 2 Mar 2017 20:51:41 +0100 Subject: [PATCH 2/4] Improve the body section and fix some mistakes --- en/controllers/request-response.rst | 34 ++++++++++++++--------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index 7237d176d0..20cb077ee9 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -579,34 +579,34 @@ redirect location header. Setting the Body ---------------- -.. php:method:: withBody($body) - -To set the response body, use the `withBody()` method, which is provided by the -:php:class:`Zend\\Diactoros\\MessageTrait`:: - - $response = $response->withBody($stream); - - // Prior to 3.4.0 - Set the body - $this->response->body('My Body'); - -Be sure that `$stream` is a :php:class:`Psr\\Http\\Message\\StreamInterface` object. -See below on how to create a new stream. - .. php:method:: withStringBody($string) -In most use cases, it is simpler to set a string as the response body:: +To set a string as the response body, do the following:: // Set a string into the body $response = $response->withStringBody('My Body'); - //If you want a json response + // If you want a json response $response = $response->withType('application/json') ->withBody(json_encode(['Foo' => 'bar'])); .. versionadded:: 3.4.3 `withStringBody()` was added in 3.4.3 -You can also stream responses from files using diactoros streams:: +.. php:method:: withBody($body) + +To set the response body, use the ``withBody()`` method, which is provided by the +:php:class:`Zend\\Diactoros\\MessageTrait`:: + + $response = $response->withBody($stream); + + // Prior to 3.4.0 - Set the body + $this->response->body('My Body'); + +Be sure that `$stream` is a :php:class:`Psr\\Http\\Message\\StreamInterface` object. +See below on how to create a new stream. + +You can also stream responses from files using :php:class:`Zend\\Diactoros\\Stream` streams:: // To stream from a file use Zend\Diactoros\Stream; @@ -614,7 +614,7 @@ You can also stream responses from files using diactoros streams:: $stream = new Stream('/path/to/file', 'rb'); $response = $response->withBody($stream); -You can also stream responses from a callback using the ``CallbackStream`` this +You can also stream responses from a callback using the ``CallbackStream``. This is useful when you have resources like images, CSV files or PDFs you need to stream to the client:: From aa48dc9cf891fab1be3189c0f25529da02b3469d Mon Sep 17 00:00:00 2001 From: Michael Hoffmann Date: Fri, 3 Mar 2017 00:11:59 +0100 Subject: [PATCH 3/4] Fix wrong method --- en/controllers/request-response.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index 20cb077ee9..3b2fe9226a 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -588,7 +588,7 @@ To set a string as the response body, do the following:: // If you want a json response $response = $response->withType('application/json') - ->withBody(json_encode(['Foo' => 'bar'])); + ->withStringBody(json_encode(['Foo' => 'bar'])); .. versionadded:: 3.4.3 `withStringBody()` was added in 3.4.3 From 8962d79793b95378e5011817f37596e878825f05 Mon Sep 17 00:00:00 2001 From: Michael Hoffmann Date: Fri, 3 Mar 2017 02:24:06 +0100 Subject: [PATCH 4/4] Add backticks --- en/controllers/request-response.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index 3b2fe9226a..86d4f4b525 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -591,7 +591,7 @@ To set a string as the response body, do the following:: ->withStringBody(json_encode(['Foo' => 'bar'])); .. versionadded:: 3.4.3 - `withStringBody()` was added in 3.4.3 +   ``withStringBody()`` was added in 3.4.3 .. php:method:: withBody($body) @@ -603,7 +603,7 @@ To set the response body, use the ``withBody()`` method, which is provided by th // Prior to 3.4.0 - Set the body $this->response->body('My Body'); -Be sure that `$stream` is a :php:class:`Psr\\Http\\Message\\StreamInterface` object. +Be sure that ``$stream`` is a :php:class:`Psr\\Http\\Message\\StreamInterface` object. See below on how to create a new stream. You can also stream responses from files using :php:class:`Zend\\Diactoros\\Stream` streams::