Custom HTTP Headers

Sometimes, you need to send custom HTTP headers.

From Twirp’s perspective, “headers” are just metadata since HTTP is a lower level, transport layer. But since Twirp is primarily used with HTTP, sometimes you might need to send or receive some information from that layer too.

Client side

Send HTTP Headers with client requests

Use Twirp\Context::withHttpRequestHeaders to attach a map of headers to the context:


// Given a client ...
$client = new \Twitch\Twirp\Example\HaberdasherClient($addr);

// Given some headers ...
$headers = [
    'Twitch-Authorization' => 'uDRlDxQYbFVXarBvmTncBoWKcZKqrZTY',
    'Twitch-Client-ID' => 'FrankerZ',

// Attach the headers to a context
$ctx = [];
$ctx = \Twirp\Context::withHttpRequestHeaders($ctx, $headers);

// And use the context in the request. Headers will be included in the request!
$resp = $client—>MakeHat($ctx, new \Twitch\Twirp\Example\Size());

Read HTTP Headers from responses

Twirp client responses are structs that depend only on the protobuf response. HTTP headers can not be used by the Twirp client in any way.

However, remember that the TwirPHP client is instantiated with a PSR-18 HTTP client, which can be anything that implements the minimal interface. For example you could configure an HTTPlug PluginClient and read the headers in a plugin.

Server side

Send HTTP Headers on server responses

In your server implementation you can set HTTP headers using Twirp\Context::withHttpResponseHeader.


public function MakeHat(array $ctx, \Twitch\Twirp\Example\Size $size): Hat
    \Twirp\Context::withHttpResponseHeader($ctx, 'Cache-Control', 'public, max-age=60');

    $hat = new \Twitch\Twirp\Example\Hat();

    return $hat;

Read HTTP Headers from requests

TwirPHP server methods are abstracted away from HTTP, therefore they don’t have direct access to HTTP Headers.

However, they receive the PSR-7 server attributes as the context that can be modified by HTTP middleware before being used by the Twirp method.

For example, lets say you want to read the ‘User-Agent’ HTTP header inside a twirp server method. You might write this middleware:


use Psr\Http\Message\ServerRequestInterface;

// class UserAgentMiddleware...

public function handle(ServerRequestInterface $request)
    $request = $request->withAttribute('user-agent', $request->getHeaderLine('User-Agent'));

    return $this->server->handle($request);