Coroutine HTTP2 Client

Notice: the documentation is suitable for PHP extension swoole until v4.7.1, we only support PHP extension openswoole from v4.7.1

This client is a coroutine safe HTTP2 Client. It specifically focuses on supporting the HTTP2 protocol.

In summary the HTTP/2 protocol is the next major version after HTTP/1.1 and it comes with great performance benefits, better security and complete rework of workarounds that were used within HTTP/1.1 and this client allows you to communicate over a network using HTTP/2. This HTTP/2 client is supposed to be used with compatible servers that support it.

If you don't specifically need support for HTTP/2 then checkout the HTTP Client.

If possible it is more recommended to enable coroutine hooks and use Swoole PHP CURL within a coroutine context, allowing you to use normal CURL functions in PHP. Because there is full support for CURL in PHP when using Swoole, you are also able to use any libraries that are based on CURL in Swoole, CURL is a great alternative as it supports HTTP/2, checkout the documentation for it.

Some of the main features supported by this client is SSL support, timeouts, data streaming, GoAway frame.

Important: To use this client it is only available when you have installed Swoole using the enable-http2="yes" flag, otherwise you will receive a fatal PHP error about an unknown class. Same goes for if you need SSL support, you must install Swoole with OpenSSL installed and with the enable-openssl="yes" flag.


Methods


Client Timeouts

All network requests (establishing a connection, send data and receive data) may time out. This client has a few ways for how you can setup timeouts.

As each Swoole client is written as a built-in class using coroutines, their timeouts are set the same way, refer to the timeout guide to understand how to setup timeouts.


Error Codes

When using this client, you are bound to come across processing errors. This mostly happens when using connect, send, recv and close methods. Most of these methods return false when there is a problem but you can use $client->errCode to check for what went wrong.

Once you have the error code, you can convert it into a message:

<?php
echo socket_strerror($client->errCode);

// Or

echo $client->errMsg;

This will give you a Linux system error message.


HTTP2 Request Object

The request object is used to build up a request which will be sent, this object has no methods, only public class properties you set values for, checkout the request object documentation for more details. Also checkout the examples below.

HTTP2 Response Object

When receiving a response from either recv() or read() you will be returned a response object, you can use this object to access information about the response.


Quick Start Examples

Basic Example

<?php

use Swoole\Http2\Request;
use Swoole\Coroutine\Http2\Client;

Co\run(function()
{
    // Setup a new HTTP2 client and a timeout
    $client = new Swoole\Coroutine\Http2\Client('127.0.0.1', 9518);
    $client->set(['timeout' => 2]);

    // Try and connect to the remote host
    $client->connect();

    // Create and build a request that will be sent...
    $request = new Swoole\Http2\Request();
    $request->path = "/index.php";
    $request->headers = [
        'host' => "localhost",
        "user-agent" => 'Chrome/49.0.2587.3',
        'accept' => 'text/html,application/xhtml+xml,application/xml',
        'accept-encoding' => 'gzip',
    ];

    // Add cookies to the request
    $request->cookies = ['name' => 'hello', 'email' => '[email protected]'];

    // Send and receive a response and output the result
    var_dump($client->send($request));
    $response = $client->recv();
    var_dump($response);
});


SSL Example

<?php

use Swoole\Http2\Request;
use Swoole\Coroutine\Http2\Client;

Co\run(function()
{
    // The domain we want to connect to
    $domain = 'www.swoole.co.uk';

    // Setup a HTTP2 client with SSL enabled
    $client = new Swoole\Coroutine\Http2\Client($domain, 443, true);
    $client->set([
        'timeout' => -1,
        'ssl_host_name' => $domain
    ]);

    // Try and connect to the remote host
    $client->connect();

    // Create and build a request that will be sent...
    $request = new Swoole\Http2\Request();
    $request->method = 'POST';
    $request->path = '/api/v4/answers/300000000/voters';
    $request->headers = [
        'host' => $domain,
        'user-agent' => 'Chrome/49.0.2587.3',
        'accept' => 'text/html,application/xhtml+xml,application/xml',
        'accept-encoding' => 'gzip'
    ];

    // Add POST data to the request
    $request->data = '{"type": "up"}';

    // Send and receive a response and output the result
    $client->send($request);
    $response = $client->recv();

    // Process the response
    var_dump(assert(json_decode($response->data)->error->code === 10002));
});