Skip to content

Commit 3f02cd0

Browse files
legionthlegionth
committed
Update README
1 parent daadd55 commit 3f02cd0

2 files changed

Lines changed: 70 additions & 25 deletions

File tree

‎README.md‎

Lines changed: 39 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ This is an HTTP server which responds with `Hello World` to every request.
2323
$loop = React\EventLoop\Factory::create();
2424
$socket = new React\Socket\Server(8080, $loop);
2525

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

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

78-
$http = new Server($socket, function (RequestInterface $request) {
78+
$http = new Server($socket, function (ServerRequestInterface $request) {
7979
return new Response(
8080
200,
8181
array('Content-Type' => 'text/plain'),
@@ -137,11 +137,13 @@ connections and then processing each incoming HTTP request.
137137
The request object will be processed once the request headers have
138138
been received by the client.
139139
This request object implements the
140+
[PSR-7 ServerRequestInterface](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md#321-psrhttpmessageserverrequestinterface)
141+
which in turn extends the
140142
[PSR-7 RequestInterface](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md#32-psrhttpmessagerequestinterface)
141143
and will be passed to the callback function like this.
142144

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

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

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

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

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

250254
```php
251-
$http = new Server($socket, function (RequestInterface $request) {
255+
$http = new Server($socket, function (ServerRequestInterface $request) {
252256
$size = $request->getBody()->getSize();
253257
if ($size === null) {
254258
$body = 'The request does not contain an explicit length.';
@@ -269,6 +273,26 @@ $http = new Server($socket, function (RequestInterface $request) {
269273
});
270274
```
271275

276+
As mentioned before the request implements the `ServerRequestInterface`.
277+
The `Server` will add server-side parameters like the remote address,
278+
remote port or cookies to this object.
279+
The remote address(`remote_address`) and remote port(`remote_port`)
280+
will be added by the `Server` and can be received by the `getServerParams()`
281+
method.
282+
283+
```php
284+
$http = new Server($socket, function (ServerRequestInterface $request) {
285+
$body = "The remote ip is: " . $request->getServerParams()['remote_address'];
286+
$body = "The remote port is: " . $request->getServerParams()['remote_port'];
287+
288+
return new Response(
289+
200,
290+
array('Content-Type' => 'text/plain'),
291+
$body
292+
);
293+
});
294+
```
295+
272296
Note that the server supports *any* request method (including custom and non-
273297
standard ones) and all request-target formats defined in the HTTP specs for each
274298
respective method.
@@ -308,7 +332,7 @@ but feel free to use any implemantation of the
308332
`PSR-7 ResponseInterface` you prefer.
309333

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

329353
```php
330-
$server = new \React\Http\Server($socket, function (RequestInterface $request) use ($loop) {
354+
$server = new \React\Http\Server($socket, function (ServerRequestInterface $request) use ($loop) {
331355
return new Promise(function ($resolve, $reject) use ($request, $loop) {
332356
$loop->addTimer(1.5, function() use ($loop, $resolve) {
333357
$response = new Response(
@@ -355,7 +379,7 @@ Note that other implementations of the `PSR-7 ResponseInterface` likely
355379
only support string.
356380

357381
```php
358-
$server = new Server($socket, function (RequestInterface $request) use ($loop) {
382+
$server = new Server($socket, function (ServerRequestInterface $request) use ($loop) {
359383
$stream = new ReadableStream();
360384

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

390414
```php
391415
$stream = new ReadableStream()
392-
$server = new Server($socket, function (RequestInterface $request) use ($loop, $stream) {
416+
$server = new Server($socket, function (ServerRequestInterface $request) use ($loop, $stream) {
393417
return new Response(
394418
200,
395419
array(
@@ -437,7 +461,7 @@ A `Date` header will be automatically added with the system date and time if non
437461
You can add a custom `Date` header yourself like this:
438462

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

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

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

466490
```php
467-
$server = new Server($socket, function (RequestInterface $request) {
491+
$server = new Server($socket, function (ServerRequestInterface $request) {
468492
return new Response(200, array('X-Powered-By' => ''));
469493
});
470494
```

‎src/Server.php‎

Lines changed: 31 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
* ```php
2626
* $socket = new React\Socket\Server(8080, $loop);
2727
*
28-
* $http = new Server($socket, function (RequestInterface $request) {
28+
* $http = new Server($socket, function (ServerRequestInterface $request) {
2929
* return new Response(
3030
* 200,
3131
* array('Content-Type' => 'text/plain'),
@@ -46,7 +46,7 @@
4646
* 'local_cert' => __DIR__ . '/localhost.pem'
4747
* ));
4848
*
49-
* $http = new Server($socket, function (RequestInterface $request) {
49+
* $http = new Server($socket, function (ServerRequestInterface $request) {
5050
* return new Response(
5151
* 200,
5252
* array('Content-Type' => 'text/plain'),
@@ -81,6 +81,22 @@
8181
* });
8282
* ```
8383
*
84+
* The server will also emit an `error` event if you return an invalid
85+
* type in the callback function or have a unhandled `Exception`.
86+
* If your callback function throws an exception,
87+
* the `Server` will emit a `RuntimeException` and add the thrown exception
88+
* as previous:
89+
*
90+
* ```php
91+
* $http->on('error', function (Exception $e) {
92+
* echo 'Error: ' . $e->getMessage() . PHP_EOL;
93+
* if ($e->getPrevious() !== null) {
94+
* $previousException = $e->getPrevious();
95+
* echo $previousException->getMessage() . PHP_EOL;
96+
* }
97+
* });
98+
* ```
99+
*
84100
* Note that the request object can also emit an error.
85101
* Check out [request](#request) for more details.
86102
*
@@ -99,15 +115,17 @@ class Server extends EventEmitter
99115
* as HTTP.
100116
*
101117
* For each request, it executes the callback function passed to the
102-
* constructor with the respective [`Request`](#request) and
103-
* [`Response`](#response) objects:
118+
* constructor with the respective [`request`](#request) object:
104119
*
105120
* ```php
106121
* $socket = new React\Socket\Server(8080, $loop);
107122
*
108-
* $http = new Server($socket, function (Request $request, Response $response) {
109-
* $response->writeHead(200, array('Content-Type' => 'text/plain'));
110-
* $response->end("Hello World!\n");
123+
* $http = new Server($socket, function (ServerRequestInterface $request) {
124+
* return new Response(
125+
* 200,
126+
* array('Content-Type' => 'text/plain'),
127+
* "Hello World!\n"
128+
* );
111129
* });
112130
* ```
113131
*
@@ -121,9 +139,12 @@ class Server extends EventEmitter
121139
* 'local_cert' => __DIR__ . '/localhost.pem'
122140
* ));
123141
*
124-
* $http = new Server($socket, function (Request $request, Response $response) {
125-
* $response->writeHead(200, array('Content-Type' => 'text/plain'));
126-
* $response->end("Hello World!\n");
142+
* $http = new Server($socket, function (ServerRequestInterface $request $request) {
143+
* return new Response(
144+
* 200,
145+
* array('Content-Type' => 'text/plain'),
146+
* "Hello World!\n"
147+
* );
127148
* });
128149
*```
129150
*

0 commit comments

Comments
 (0)