Skip to content

Commit

Permalink
Adapt README
Browse files Browse the repository at this point in the history
  • Loading branch information
legionth committed Mar 21, 2017
1 parent b27a34b commit 524fe9d
Showing 1 changed file with 33 additions and 18 deletions.
51 changes: 33 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,25 +104,40 @@ for more details.
### Request

A HTTP request will be sent by a client to the [Server](#server).
The `Server` will receive this request on the `data` event and
is responsible to create a request object from this data.
This object will be passed to the callback function.

The request is an instance of [PSR-7 RequestInterface](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md#32-psrhttpmessagerequestinterface).

As defined in PSR-7, the `getBody()` method returns a stream instance
which implements the [PSR-7 StreamInterface](http://www.php-fig.org/psr/psr-7/#psrhttpmessagestreaminterface).
Note that the incoming request will be processed once the request headers have
been received, which implies that the (potentially much larger) request body
may still be outstanding (in a streaming state).
The `Server` will receive this request and
is responsible for creating a request object from this data.
The request will be processed once the request headers have
been received, irrespective of the (potentially much larger) request body (see also below).
This object implements the
[PSR-7 RequestInterface](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md#32-psrhttpmessagerequestinterface).
and will be passed to the callback function.

```php
$http = new Server($socket, function (RequestInterface $request, Response $response) {
$response->writeHead(200, array('Content-Type' => 'text/plain'));
$response->write("The method of the request is: " . $request->getMethod());
$response->end("The requested path is: " . $request->getUri()->getPath());
});
```

For more details about the request object, check out the [PSR-7 RequestInterface](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md#32-psrhttpmessagerequestinterface) documentation.

If you want to access the request body you can use `getBody()`.
This method returns an instance that implements both the [PSR-7 StreamInterface](http://www.php-fig.org/psr/psr-7/#psrhttpmessagestreaminterface)
and the [ReactPHP ReadableStreamInterface](https://github.com/reactphp/stream#readablestreaminterface).
Because of the `ReactPHP ReadableStreamInterface` implemantation
you have opportunities like receiving large amount of data without
the need to buffer, deny the request if the body is too big or
start processing parts of the body without waiting for
the complete body data.
Use this to receive the full potential out of such scenarios and
create a fast application.
However, most of the `PSR-7 StreamInterface` methods have been
designed under the assumption of being in control of the request body.
Given that this does not apply to this server, the following
This does not apply to this server, the following
`PSR-7 StreamInterface` methods are not used and SHOULD NOT be called:
`tell()`, `eof()`, `seek()`, `rewind()`, `write()` and `read()`.
Instead, the returned stream instance *also* implements the
[ReactPHP ReadableStreamInterface](https://github.com/reactphp/stream#readablestreaminterface)
which gives you access to the incoming request body as the individual chunks
The stream you access to the incoming request body as the individual chunks
arrive:

```php
Expand Down Expand Up @@ -161,11 +176,11 @@ advance because the request message uses chunked transfer encoding.
```php
$http = new Server($socket, function (RequestInterface $request, Response $response) {
$response->writeHead(200, array('Content-Type' => 'text/plain'));
$response->write("Request method: " . $request->getMethod() . "\n");
if ($request->getBody()->getSize() !== null) {
$response->write("Request body size: " . $request->getBody()->getSize() . "\n");
$response->end("Request body size: " . $request->getBody()->getSize() . "\n");
return;
}
$response->end("The requested path is: " . $request->getUri()->getPath());
$response->end("No size given.");
});
```

Expand Down

0 comments on commit 524fe9d

Please sign in to comment.