Getting Started Libraries Services Libraries React PHP react-http

react-http

Http Component

Event-driven, streaming plaintext HTTP and secure HTTPS server for ReactPHP

Table of Contents

Quickstart example
Usage
- Server
- Request
- Response
Install
Tests
License

Quickstart example

This is an HTTP server which responds with Hello World to every request.

$loop = React\EventLoop\Factory::create();

$server = new Server(function (ServerRequestInterface $request) {
    return new Response(
        200,
        array('Content-Type' => 'text/plain'),
        "Hello World!\n"
    );
});

$socket = new React\Socket\Server(8080, $loop);
$server->listen($socket);

$loop->run();

Usage

Server

The Server class is responsible for handling incoming connections and then processing each incoming HTTP request.

For each request, it executes the callback function passed to the constructor with the respective request object and expects a respective response object in return.

$server = new Server(function (ServerRequestInterface $request) {
    return new Response(
        200,
        array('Content-Type' => 'text/plain'),
        "Hello World!\n"
    );
});

In order to process any connections, the server needs to be attached to an instance of React\Socket\ServerInterface which emits underlying streaming connections in order to then parse incoming data as HTTP.

You can attach this to a React\Socket\Server in order to start a plaintext HTTP server like this:

$server = new Server($handler);

$socket = new React\Socket\Server(8080, $loop);
$server->listen($socket);

See also the listen() method and the first example for more details.

Similarly, you can also attach this to a React\Socket\SecureServer in order to start a secure HTTPS server like this:

$server = new Server($handler);

$socket = new React\Socket\Server(8080, $loop);
$socket = new React\Socket\SecureServer($socket, $loop, array(
    'local_cert' => __DIR__ . '/localhost.pem'
));

$server->listen($socket);

Request

An seen above, the Server class is responsible for handling incoming 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 PSR-7 ServerRequestInterface which in turn extends the PSR-7 RequestInterface and will be passed to the callback function like this.

$server = new Server(function (ServerRequestInterface $request) {
    $body = "The method of the request is: " . $request->getMethod();
    $body .= "The requested path is: " . $request->getUri()->getPath();

    return new Response(
        200,
        array('Content-Type' => 'text/plain'),
        $body
    );
});

The getServerParams(): mixed[] method can be used to get server-side parameters similar to the $_SERVER variable. The following parameters are currently available:

REMOTE_ADDR The IP address of the request sender
REMOTE_PORT Port of the request sender
SERVER_ADDR The IP address of the server
SERVER_PORT The port of the server
REQUEST_TIME Unix timestamp when the complete request header has been received, as integer similar to time()
REQUEST_TIME_FLOAT Unix timestamp when the complete request header has been received, as float similar to microtime(true)
HTTPS Set to 'on' if the request used HTTPS, otherwise it won't be set

$server = new Server(function (ServerRequestInterface $request) {
    $body = "Your IP is: " . $request->getServerParams()['REMOTE_ADDR'];

    return new Response(
        200,
        array('Content-Type' => 'text/plain'),
        $body
    );
});

Response

The callback function passed to the constructor of the Server is responsible for processing the request and returning a response, which will be delivered to the client. This function MUST return an instance imlementing PSR-7 ResponseInterface object or a ReactPHP Promise which will resolve a PSR-7 ResponseInterface object.

You will find a Response class which implements the PSR-7 ResponseInterface in this project. We use instantiation of this class in our projects, but feel free to use any implemantation of the PSR-7 ResponseInterface you prefer.

$server = new Server(function (ServerRequestInterface $request) {
    return new Response(
        200,
        array('Content-Type' => 'text/plain'),
        "Hello World!\n"
    );
});

The example above returns the response directly, because it needs no time to be processed. Using a database, the file system or long calculations (in fact every action that will take >=1ms) to create your response, will slow down the server. To prevent this you SHOULD use a ReactPHP Promise. This example shows how such a long-term action could look like:

$server = new Server(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(
                200,
                array('Content-Type' => 'text/plain'),
                "Hello world"
            );
            $resolve($response);
        });
    });
});

The above example will create a response after 1.5 second. This example shows that you need a promise, if your response needs time to created. The ReactPHP Promise will resolve in a Response object when the request body ends. If the client closes the connection while the promise is still pending, the promise will automatically be cancelled. The promise cancellation handler can be used to clean up any pending resources allocated in this case (if applicable). If a promise is resolved after the client closes, it will simply be ignored.

The Response class in this project supports to add an instance which implements the ReactPHP ReadableStreamInterface for the response body. So you are able stream data directly into the response body. Note that other implementations of the PSR-7 ResponseInterface likely only support strings.

$server = new Server(function (ServerRequestInterface $request) use ($loop) {
    $stream = new ThroughStream();

    $timer = $loop->addPeriodicTimer(0.5, function () use ($stream) {
        $stream->emit('data', array(microtime(true) . PHP_EOL));
    });

    $loop->addTimer(5, function() use ($loop, $timer, $stream) {
        $loop->cancelTimer($timer);
        $stream->emit('end');
    });

    return new Response(200, array('Content-Type' => 'text/plain'), $stream);
});

The above example will emit every 0.5 seconds the current Unix timestamp with microseconds as float to the client and will end after 5 seconds. This is just a example you could use of the streaming, you could also send a big amount of data via little chunks or use it for body data that needs to calculated.

If the request handler resolves with a response stream that is already closed, it will simply send an empty response body. If the client closes the connection while the stream is still open, the response stream will automatically be closed. If a promise is resolved with a streaming body after the client closes, the response stream will automatically be closed. The close event can be used to clean up any pending resources allocated in this case (if applicable).

If the response body is a string, a Content-Length header will be added automatically. If the response body is a ReactPHP ReadableStreamInterface and you do not specify a Content-Length header, HTTP/1.1 responses will automatically use chunked transfer encoding and send the respective header (Transfer-Encoding: chunked) automatically. The server is responsible for handling Transfer-Encoding, so you SHOULD NOT pass this header yourself. If you know the length of your stream body, you MAY specify it like this instead:

$stream = new ThroughStream()
$server = new Server(function (ServerRequestInterface $request) use ($stream) {
    return new Response(
        200,
        array(
            'Content-Length' => '5',
            'Content-Type' => 'text/plain',
        ),
        $stream
    );
});

An invalid return value or an unhandled Exception in the code of the callback function, will result in an 500 Internal Server Error message. Make sure to catch Exceptions to create own response messages.

After the return in the callback function the response will be processed by the Server. The Server will add the protocol version of the request, so you don't have to.

Any response to a HEAD request and any response with a 1xx (Informational), 204 (No Content) or 304 (Not Modified) status code will not include a message body as per the HTTP specs. This means that your callback does not have to take special care of this and any response body will simply be ignored.

Similarly, any 2xx (Successful) response to a CONNECT request, any response with a 1xx (Informational) or 204 (No Content) status code will not include a Content-Length or Transfer-Encoding header as these do not apply to these messages. Note that a response to a HEAD request and any response with a 304 (Not Modified) status code MAY include these headers even though the message does not contain a response body, because these header would apply to the message if the same request would have used an (unconditional) GET.

Note that special care has to be taken if you use a body stream instance that implements ReactPHP's DuplexStreamInterface (such as the ThroughStream in the above example).

For most cases, this will simply only consume its readable side and forward (send) any data that is emitted by the stream, thus entirely ignoring the writable side of the stream. If however this is either a 101 (Switching Protocols) response or a 2xx (Successful) response to a CONNECT method, it will also write data to the writable side of the stream. This can be avoided by either rejecting all requests with the CONNECT method (which is what most normal origin HTTP servers would likely do) or or ensuring that only ever an instance of ReadableStreamInterface is used.

The 101 (Switching Protocols) response code is useful for the more advanced Upgrade requests, such as upgrading to the WebSocket protocol or implementing custom protocol logic that is out of scope of the HTTP specs and this HTTP library. If you want to handle the Upgrade: WebSocket header, you will likely want to look into using Ratchet instead. If you want to handle a custom protocol, you will likely want to look into the HTTP specs and also see examples #31 and #32 for more details. In particular, the 101 (Switching Protocols) response code MUST NOT be used unless you send an Upgrade response header value that is also present in the corresponding HTTP/1.1 Upgrade request header value. The server automatically takes care of sending a Connection: upgrade header value in this case, so you don't have to.

The CONNECT method is useful in a tunneling setup (HTTPS proxy) and not something most origin HTTP servers would want to care about. The HTTP specs define an opaque "tunneling mode" for this method and make no use of the message body. For consistency reasons, this library uses a DuplexStreamInterface in the response body for tunneled application data. This implies that that a 2xx (Successful) response to a CONNECT request can in fact use a streaming response body for the tunneled application data, so that any raw data the client sends over the connection will be piped through the writable stream for consumption. Note that while the HTTP specs make no use of the request body for CONNECT requests, one may still be present. Normal request body processing applies here and the connection will only turn to "tunneling mode" after the request body has been processed (which should be empty in most cases). See also example #22 for more details.

A Date header will be automatically added with the system date and time if none is given. You can add a custom Date header yourself like this:

$server = new Server(function (ServerRequestInterface $request) {
    return new Response(200, array('Date' => date('D, d M Y H:i:s T')));
});

If you don't have a appropriate clock to rely on, you should unset this header with an empty string:

$server = new Server(function (ServerRequestInterface $request) {
    return new Response(200, array('Date' => ''));
});

Note that it will automatically assume a X-Powered-By: react/alpha header unless your specify a custom X-Powered-By header yourself:

$server = new Server(function (ServerRequestInterface $request) {
    return new Response(200, array('X-Powered-By' => 'PHP 3'));
});

If you do not want to send this header at all, you can use an empty string as value like this:

$server = new Server(function (ServerRequestInterface $request) {
    return new Response(200, array('X-Powered-By' => ''));
});

Note that persistent connections (Connection: keep-alive) are currently not supported. As such, HTTP/1.1 response messages will automatically include a Connection: close header, irrespective of what header values are passed explicitly.

Install

The recommended way to install this library is through Composer. New to Composer?

This will install the latest supported version:

$ composer require react/http:^0.7

More details about version upgrades can be found in the CHANGELOG.

Tests

To run the test suite, you first need to clone this repo and then install all dependencies through Composer:

$ composer install

To run the test suite, go to the project root and run:

$ php vendor/bin/phpunit

License

MIT, see LICENSE file.