[Summary view] [Print] [Text view]

   1  ### PSR-7 Usage
   2  
   3  All PSR-7 applications comply with these interfaces 
   4  They were created to establish a standard between middleware implementations.
   5  
   6  > `RequestInterface`, `ServerRequestInterface`, `ResponseInterface` extend `MessageInterface`  because the `Request` and the `Response` are `HTTP Messages`.
   7  > When using `ServerRequestInterface`, both `RequestInterface` and `Psr\Http\Message\MessageInterface` methods are considered.
   8  
   9  
  10  The following examples will illustrate how basic operations are done in PSR-7.
  11  
  12  ##### Examples
  13  
  14  
  15  For this examples to work (at least) a PSR-7 implementation package is required. (eg: zendframework/zend-diactoros, guzzlehttp/psr7, slim/slim, etc)
  16  All PSR-7 implementations should have the same behaviour.
  17  
  18  The following will be assumed: 
  19  `$request` is an object of `Psr\Http\Message\RequestInterface` and
  20  
  21  `$response` is an object implementing `Psr\Http\Message\RequestInterface`
  22  
  23  
  24  ### Working with HTTP Headers
  25  
  26  #### Adding headers to response:
  27  
  28  ```php
  29  $response->withHeader('My-Custom-Header', 'My Custom Message');
  30  ```
  31  
  32  #### Appending values to headers
  33  
  34  ```php
  35  $response->withAddedHeader('My-Custom-Header', 'The second message');
  36  ```
  37  
  38  #### Checking if header exists:
  39  
  40  ```php
  41  $request->hasHeader('My-Custom-Header'); // will return false
  42  $response->hasHeader('My-Custom-Header'); // will return true
  43  ```
  44  
  45  > Note: My-Custom-Header was only added in the Response
  46  
  47  #### Getting comma-separated values from a header (also applies to request)
  48  
  49  ```php
  50  // getting value from request headers
  51  $request->getHeaderLine('Content-Type'); // will return: "text/html; charset=UTF-8"
  52  // getting value from response headers
  53  $response->getHeaderLine('My-Custom-Header'); // will return:  "My Custom Message; The second message"
  54  ```
  55  
  56  #### Getting array of value from a header (also applies to request)
  57  ```php
  58  // getting value from request headers
  59  $request->getHeader('Content-Type'); // will return: ["text/html", "charset=UTF-8"]
  60  // getting value from response headers
  61  $response->getHeader('My-Custom-Header'); // will return:  ["My Custom Message",  "The second message"]
  62  ```
  63  
  64  #### Removing headers from HTTP Messages
  65  ```php
  66  // removing a header from Request, removing deprecated "Content-MD5" header
  67  $request->withoutHeader('Content-MD5'); 
  68  
  69  // removing a header from Response
  70  // effect: the browser won't know the size of the stream
  71  // the browser will download the stream till it ends
  72  $response->withoutHeader('Content-Length');
  73  ```
  74  
  75  ### Working with HTTP Message Body
  76  
  77  When working with the PSR-7 there are two methods of implementation:
  78  #### 1. Getting the body separately
  79  
  80  > This method makes the body handling easier to understand and is useful when repeatedly calling body methods. (You only call `getBody()` once). Using this method mistakes like `$response->write()` are also prevented.
  81  
  82  ```php
  83  $body = $response->getBody();
  84  // operations on body, eg. read, write, seek
  85  // ...
  86  // replacing the old body
  87  $response->withBody($body); 
  88  // this last statement is optional as we working with objects
  89  // in this case the "new" body is same with the "old" one
  90  // the $body variable has the same value as the one in $request, only the reference is passed
  91  ```
  92  
  93  #### 2. Working directly on response
  94  
  95  > This method is useful when only performing few operations as the `$request->getBody()` statement fragment is required
  96  
  97  ```php
  98  $response->getBody()->write('hello');
  99  ```
 100  
 101  ### Getting the body contents
 102  
 103  The following snippet gets the contents of a stream contents.
 104  > Note: Streams must be rewinded, if content was written into streams, it will be ignored when calling `getContents()` because the stream pointer is set to the last character, which is `\0` - meaning end of stream.
 105  ```php 
 106  $body = $response->getBody();
 107  $body->rewind(); // or $body->seek(0);
 108  $bodyText = $body->getContents();
 109  ```
 110  > Note: If `$body->seek(1)` is called before `$body->getContents()`, the first character will be ommited as the starting pointer is set to `1`, not `0`. This is why using `$body->rewind()` is recommended.
 111  
 112  ### Append to body
 113  
 114  ```php
 115  $response->getBody()->write('Hello'); // writing directly
 116  $body = $request->getBody(); // which is a `StreamInterface`
 117  $body->write('xxxxx');
 118  ```
 119  
 120  ### Prepend to body
 121  Prepending is different when it comes to streams. The content must be copied before writing the content to be prepended.
 122  The following example will explain the behaviour of streams.
 123  
 124  ```php
 125  // assuming our response is initially empty
 126  $body = $repsonse->getBody();
 127  // writing the string "abcd"
 128  $body->write('abcd');
 129  
 130  // seeking to start of stream
 131  $body->seek(0);
 132  // writing 'ef'
 133  $body->write('ef'); // at this point the stream contains "efcd"
 134  ```
 135  
 136  #### Prepending by rewriting separately
 137  
 138  ```php
 139  // assuming our response body stream only contains: "abcd"
 140  $body = $response->getBody();
 141  $body->rewind();
 142  $contents = $body->getContents(); // abcd
 143  // seeking the stream to beginning
 144  $body->rewind();
 145  $body->write('ef'); // stream contains "efcd"
 146  $body->write($contents); // stream contains "efabcd"
 147  ```
 148  
 149  > Note: `getContents()` seeks the stream while reading it, therefore if the second `rewind()` method call was not present the stream would have resulted in `abcdefabcd` because the `write()` method appends to stream if not preceeded by `rewind()` or `seek(0)`.
 150  
 151  #### Prepending by using contents as a string
 152  ```php
 153  $body = $response->getBody();
 154  $body->rewind();
 155  $contents = $body->getContents(); // efabcd
 156  $contents = 'ef'.$contents;
 157  $body->rewind();
 158  $body->write($contents);
 159  ```