Skip to content

Commit 6a5d5a3

Browse files
legionthlegionth
committed
Update README
1 parent 42b5745 commit 6a5d5a3

File tree

2 files changed

+69
-25
lines changed

2 files changed

+69
-25
lines changed

‎README.md

Lines changed: 38 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

@@ -153,8 +155,29 @@ $http = new Server($socket, function (RequestInterface $request) {
153155
});
154156
```
155157

158+
As mentioned before the request implements the `ServerRequestInterface`.
159+
The `Server` will currently add several server-side parameters to the request like:
160+
161+
* `server_address`
162+
The current IP address of the server
163+
* `remote_address`
164+
The IP address of the request sender
165+
* `remote_port`
166+
Port of the request sender
167+
* `request_time`
168+
Unix timestamp of the moment, the complete request header was received
169+
* `request_time_float`
170+
Unix timestamp in microseconds of the moment, the complete request header wa
171+
received
172+
173+
The cookies of the request, will also be added to the request object by the `Server`.
174+
Use the `getCookies` method to receive these cookies
175+
176+
Any other parameters can be obtained by the request itself.
156177
For more details about the request object, check out the documentation of
157178
[PSR-7 RequestInterface](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md#32-psrhttpmessagerequestinterface).
179+
and
180+
[PSR-7 ServerRequestInterface](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md#321-psrhttpmessageserverrequestinterface)
158181

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

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

250273
```php
251-
$http = new Server($socket, function (RequestInterface $request) {
274+
$http = new Server($socket, function (ServerRequestInterface $request) {
252275
$size = $request->getBody()->getSize();
253276
if ($size === null) {
254277
$body = 'The request does not contain an explicit length.';
@@ -308,7 +331,7 @@ but feel free to use any implemantation of the
308331
`PSR-7 ResponseInterface` you prefer.
309332

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

329352
```php
330-
$server = new \React\Http\Server($socket, function (RequestInterface $request) use ($loop) {
353+
$server = new \React\Http\Server($socket, function (ServerRequestInterface $request) use ($loop) {
331354
return new Promise(function ($resolve, $reject) use ($request, $loop) {
332355
$loop->addTimer(1.5, function() use ($loop, $resolve) {
333356
$response = new Response(
@@ -355,7 +378,7 @@ Note that other implementations of the `PSR-7 ResponseInterface` likely
355378
only support string.
356379

357380
```php
358-
$server = new Server($socket, function (RequestInterface $request) use ($loop) {
381+
$server = new Server($socket, function (ServerRequestInterface $request) use ($loop) {
359382
$stream = new ReadableStream();
360383

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

390413
```php
391414
$stream = new ReadableStream()
392-
$server = new Server($socket, function (RequestInterface $request) use ($loop, $stream) {
415+
$server = new Server($socket, function (ServerRequestInterface $request) use ($loop, $stream) {
393416
return new Response(
394417
200,
395418
array(
@@ -437,7 +460,7 @@ A `Date` header will be automatically added with the system date and time if non
437460
You can add a custom `Date` header yourself like this:
438461

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

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

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

466489
```php
467-
$server = new Server($socket, function (RequestInterface $request) {
490+
$server = new Server($socket, function (ServerRequestInterface $request) {
468491
return new Response(200, array('X-Powered-By' => ''));
469492
});
470493
```

‎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
*
@@ -100,15 +116,17 @@ class Server extends EventEmitter
100116
* as HTTP.
101117
*
102118
* For each request, it executes the callback function passed to the
103-
* constructor with the respective [`Request`](#request) and
104-
* [`Response`](#response) objects:
119+
* constructor with the respective [`request`](#request) object:
105120
*
106121
* ```php
107122
* $socket = new React\Socket\Server(8080, $loop);
108123
*
109-
* $http = new Server($socket, function (Request $request, Response $response) {
110-
* $response->writeHead(200, array('Content-Type' => 'text/plain'));
111-
* $response->end("Hello World!\n");
124+
* $http = new Server($socket, function (ServerRequestInterface $request) {
125+
* return new Response(
126+
* 200,
127+
* array('Content-Type' => 'text/plain'),
128+
* "Hello World!\n"
129+
* );
112130
* });
113131
* ```
114132
*
@@ -122,9 +140,12 @@ class Server extends EventEmitter
122140
* 'local_cert' => __DIR__ . '/localhost.pem'
123141
* ));
124142
*
125-
* $http = new Server($socket, function (Request $request, Response $response) {
126-
* $response->writeHead(200, array('Content-Type' => 'text/plain'));
127-
* $response->end("Hello World!\n");
143+
* $http = new Server($socket, function (ServerRequestInterface $request $request) {
144+
* return new Response(
145+
* 200,
146+
* array('Content-Type' => 'text/plain'),
147+
* "Hello World!\n"
148+
* );
128149
* });
129150
*```
130151
*

0 commit comments

Comments
 (0)