Response interface in Aerys

The Response interface generally finds its only use in responder callables (or Websocket::onOpen()). Middlewares do never see the Response; the StandardResponse class is communicating headers, data and flushes to a Generator under the hood.

setStatus(int $code): Response

Sets the numeric HTTP status code (between 100 and 599).

If not assigned this value defaults to 200.

setReason(string $phrase): Response

Sets the optional HTTP reason phrase.

addHeader(string $field, string $value): Response

Appends the specified header.

setHeader(string $field, string $value): Response

Sets the specified header.

This method will replace any existing headers for the specified field.

setCookie(string $name, string $value, array $flags = []): Response

Provides an easy API to set cookie headers.

Those who prefer using addHeader() may do so.

Valid $flags are per RFC 6265:

  • "Expires" => date("r", $timestamp) - A timestamp when the cookie will become invalid (set to a date in the past to delete it)
  • "Max-Age" => $seconds - A number in seconds when the cookie must be expired by the client
  • "Domain" => $domain - The domain where the cookie is available
  • "Path" => $path - The path the cookie is restricted to
  • "Secure" - Only send this cookie to the server over TLS
  • "HttpOnly" - The client must hide this cookie from any scripts (e.g. Javascript)

stream(string $partialBodyChunk): \Amp\Promise

Incrementally streams parts of the response body.

Applications that can afford to buffer an entire response in memory or can wait for all body data to generate may use Response::end() to output the entire response in a single call.

Note: Headers are sent upon the first invocation of Response::stream().

flush()

Forces a flush message [false inside Middlewares and HttpDriver] to be propagated and any buffers forwarded to the client.

Calling this method only makes sense when streaming output via Response::stream(). Invoking it before calling stream() or after end() is a logic error.

end(string $finalBodyChunk = null)

End any streaming response output with an optional final message by $finalBodyChunk.

User applications are not required to call Response::end() after streaming or sending response data (though it’s not incorrect to do so) — the server will automatically call end() as needed.

Passing the optional $finalBodyChunk parameter is a shortcut equivalent to the following:

$response->stream($finalBodyChunk);
$response->end();

Note: Thus it is also fine to call this function without previous stream() calls, to send it all at once.

push(string $url, array $headers = null): Response

Indicate resources which a client very likely needs to fetch. (e.g. Link: preload header or HTTP/2 Push Promises)

If a push promise is actually being sent, it will be dispatched with the $headers if not null, else the server will try to reuse some headers from the request

state(): int

Retrieves the current response state

The response state is a bitmask of the following flags:

  • Response::NONE
  • Response::STARTED
  • Response::STREAMING
  • Response::ENDED