Skip to content

Commit b844641

Browse files
akrabatakrabat
committed
Merge branch 'Update-Readme'
Closes #68
2 parents 3bc969a + 0e52691 commit b844641

File tree

1 file changed

+245
-11
lines changed

1 file changed

+245
-11
lines changed

‎README.md

+245-11
Original file line numberDiff line numberDiff line change
@@ -13,41 +13,275 @@ It's recommended that you use [Composer](https://getcomposer.org/) to install
1313
this library.
1414

1515
```bash
16-
$ composer require slim/http "^0.1"
16+
$ composer require slim/http "^0.5"
1717
```
1818

1919
This will install the `slim/http` component and all required dependencies.
2020
PHP 7.1, or newer, is required.
2121

22-
## Usage
23-
24-
Coming soon.
25-
2622
## Tests
2723

28-
To execute the test suite, you'll need phpunit.
24+
To execute the test suite, you'll need to install all development dependencies.
2925

3026
```bash
31-
$ phpunit
27+
$ git clone https://github.com/slimphp/Slim-Http
28+
$ composer install
29+
$ composer test
3230
```
3331

34-
## Contributing
3532

33+
## Usage
34+
35+
The Decoration Repo Provides 3 Factories which instantiate the Decorators. They respectively return PSR-7 Compatible Interfaces.
36+
- `DecoratedResponseFactory`
37+
- `DecoratedServerRequestFactory`
38+
- `DecoratedUriFactory`
39+
40+
## Example for Instantiating a Decorated Nyholm/Psr7 Response
41+
```php
42+
<?php
43+
44+
use Nyholm\Psr7\Factory\Psr17Factory;
45+
use Slim\Http\Factory\DecoratedResponseFactory;
46+
47+
$nyholmFactory = new Psr17Factory();
48+
49+
/**
50+
* DecoratedResponseFactory takes 2 parameters
51+
* @param \Psr\Http\Message\ResponseFactoryInterface which should be a ResponseFactory originating from the PSR-7 Implementation of your choice
52+
* @param \Psr\Http\Message\StreamFactoryInterface which should be a StreamFactory originating from the PSR-7 Implementation of your choice
53+
* Note: Nyholm/Psr17 has one factory which implements Both ResponseFactoryInterface and StreamFactoryInterface see https://github.com/Nyholm/psr7/blob/master/src/Factory/Psr17Factory.php
54+
*/
55+
$decoratedResponseFactory = new DecoratedResponseFactory($nyholmFactory, $nyholmFactory);
56+
57+
/**
58+
* @var \Slim\Http\Decorators\ResponseDecorator $response
59+
* The returned variable is a ResponseDecorator which has methods like withJson()
60+
*/
61+
$response = $decoratedResponseFactory->createResponse(200, 'OK');
62+
$response = $response->withJson(['data' => [1, 2, 3]]);
63+
64+
```
65+
66+
67+
## Example for Instantiating a Decorated Zend Diactoros Response
68+
```php
69+
<?php
70+
71+
use Zend\Diactoros\ResponseFactory;
72+
use Zend\Diactoros\StreamFactory;
73+
use Slim\Http\Factory\DecoratedResponseFactory;
74+
75+
$responseFactory = new ResponseFactory();
76+
$streamFactory = new StreamFactory();
77+
78+
/**
79+
* DecoratedResponseFactory takes 2 parameters
80+
* @param \Psr\Http\Message\ResponseFactoryInterface which should be a ResponseFactory originating from the PSR-7 Implementation of your choice
81+
* @param \Psr\Http\Message\StreamFactoryInterface which should be a StreamFactory originating from the PSR-7 Implementation of your choice
82+
*/
83+
$decoratedResponseFactory = new DecoratedResponseFactory($responseFactory, $streamFactory);
84+
85+
/**
86+
* @var \Slim\Http\Decorators\ResponseDecorator $response
87+
* The returned variable is a ResponseDecorator which has methods like withJson()
88+
*/
89+
$response = $decoratedResponseFactory->createResponse(200, 'OK');
90+
$response = $response->withJson(['data' => [1, 2, 3]]);
91+
92+
```
93+
94+
95+
## Decoratored Response Object Methods
96+
The decorated `ResponseInterface` provides the following additional methods:
97+
98+
#### `ResponseDecorator::withJson($data, $status, $options, $depth)` ####
99+
| Parameter | Type | Description |
100+
|-------------|---------|-------------------------|
101+
| **$data** | `mixed` | The data to encode |
102+
| **$status** | `int` | The HTTP Status Code |
103+
| **$depth** | `int` | JSON encoding max depth |
104+
105+
#### `ResponseDecorator::withRedirect($url, $status)` ####
106+
| Parameter | Type | Description |
107+
|-------------|----------|------------------------------|
108+
| **$url** | `string` | The redirect destination url |
109+
| **$status** | `int` | The HTTP Status Code |
110+
111+
#### `ResponseDecorator::write($data)` ####
112+
| Parameter | Type | Description |
113+
|-----------|----------|------------------------------------------|
114+
| **$url** | `string` | The data to write to the `Response` body |
115+
116+
#### `ResponseDecorator::isClientError()` ####
117+
Assert the underlying response's status code is between **400** and **500**.
118+
119+
#### `ResponseDecorator::isEmpty()` ####
120+
Assert the underlying response's status code is **204, 205** or **304**.
121+
122+
#### `ResponseDecorator::isForbidden()` ####
123+
Assert the underlying response's status code is **403**.
124+
125+
#### `ResponseDecorator::isInformational()` ####
126+
Assert the underlying response's status code is between **100** and **200**.
127+
128+
#### `ResponseDecorator::isOk()` ####
129+
Assert the underlying response's status code is **200**.
130+
131+
#### `ResponseDecorator::isNotFound()` ####
132+
Assert the underlying response's status code is **404**.
133+
134+
#### `ResponseDecorator::isRedirection()` ####
135+
Assert the underlying response's status code is between **300** and **400**.
136+
137+
#### `ResponseDecorator::isServerError()` ####
138+
Assert the underlying response's status code is between **500** and **600**.
139+
140+
#### `ResponseDecorator::isSuccessful()` ####
141+
Assert the underlying response's status code is between **200** and **300**.
142+
143+
#### `ResponseDecorator::__toString()` ####
144+
Will return a string formatted representation of the underlying response object.
145+
```
146+
HTTP/1.1 200 OK
147+
Content-Type: application/json;charset=utf-8
148+
149+
{"Hello": "World"}
150+
```
151+
152+
153+
## Decoratored ServerRequest Object Methods
154+
The decorated `ServerRequestInterface` provides the following additional methods:
155+
156+
#### `ServerRequestDecorator::withAttributes($attributes)` ####
157+
| Parameter | Type | Description |
158+
|-----------------|-----------|------------------------------------------|
159+
| **$attributes** | `array` | Attributes to be appended to the request |
160+
161+
#### `ServerRequestDecorator::getContentCharset()` ####
162+
Returns the detected charset from the `Content-Type` header of the underlying server request object. Returns `null` if no value is present.
163+
164+
#### `ServerRequestDecorator::getContentType()` ####
165+
Returns the value from the `Content-Type` header of the underlying server request object. Returns `null` if no value is present.
166+
167+
#### `ServerRequestDecorator::getContentLength()` ####
168+
Returns the value from the `Content-Length` header of the underlying server request object. Returns `null` if no value is present.
169+
170+
#### `ServerRequestDecorator::getCookieParam($key, $default)` ####
171+
| Parameter | Type | Description |
172+
|---------------|----------|--------------------------------------------------------|
173+
| **$key** | `string` | The attribute name |
174+
| **$default** | `mixed` | Default value to return if the attribute does not exist |
175+
176+
#### `ServerRequestDecorator::getMediaType()` ####
177+
Returns the first detected value from the `Content-Type` header of the underlying server request object. Returns `null` if no value is present.
178+
179+
#### `ServerRequestDecorator::getMediaTypeParams()` ####
180+
Returns an array of detected values from the `Content-Type` header of the underlying server request object. Returns an empty array if no values are present.
181+
182+
#### `ServerRequestDecorator::getParam($key, $default)` ####
183+
Returns the value from key in `$_POST` or `$_GET`
184+
185+
| Parameter | Type | Description |
186+
|--------------|----------|---------------------------------------------------------|
187+
| **$key** | `string` | The attribute name |
188+
| **$default** | `mixed` | Default value to return if the attribute does not exist |
189+
190+
#### `ServerRequestDecorator::getParams()` ####
191+
Returns a merged associative array of the `$_POST` and `$_GET` parameters.
192+
193+
#### `ServerRequestDecorator::getParsedBody()` ####
194+
Returns the parsed body from the underlying server request object if it already has been parsed by the underlying PSR-7 implementation. If the parsed body is empty, our decorator attempts to detect the content type and parse the body using one of the registered media type parsers.
195+
196+
The default media type parsers support:
197+
- JSON
198+
- XML
199+
200+
You can register your own media type parser using the `ServerRequestDecorator::registerMediaTypeParser()` method.
201+
202+
203+
#### `ServerRequestDecorator::getParsedBodyParam($key, $default)` ####
204+
Returns the value from key in the parsed body of the underlying server request object.
205+
206+
| Parameter | Type | Description |
207+
|--------------|----------|---------------------------------------------------------|
208+
| **$key** | `string` | The attribute name |
209+
| **$default** | `mixed` | Default value to return if the attribute does not exist |
210+
211+
#### `ServerRequestDecorator::getQueryParam($key, $default)` ####
212+
Returns the value from key in the parsed `ServerRequest` query string
213+
214+
| Parameter | Type | Description |
215+
|---------------|----------|---------------------------------------------------------|
216+
| **$key** | `string` | The attribute name |
217+
| **$default** | `mixed` | Default value to return if the attribute does not exist |
218+
219+
#### `ServerRequestDecorator::getServerParam($key, $default)` ####
220+
Returns the value from key in parsed server parameters from the underlying underlying server request object.
221+
222+
| Parameter | Type | Description |
223+
|--------------|----------|----------------------------------------------------------|
224+
| **$key** | `string` | The attribute name |
225+
| **$default** | `mixed` | Default value to return if the attribute does not exist |
226+
227+
#### `ServerRequestDecorator::registerMediaTypeParser($key, $default)` ####
228+
Returns the value from key in parsed server parameters from the underlying server request object.
229+
230+
| Parameter | Type | Description |
231+
|----------------|------------|--------------------------------------------------------|
232+
| **$mediaType** | `string` | A HTTP media type (excluding content-type params) |
233+
| **$callable** | `callable` | A callable that returns parsed contents for media type |
234+
235+
#### `ServerRequestDecorator::isMethod($method)` ####
236+
| Parameter | Type | Description |
237+
|-------------|----------|-----------------|
238+
| **$method** | `string` | The method name |
239+
240+
#### `ServerRequestDecorator::isDelete()` ####
241+
Asserts that the underlying server request's method is `DELETE`
242+
243+
#### `ServerRequestDecorator::isGet()` ####
244+
Asserts that the underlying server request's method is `GET`
245+
246+
#### `ServerRequestDecorator::isHead()` ####
247+
Asserts that the underlying server request's method is `HEAD`
248+
249+
#### `ServerRequestDecorator::isOptions()` ####
250+
Asserts that the underlying server request's method is `OPTIONS`
251+
252+
#### `ServerRequestDecorator::isPatch()` ####
253+
Asserts that the underlying server request's method is `PATCH`
254+
255+
#### `ServerRequestDecorator::isPost()` ####
256+
Asserts that the underlying server request's method is `POST`
257+
258+
#### `ServerRequestDecorator::isPut()` ####
259+
Asserts that the underlying server request's method is `PUT`
260+
261+
#### `ServerRequestDecorator::isXhr()` ####
262+
Asserts that the header `X-Requested-With` from the underlying server request is `XMLHttpRequest`
263+
264+
## Decorated Uri Object Methods
265+
The decorated `UriInterface` provides the following additional methods:
266+
267+
#### `UriDecorator::getBaseUrl()` ####
268+
Returns the fully qualified base URL of the underlying uri object.
269+
270+
## Contributing
36271
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
37272

38273
## Security
39-
40274
If you discover security related issues, please email [email protected]
41275
instead of using the issue tracker.
42276

43277
## Credits
44-
45278
- [Josh Lockhart](https://github.com/codeguy)
46279
- [Andrew Smith](https://github.com/silentworks)
47280
- [Rob Allen](https://github.com/akrabat)
281+
- [Pierre Bérubé](https://github.com/l0gicgate)
48282
- [All Contributors](../../contributors)
49283

50284
## License
51285

52-
This component is licensed under the MIT license. See [License File](LICENSE.md)
286+
This component is licensed under the MIT license. See [License File](LICENSE)
53287
for more information.

0 commit comments

Comments
 (0)