Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@legionth
legionth committed Apr 2, 2017
1 parent 0c8ea69 commit 82baf6d
Show file tree
Hide file tree
Showing 2 changed files with 65 additions and 26 deletions.
50 changes: 34 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ This is an HTTP server which responds with `Hello World` to every request.
$loop = React\EventLoop\Factory::create();
$socket = new React\Socket\Server(8080, $loop);

$http = new Server($socket, function (RequestInterface $request) {
$http = new Server($socket, function (ServerRequestInterface $request) {
return new Response(
200,
array('Content-Type' => 'text/plain'),
Expand Down Expand Up @@ -54,7 +54,7 @@ constructor with the respective [request](#request) and
```php
$socket = new React\Socket\Server(8080, $loop);

$http = new Server($socket, function (RequestInterface $request) {
$http = new Server($socket, function (ServerRequestInterface $request) {
return new Response(
200,
array('Content-Type' => 'text/plain'),
Expand All @@ -75,7 +75,7 @@ $socket = new React\Socket\SecureServer($socket, $loop, array(
'local_cert' => __DIR__ . '/localhost.pem'
));

$http = new Server($socket, function (RequestInterface $request) {
$http = new Server($socket, function (ServerRequestInterface $request) {
return new Response(
200,
array('Content-Type' => 'text/plain'),
Expand Down Expand Up @@ -136,12 +136,14 @@ connections and then processing each incoming HTTP request.

The request object will be processed once the request headers have
been received by the client.
This request object implements the
This request object uses an implementation of the
[PSR-7 RequestInterface](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md#32-psrhttpmessagerequestinterface)
and implements the
[PSR-7 ServerRequestInterface](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md#321-psrhttpmessageserverrequestinterface)
and will be passed to the callback function like this.

```php
$http = new Server($socket, function (RequestInterface $request) {
```php
$http = new Server($socket, function (ServerRequestInterface $request) {
$body = "The method of the request is: " . $request->getMethod();
$body .= "The requested path is: " . $request->getUri()->getPath();

Expand All @@ -155,6 +157,8 @@ $http = new Server($socket, function (RequestInterface $request) {

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

Note that the request object will be processed once the request headers have
been received.
Expand Down Expand Up @@ -184,7 +188,7 @@ Instead, you should use the `ReactPHP ReadableStreamInterface` which
gives you access to the incoming request body as the individual chunks arrive:

```php
$http = new Server($socket, function (RequestInterface $request) {
$http = new Server($socket, function (ServerRequestInterface $request) {
return new Promise(function ($resolve, $reject) use ($request) {
$contentLength = 0;
$request->getBody()->on('data', function ($data) use (&$contentLength) {
Expand Down Expand Up @@ -248,7 +252,7 @@ Note that this value may be `null` if the request body size is unknown in
advance because the request message uses chunked transfer encoding.

```php
$http = new Server($socket, function (RequestInterface $request) {
$http = new Server($socket, function (ServerRequestInterface $request) {
$size = $request->getBody()->getSize();
if ($size === null) {
$body = 'The request does not contain an explicit length.';
Expand All @@ -269,6 +273,20 @@ $http = new Server($socket, function (RequestInterface $request) {
});
```

As mentioned before the request implements the `ServerRequestInterface`.
The `Server` will add server-side parameters like the remote address or cookies
this object.

```php
$http = new Server($socket, function (ServerRequestInterface $request) {
return new Response(
200,
array('Content-Type' => 'text/plain'),
"The remote: " . $request->getServerParams()['remote_address']
);
});
```

Note that the server supports *any* request method (including custom and non-
standard ones) and all request-target formats defined in the HTTP specs for each
respective method.
Expand Down Expand Up @@ -308,7 +326,7 @@ but feel free to use any implemantation of the
`PSR-7 ResponseInterface` you prefer.

```php
$http = new Server($socket, function (RequestInterface $request) {
$http = new Server($socket, function (ServerRequestInterface $request) {
return new Response(
200,
array('Content-Type' => 'text/plain'),
Expand All @@ -327,7 +345,7 @@ To prevent this you SHOULD use a
This example shows how such a long-term action could look like:

```php
$server = new \React\Http\Server($socket, function (RequestInterface $request) use ($loop) {
$server = new \React\Http\Server($socket, function (ServerRequestInterface $request) use ($loop) {
return new Promise(function ($resolve, $reject) use ($request, $loop) {
$loop->addTimer(1.5, function() use ($loop, $resolve) {
$response = new Response(
Expand Down Expand Up @@ -355,7 +373,7 @@ Note that other implementations of the `PSR-7 ResponseInterface` likely
only support string.

```php
$server = new Server($socket, function (RequestInterface $request) use ($loop) {
$server = new Server($socket, function (ServerRequestInterface $request) use ($loop) {
$stream = new ReadableStream();

$timer = $loop->addPeriodicTimer(0.5, function () use ($stream) {
Expand Down Expand Up @@ -389,7 +407,7 @@ If you know the length of your stream body, you MAY specify it like this instead

```php
$stream = new ReadableStream()
$server = new Server($socket, function (RequestInterface $request) use ($loop, $stream) {
$server = new Server($socket, function (ServerRequestInterface $request) use ($loop, $stream) {
return new Response(
200,
array(
Expand Down Expand Up @@ -437,7 +455,7 @@ A `Date` header will be automatically added with the system date and time if non
You can add a custom `Date` header yourself like this:

```php
$server = new Server($socket, function (RequestInterface $request) {
$server = new Server($socket, function (ServerRequestInterface $request) {
return new Response(200, array('Date' => date('D, d M Y H:i:s T')));
});
```
Expand All @@ -446,7 +464,7 @@ If you don't have a appropriate clock to rely on, you should
unset this header with an empty string:

```php
$server = new Server($socket, function (RequestInterface $request) {
$server = new Server($socket, function (ServerRequestInterface $request) {
return new Response(200, array('Date' => ''));
});
```
Expand All @@ -455,7 +473,7 @@ Note that it will automatically assume a `X-Powered-By: react/alpha` header
unless your specify a custom `X-Powered-By` header yourself:

```php
$server = new Server($socket, function (RequestInterface $request) {
$server = new Server($socket, function (ServerRequestInterface $request) {
return new Response(200, array('X-Powered-By' => 'PHP 3'));
});
```
Expand All @@ -464,7 +482,7 @@ If you do not want to send this header at all, you can use an empty string as
value like this:

```php
$server = new Server($socket, function (RequestInterface $request) {
$server = new Server($socket, function (ServerRequestInterface $request) {
return new Response(200, array('X-Powered-By' => ''));
});
```
Expand Down
41 changes: 31 additions & 10 deletions src/Server.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
* ```php
* $socket = new React\Socket\Server(8080, $loop);
*
* $http = new Server($socket, function (RequestInterface $request) {
* $http = new Server($socket, function (ServerRequestInterface $request) {
* return new Response(
* 200,
* array('Content-Type' => 'text/plain'),
Expand All @@ -46,7 +46,7 @@
* 'local_cert' => __DIR__ . '/localhost.pem'
* ));
*
* $http = new Server($socket, function (RequestInterface $request) {
* $http = new Server($socket, function (ServerRequestInterface $request) {
* return new Response(
* 200,
* array('Content-Type' => 'text/plain'),
Expand Down Expand Up @@ -81,6 +81,22 @@
* });
* ```
*
* The server will also emit an `error` event if you return an invalid
* type in the callback function or have a unhandled `Exception`.
* If your callback function throws an exception,
* the `Server` will emit a `RuntimeException` and add the thrown exception
* as previous:
*
* ```php
* $http->on('error', function (Exception $e) {
* echo 'Error: ' . $e->getMessage() . PHP_EOL;
* if ($e->getPrevious() !== null) {
* $previousException = $e->getPrevious();
* echo $previousException->getMessage() . PHP_EOL;
* }
* });
* ```
*
* Note that the request object can also emit an error.
* Check out [request](#request) for more details.
*
Expand All @@ -99,15 +115,17 @@ class Server extends EventEmitter
* as HTTP.
*
* For each request, it executes the callback function passed to the
* constructor with the respective [`Request`](#request) and
* [`Response`](#response) objects:
* constructor with the respective [`request`](#request) object:
*
* ```php
* $socket = new React\Socket\Server(8080, $loop);
*
* $http = new Server($socket, function (Request $request, Response $response) {
* $response->writeHead(200, array('Content-Type' => 'text/plain'));
* $response->end("Hello World!\n");
* $http = new Server($socket, function (ServerRequestInterface $request) {
* return new Response(
* 200,
* array('Content-Type' => 'text/plain'),
* "Hello World!\n"
* );
* });
* ```
*
Expand All @@ -121,9 +139,12 @@ class Server extends EventEmitter
* 'local_cert' => __DIR__ . '/localhost.pem'
* ));
*
* $http = new Server($socket, function (Request $request, Response $response) {
* $response->writeHead(200, array('Content-Type' => 'text/plain'));
* $response->end("Hello World!\n");
* $http = new Server($socket, function (ServerRequestInterface $request $request) {
* return new Response(
* 200,
* array('Content-Type' => 'text/plain'),
* "Hello World!\n"
* );
* });
*```
*
Expand Down

0 comments on commit 82baf6d

Please sign in to comment.