dokuwiki-matrixnotifierwas-plugin – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 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 ```