Class AbstractStreamResponse

Base class for response types that stream an iterable payload to the client memory-efficiently.

Concrete subclasses such as {@see \Cake\Http\Response\JsonStreamResponse} produce the wire format (JSON, CSV, XML, …); this class owns the streaming lifecycle that is common to all of them:

Wires a {@see \Cake\Http\CallbackStream} into the response body.
Emits the streaming-friendly headers (Content-Type with charset and X-Accel-Buffering: no so proxies / nginx do not buffer the response).
Provides the {@see self::output()}, {@see self::outputAndFlush()} and {@see self::flushOutputBuffers()} primitives subclasses use to write the wire format, including the threshold-based flush counter driven by the flushEvery option.
Provides {@see self::logStreamError()} (gated on cakephp/log being installed) for surfacing encoding failures server-side.
Implements the PSR-7 immutability helpers ({@see self::withStreamOptions()} / {@see self::getStreamOptions()}).

Subclasses must implement {@see self::contentType()} (the MIME type without the charset suffix) and {@see self::streamData()} (the actual write loop). They may override {@see self::normalizeStreamOptions()} to validate format-specific options on top of the base validation.

Abstract
Namespace: Cake\Http\Response

Constants

int

STATUS_CODE_MAX ¶
```
599
```
int

STATUS_CODE_MIN ¶
```
100
```

Property Summary

$_cacheDirectives protected

array<string, mixed>

Holds all the cache directives that will be converted into headers when sending the response
$_charset protected

string

The charset the response body is encoded with
$_config protected

array<string, mixed>

Runtime config
$_configInitialized protected

bool

Whether the config property has already been configured with defaults
$_cookies protected

Cake\Http\Cookie\CookieCollection

Collection of cookies to send to the client
$_defaultConfig protected

array<string, mixed>

Default streaming options shared by all concrete subclasses.
$_file protected

SplFileInfo|null

File object for file to be read out as response
$_fileRange protected

array<int>

File range. Used for requesting ranges of files.
$_reasonPhrase protected

string

Reason Phrase
$_status protected

int

Status code to send to the client
$_statusCodes protected

array<int, string>

Allowed HTTP status codes and their default description.
$_streamMode protected

string

Stream mode options.
$_streamTarget protected

resource|string

Stream target or resource object.
$data protected

iterable

The iterable data to stream.
$headerNames protected

array

Map of normalized header name to original name used to register header.
$headers protected

array

List of all registered headers, as key => array of values.
$links protected

Psr\Link\EvolvableLinkProviderInterface

Collection of hypermedia links (PSR-13).
$rowsSinceLastFlush protected

int

Number of streamed rows since the last flush.

Method Summary

__construct() public

Constructor.
__debugInfo() public

Returns an array that can be used to describe the internal state of this object.
__toString() public

String conversion. Fetches the response body as a string. Does not send headers. If body is a callable, a blank string is returned.
_clearHeader() protected

Clear header
_configDelete() protected

Deletes a single config key.
_configRead() protected

Reads a config key.
_configWrite() protected

Writes a config key.
_createStream() protected

Creates the stream object.
_fileRange() protected

Apply a file range to a file and set the end offset.
_getUTCDate() protected

Returns a DateTime object initialized at the $time param and using UTC as timezone
_setCacheControl() protected

Helper method to generate a valid Cache-Control header from the options set in other methods
_setContentType() protected

Formats the Content-Type header based on the configured contentType and charset the charset will only be set in the header if the response is of type text/*
_setHeader() protected

Sets a header.
_setStatus() protected

Modifier for response status
applyStreamingHeaders() protected

Apply headers derived from the active stream options.
compress() public

Sets the correct output buffering handler to send a compressed response. Responses will be compressed with zlib, if the extension is available.
configShallow() public

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.
contentType() abstract protected

Return the response MIME type without the charset suffix.
cors() public

Get a CorsBuilder instance for defining CORS headers.
createStreamCallback() protected

Create the streaming callback installed on the response body.
deleteConfig() public

Deletes a config key.
flushOutputBuffers() protected

Flush output buffers when it is safe to do so.
getBody() public

Gets the body of the message.
getCharset() public

Returns the current charset.
getConfig() public

Returns the config.
getConfigOrFail() public

Returns the config for this specific key.
getCookie() public

Read a single cookie from the response.
getCookieCollection() public

Get the CookieCollection from the response
getCookies() public

Get all cookies in the response.
getFile() public

Get the current file if one exists.
getHeader() public

Retrieves a message header value by the given case-insensitive name.
getHeaderLine() public

Retrieves a comma-separated string of the values for a single header.
getHeaders() public

Retrieves all message headers.
getLinks() public

Get the link provider containing all hypermedia links.
getMimeType() public

Returns the mime type definition for an alias
getProtocolVersion() public

Retrieves the HTTP protocol version as a string.
getReasonPhrase() public

Gets the response reason phrase associated with the status code.
getRfc7231() protected

Converts the time zone to GMT and returns a string in RFC7231 format. This replaced the deprecated and broken DATE_RFC7231 formatting constant.
getStatusCode() public

Gets the response status code.
getStreamOptions() public

Get the streaming options.
getType() public

Returns the current content type.
hasHeader() public

Checks if a header exists by the given case-insensitive name.
isNotModified() public

Checks whether a response has not been modified according to the 'If-None-Match' (Etags) and 'If-Modified-Since' (last modification date) request headers.
logStreamError() protected

Log a streaming error.
mapType() public

Maps a content-type back to an alias
normalizeStreamOptions() protected

Validate and normalize the streaming options.
output() protected

Output data without flushing.
outputAndFlush() protected

Output data and flush to the client subject to the flushEvery threshold.
outputCompressed() public

Returns whether the resulting output will be compressed by PHP
resolveType() protected

Translate and validate content-types.
setConfig() public

Sets the config.
setTypeMap() public

Sets a content type definition into the map.
streamData() abstract protected

Write the streamed payload using {@see self::output()} / {@see self::outputAndFlush()}.
validateFile() protected

Validate a file path is a valid response body.
withAddedHeader() public

Return an instance with the specified header appended with the given value.
withAddedLink() public

Create a new response with the Link header set.
withBody() public

Return an instance with the specified message body.
withCache() public

Create a new instance with the headers to enable client caching.
withCharset() public

Get a new instance with an updated charset.
withCookie() public

Create a new response with a cookie set.
withCookieCollection() public

Get a new instance with provided cookie collection.
withDisabledCache() public

Create a new instance with headers to instruct the client to not cache the response
withDownload() public

Create a new instance with the Content-Disposition header set.
withEtag() public

Create a new instance with the Etag header set.
withExpiredCookie() public

Create a new response with an expired cookie set.
withExpires() public

Create a new instance with the Expires header set.
withFile() public

Create a new instance that is based on a file.
withHeader() public

Return an instance with the provided header, replacing any existing values of any headers with the same case-insensitive name.
withLength() public

Create a new response with the Content-Length header set.
withLink() public

Create a new response with a hypermedia link added.
withLinkProvider() public

Get a new instance with provided link provider.
withLocation() public

Return an instance with an updated location header.
withMaxAge() public

Create an instance with Cache-Control max-age directive set.
withModified() public

Create a new instance with the Last-Modified header set.
withMustRevalidate() public

Create an instance with Cache-Control must-revalidate directive set.
withNotModified() public

Create a new instance as 'not modified'
withProtocolVersion() public

Return an instance with the specified HTTP protocol version.
withSharable() public

Create a new instance with the public/private Cache-Control directive set.
withSharedMaxAge() public

Create a new instance with the Cache-Control s-maxage directive.
withStatus() public

Return an instance with the specified status code and, optionally, reason phrase.
withStreamOptions() public

Return an instance with updated streaming options.
withStringBody() public

Convenience method to set a string into the response body
withType() public

Get an updated response with the content type set.
withVary() public

Create a new instance with the Vary header set.
withoutHeader() public

Return an instance without the specified header.
withoutLink() public

Create a new response without a specific hypermedia link.

Method Detail

__construct() ¶ public

__construct(iterable $data, array<string, mixed> $options = [])

Constructor.

Parameters

iterable $data: The iterable data to stream (array, generator, ResultSet, etc.).
array<string, mixed> $options optional: Streaming options. The base accepts flushEvery (int >= 1) controlling how many items are buffered before flushing. Subclasses add their own keys.

__debugInfo() ¶ public

__debugInfo(): array<string, mixed>

Returns an array that can be used to describe the internal state of this object.

Returns

array<string, mixed>

__toString() ¶ public

__toString(): string

String conversion. Fetches the response body as a string. Does not send headers. If body is a callable, a blank string is returned.

Returns

string

_clearHeader() ¶ protected

_clearHeader(non-empty-string $header): void

Clear header

Parameters

non-empty-string $header: Header key.

Returns

void

_configDelete() ¶ protected

_configDelete(string $key): void

Deletes a single config key.

Parameters

string $key: Key to delete.

Returns

void

Throws

Cake\Core\Exception\CakeException
if attempting to clobber existing config

_configRead() ¶ protected

_configRead(string|null $key): $key is null ? array : mixed

Reads a config key.

Parameters

string|null $key: Key to read.

Returns

$key is null ? array : mixed

_configWrite() ¶ protected

_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void

Writes a config key.

Parameters

array<string, mixed>|string $key: Key to write to.
mixed $value: Value to write.
string|bool $merge optional: True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Returns

void

Throws

Cake\Core\Exception\CakeException
if attempting to clobber existing config

_createStream() ¶ protected

_createStream(): void

Creates the stream object.

Returns

void

_fileRange() ¶ protected

_fileRange(SplFileInfo $file, string $httpRange): void

Apply a file range to a file and set the end offset.

If an invalid range is requested a 416 Status code will be used in the response.

Parameters

SplFileInfo $file: The file to set a range on.
string $httpRange: The range to use.

Returns

void

_getUTCDate() ¶ protected

_getUTCDate(DateTimeInterface|string|int|null $time = null): DateTimeInterface

Returns a DateTime object initialized at the $time param and using UTC as timezone

Parameters

DateTimeInterface|string|int|null $time optional: Valid time string or \DateTimeInterface instance.

Returns

DateTimeInterface

_setCacheControl() ¶ protected

_setCacheControl(): void

Helper method to generate a valid Cache-Control header from the options set in other methods

Returns

void

_setContentType() ¶ protected

_setContentType(string $type): void

Formats the Content-Type header based on the configured contentType and charset the charset will only be set in the header if the response is of type text/*

Note: Content-Type header will be cleared for 304 and 204 status codes as these status codes must not have a Content-Type header.

Parameters

string $type: The type to set.

Returns

void

_setHeader() ¶ protected

_setHeader(non-empty-string $header, string $value): void

Sets a header.

Parameters

non-empty-string $header: Header key.
string $value: Header value.

Returns

void

_setStatus() ¶ protected

_setStatus(int $code, string $reasonPhrase = ''): void

Modifier for response status

Parameters

int $code: The status code to set.
string $reasonPhrase optional: The response reason phrase.

Returns

void

Throws

InvalidArgumentException
For invalid status code arguments.

applyStreamingHeaders() ¶ protected

applyStreamingHeaders(): void

Apply headers derived from the active stream options.

Sets the Content-Type (with charset) returned by {@see self::contentType()} and X-Accel-Buffering: no so reverse proxies do not buffer the body.

Returns

void

compress() ¶ public

compress(): bool

Sets the correct output buffering handler to send a compressed response. Responses will be compressed with zlib, if the extension is available.

Returns

bool

false if client does not accept compressed responses or no handler is available, true otherwise

configShallow() ¶ public

configShallow(array<string, mixed>|string $key, mixed|null $value = null): $this

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

array<string, mixed>|string $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.

Returns

$this

contentType() ¶ abstract protected

contentType(): string

Return the response MIME type without the charset suffix.

Called when applying streaming headers so subclasses can return a different value depending on the active stream options (e.g. JSON vs NDJSON share one response class but emit different content types).

Returns

string

cors() ¶ public

cors(Cake\Http\ServerRequest $request): Cake\Http\CorsBuilder

Get a CorsBuilder instance for defining CORS headers.

Parameters

Cake\Http\ServerRequest $request: Request object

Returns

Cake\Http\CorsBuilder

A builder object that provides a fluent interface for defining additional CORS headers.

createStreamCallback() ¶ protected

createStreamCallback(): Closure

Create the streaming callback installed on the response body.

Returns

Closure

deleteConfig() ¶ public

deleteConfig(string $key): $this

Deletes a config key.

Parameters

string $key: Key to delete. It can be a dot separated string to delete nested keys.

Returns

$this

flushOutputBuffers() ¶ protected

flushOutputBuffers(): void

Flush output buffers when it is safe to do so.

Only flushes at the implicit output buffer level (1) or when no buffering is active. Higher levels indicate explicit buffering (e.g. tests wrapping the call in ob_start()) which should not be disturbed.

Returns

void

getBody() ¶ public

getBody(): StreamInterface

Gets the body of the message.

Returns

StreamInterface

Returns the body as a stream.

getCharset() ¶ public

getCharset(): string

Returns the current charset.

Returns

string

getConfig() ¶ public

getConfig(string|null $key = null, mixed $default = null): $key is null ? array : mixed

Returns the config.

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

string|null $key optional: The key to get or null for the whole config.
mixed $default optional: The return value when the key does not exist.

Returns

$key is null ? array : mixed

Configuration data at the named key or null if the key does not exist.

getConfigOrFail() ¶ public

getConfigOrFail(string $key): mixed

Returns the config for this specific key.

The config value for this key must exist, it can never be null.

Parameters

string $key: The key to get.

Returns

mixed

Configuration data at the named key

Throws

InvalidArgumentException

getCookie() ¶ public

getCookie(string $name): array|null

Read a single cookie from the response.

This method provides read access to pending cookies. It will not read the Set-Cookie header if set.

Parameters

string $name: The cookie name you want to read.

Returns

array|null

Either the cookie data or null

getCookieCollection() ¶ public

getCookieCollection(): Cake\Http\Cookie\CookieCollection

Get the CookieCollection from the response

Returns

Cake\Http\Cookie\CookieCollection

getCookies() ¶ public

getCookies(): array<string, array>

Get all cookies in the response.

Returns an associative array of cookie name => cookie data.

Returns

array<string, array>

getFile() ¶ public

getFile(): SplFileInfo|null

Get the current file if one exists.

Returns

SplFileInfo|null

The file to use in the response or null

getHeader() ¶ public

getHeader(string $name): string[]

Retrieves a message header value by the given case-insensitive name.

This method returns an array of all the header values of the given case-insensitive header name.

If the header does not appear in the message, this method MUST return an empty array.

Parameters

string $name: Case-insensitive header field name.

Returns

string[]

An array of string values as provided for the given header. If the header does not appear in the message, this method MUST return an empty array.

getHeaderLine() ¶ public

getHeaderLine(string $name): string

Retrieves a comma-separated string of the values for a single header.

This method returns all of the header values of the given case-insensitive header name as a string concatenated together using a comma.

NOTE: Not all header values may be appropriately represented using comma concatenation. For such headers, use getHeader() instead and supply your own delimiter when concatenating.

If the header does not appear in the message, this method MUST return an empty string.

Parameters

string $name: Case-insensitive header field name.

Returns

string

A string of values as provided for the given header concatenated together using a comma. If the header does not appear in the message, this method MUST return an empty string.

getHeaders() ¶ public

getHeaders(): array

Retrieves all message headers.

The keys represent the header name as it will be sent over the wire, and each value is an array of strings associated with the header.

// Represent the headers as a string foreach ($message->getHeaders() as $name => $values) { echo $name . ": " . implode(", ", $values); }

// Emit headers iteratively: foreach ($message->getHeaders() as $name => $values) { foreach ($values as $value) { header(sprintf('%s: %s', $name, $value), false); } }

Returns

array

Returns an associative array of the message's headers. Each key MUST be a header name, and each value MUST be an array of strings.

getLinks() ¶ public

getLinks(): Psr\Link\EvolvableLinkProviderInterface

Get the link provider containing all hypermedia links.

Returns

Psr\Link\EvolvableLinkProviderInterface

getMimeType() ¶ public

getMimeType(string $alias): array|string|false

Returns the mime type definition for an alias

e.g getMimeType('pdf'); // returns 'application/pdf'

Parameters

string $alias: the content type alias to map

Returns

array|string|false

String mapped mime type or false if $alias is not mapped

getProtocolVersion() ¶ public

getProtocolVersion(): string

Retrieves the HTTP protocol version as a string.

The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").

Returns

string

HTTP protocol version.

getReasonPhrase() ¶ public

getReasonPhrase(): string

Gets the response reason phrase associated with the status code.

Because a reason phrase is not a required element in a response status line, the reason phrase value MAY be null. Implementations MAY choose to return the default RFC 7231 recommended reason phrase (or those listed in the IANA HTTP Status Code Registry) for the response's status code.

Returns

string

Reason phrase; must return an empty string if none present.

Links

https://tools.ietf.org/html/rfc7231#section-6

https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

getRfc7231() ¶ protected

getRfc7231(DateTimeInterface|string|int|null $time = null): string

Converts the time zone to GMT and returns a string in RFC7231 format. This replaced the deprecated and broken DATE_RFC7231 formatting constant.

Parameters

DateTimeInterface|string|int|null $time optional

Returns

string

getStatusCode() ¶ public

getStatusCode(): int

Gets the response status code.

The status code is a 3-digit integer result code of the server's attempt to understand and satisfy the request.

Returns

int

Status code.

getStreamOptions() ¶ public

getStreamOptions(): array<string, mixed>

Get the streaming options.

Returns

array<string, mixed>

getType() ¶ public

getType(): string

Returns the current content type.

Returns

string

hasHeader() ¶ public

hasHeader(string $name): bool

Checks if a header exists by the given case-insensitive name.

Parameters

string $name: Case-insensitive header name.

Returns

bool

Returns true if any header names match the given header name using a case-insensitive string comparison. Returns false if no matching header name is found in the message.

isNotModified() ¶ public

isNotModified(Cake\Http\ServerRequest $request): bool

Checks whether a response has not been modified according to the 'If-None-Match' (Etags) and 'If-Modified-Since' (last modification date) request headers.

In order to interact with this method you must mark responses as not modified. You need to set at least one of the Last-Modified or Etag response headers before calling this method. Otherwise, a comparison will not be possible.

Parameters

Cake\Http\ServerRequest $request: Request object

Returns

bool

Whether the response is 'modified' based on cache headers.

logStreamError() ¶ protected

logStreamError(string $message, int $index): void

Log a streaming error.

No-op when cakephp/log is not installed (keeps the dependency optional for the cakephp/http package).

Parameters

string $message: Error message.
int $index: Item index where the error occurred.

Returns

void

mapType() ¶ public

mapType(array|string $ctype): array|string|null

Maps a content-type back to an alias

e.g mapType('application/pdf'); // returns 'pdf'

Parameters

array|string $ctype: Either a string content type to map, or an array of types.

Returns

array|string|null

Aliases for the types provided.

normalizeStreamOptions() ¶ protected

normalizeStreamOptions(array<string, mixed> $options, array<string, mixed> $originalOptions = []): array<string, mixed>

Validate and normalize the streaming options.

Subclasses overriding this method should call parent::normalizeStreamOptions() so the shared options (currently flushEvery) keep their validation.

Parameters

array<string, mixed> $options: Merged options.
array<string, mixed> $originalOptions optional: Original options passed by the caller.

Returns

array<string, mixed>

output() ¶ protected

output(string $data): void

Output data without flushing.

Used for structural bytes like wrapper brackets / separators that do not need an immediate flush.

Parameters

string $data: The data to output.

Returns

void

outputAndFlush() ¶ protected

outputAndFlush(string $data, bool $force = false): void

Output data and flush to the client subject to the flushEvery threshold.

Parameters

string $data: The data to output and flush.
bool $force optional: Whether to force an immediate flush regardless of threshold.

Returns

void

outputCompressed() ¶ public

outputCompressed(): bool

Returns whether the resulting output will be compressed by PHP

Returns

bool

resolveType() ¶ protected

resolveType(string $contentType): string

Translate and validate content-types.

Parameters

string $contentType: The content-type or type alias.

Returns

string

The resolved content-type

Throws

InvalidArgumentException
When an invalid content-type or alias is used.

setConfig() ¶ public

setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $this

Sets the config.

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

array<string, mixed>|string $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.
bool $merge optional: Whether to recursively merge or overwrite existing config, defaults to true.

Returns

$this

Throws

Cake\Core\Exception\CakeException
When trying to set a key that is invalid.

setTypeMap() ¶ public

setTypeMap(string $type, array<string>|string $mimeType): void

Sets a content type definition into the map.

E.g.: setTypeMap('xhtml', ['application/xhtml+xml', 'application/xhtml'])

This is needed for RequestHandlerComponent and recognition of types.

Parameters

string $type: Content type.
array<string>|string $mimeType: Definition of the mime type.

Returns

void

streamData() ¶ abstract protected

streamData(): void

Write the streamed payload using {@see self::output()} / {@see self::outputAndFlush()}.

Called from the response body callback. Subclasses own the wire format, including any wrapper bytes, item separators and end-of-stream handling.

Returns

void

validateFile() ¶ protected

validateFile(string $path): SplFileInfo

Validate a file path is a valid response body.

Parameters

string $path: The path to the file.

Returns

SplFileInfo

Throws

Cake\Http\Exception\NotFoundException

withAddedHeader() ¶ public

withAddedHeader(string $name, string|string[] $value): static

Return an instance with the specified header appended with the given value.

Existing values for the specified header will be maintained. The new value(s) will be appended to the existing list. If the header did not exist previously, it will be added.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the new header and/or value.

Parameters

string $name: Case-insensitive header field name to add.
string|string[] $value: Header value(s).

Returns

static

Throws

Exception\InvalidArgumentException
For invalid header names or values.

withAddedLink() ¶ public

withAddedLink(string $url, array<string, mixed> $options = []): static

Create a new response with the Link header set.

Examples

$response = $response->withAddedLink('http://example.com?page=1', ['rel' => 'prev'])
    ->withAddedLink('http://example.com?page=3', ['rel' => 'next']);

Will generate:

Link: <http://example.com?page=1>; rel="prev"
Link: <http://example.com?page=3>; rel="next"

Parameters

string $url: The LinkHeader url.
array<string, mixed> $options optional: The LinkHeader params.

Returns

static

withBody() ¶ public

withBody(StreamInterface $body): static

Return an instance with the specified message body.

The body MUST be a StreamInterface object.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return a new instance that has the new body stream.

Parameters

StreamInterface $body: Body.

Returns

static

Throws

Exception\InvalidArgumentException
When the body is not valid.

withCache() ¶ public

withCache(string|int $since, string|int $time = '+1 day'): static

Create a new instance with the headers to enable client caching.

Parameters

string|int $since: a valid time since the response text has not been modified
string|int $time optional: a valid time for cache expiry

Returns

static

withCharset() ¶ public

withCharset(string $charset): static

Get a new instance with an updated charset.

Parameters

string $charset: Character set string.

Returns

static

withCookie() ¶ public

withCookie(Cake\Http\Cookie\CookieInterface $cookie): static

Create a new response with a cookie set.

Example

// add a cookie object
$response = $response->withCookie(new Cookie('remember_me', 1));

Parameters

Cake\Http\Cookie\CookieInterface $cookie: cookie object

Returns

static

withCookieCollection() ¶ public

withCookieCollection(Cake\Http\Cookie\CookieCollection $cookieCollection): static

Get a new instance with provided cookie collection.

Parameters

Cake\Http\Cookie\CookieCollection $cookieCollection: Cookie collection to set.

Returns

static

withDisabledCache() ¶ public

withDisabledCache(): static

Create a new instance with headers to instruct the client to not cache the response

Returns

static

withDownload() ¶ public

withDownload(string $filename): static

Create a new instance with the Content-Disposition header set.

Parameters

string $filename: The name of the file as the browser will download the response

Returns

static

withEtag() ¶ public

withEtag(string $hash, bool $weak = false): static

Create a new instance with the Etag header set.

Etags are a strong indicative that a response can be cached by a HTTP client. A bad way of generating Etags is creating a hash of the response output, instead generate a unique hash of the unique components that identifies a request, such as a modification time, a resource Id, and anything else you consider it that makes the response unique.

The second parameter is used to inform clients that the content has changed, but semantically it is equivalent to existing cached values. Consider a page with a hit counter, two different page views are equivalent, but they differ by a few bytes. This permits the Client to decide whether they should use the cached data.

Parameters

string $hash: The unique hash that identifies this response
bool $weak optional: Whether the response is semantically the same as other with the same hash or not. Defaults to false

Returns

static

withExpiredCookie() ¶ public

withExpiredCookie(Cake\Http\Cookie\CookieInterface $cookie): static

Create a new response with an expired cookie set.

Example

// add a cookie object
$response = $response->withExpiredCookie(new Cookie('remember_me'));

Parameters

Cake\Http\Cookie\CookieInterface $cookie: cookie object

Returns

static

withExpires() ¶ public

withExpires(DateTimeInterface|string|int|null $time): static

Create a new instance with the Expires header set.

Strings without an explicit time zone will be converted from the default time zone to UTC.

Examples:

// Will Expire the response cache now
$response->withExpires('now')

// Will set the expiration in next 24 hours
$response->withExpires(new DateTime('+1 day'))

Parameters

DateTimeInterface|string|int|null $time: Valid time string or \DateTime instance.

Returns

static

withFile() ¶ public

withFile(string $path, array<string, mixed> $options = []): static

Create a new instance that is based on a file.

This method will augment both the body and a number of related headers.

If $_SERVER['HTTP_RANGE'] is set, a slice of the file will be returned instead of the entire file.

Options keys

name: Alternate download name
download: If true sets download header and forces file to be downloaded rather than displayed inline.

Parameters

string $path: Absolute path to file.
array<string, mixed> $options optional: Options See above.

Returns

static

Throws

Cake\Http\Exception\NotFoundException

withHeader() ¶ public

withHeader(string $name, string|string[] $value): static

Return an instance with the provided header, replacing any existing values of any headers with the same case-insensitive name.

While header names are case-insensitive, the casing of the header will be preserved by this function, and returned from getHeaders().

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the new and/or updated header and value.

Parameters

string $name: Case-insensitive header field name.
string|string[] $value: Header value(s).

Returns

static

Throws

Exception\InvalidArgumentException
For invalid header names or values.

withLength() ¶ public

withLength(string|int $bytes): static

Create a new response with the Content-Length header set.

Parameters

string|int $bytes: Number of bytes

Returns

static

withLink() ¶ public

withLink(Psr\Link\LinkInterface $link): static

Create a new response with a hypermedia link added.

Example

use Cake\Http\Link\Link;

$response = $response->withLink(new Link('/api/users', 'self'));
$response = $response->withLink(
    (new Link('/css/app.css'))
        ->withRel('preload')
        ->withAttribute('as', 'style')
);

Parameters

Psr\Link\LinkInterface $link: The link to add.

Returns

static

withLinkProvider() ¶ public

withLinkProvider(Psr\Link\EvolvableLinkProviderInterface $links): static

Get a new instance with provided link provider.

Parameters

Psr\Link\EvolvableLinkProviderInterface $links: Link provider to set.

Returns

static

withLocation() ¶ public

withLocation(string $url): static

Return an instance with an updated location header.

If the current status code is 200, it will be replaced with 302.

Parameters

string $url: The location to redirect to.

Returns

static

A new response with the Location header set.

withMaxAge() ¶ public

withMaxAge(int $seconds): static

Create an instance with Cache-Control max-age directive set.

The max-age is the number of seconds after which the response should no longer be considered a good candidate to be fetched from the local (client) cache.

Parameters

int $seconds: The seconds a cached response can be considered valid

Returns

static

withModified() ¶ public

withModified(DateTimeInterface|string|int $time): static

Create a new instance with the Last-Modified header set.

Strings without an explicit time zone will be converted from the default time zone to UTC.

Examples:

// Will Expire the response cache now
$response->withModified('now')

// Will set the expiration in next 24 hours
$response->withModified(new DateTime('+1 day'))

Parameters

DateTimeInterface|string|int $time: Valid time string or \DateTime instance.

Returns

static

withMustRevalidate() ¶ public

withMustRevalidate(bool $enable): static

Create an instance with Cache-Control must-revalidate directive set.

Sets the Cache-Control must-revalidate directive. must-revalidate indicates that the response should not be served stale by a cache under any circumstance without first revalidating with the origin.

Parameters

bool $enable: If boolean sets or unsets the directive.

Returns

static

withNotModified() ¶ public

withNotModified(): static

Create a new instance as 'not modified'

This will remove any body contents set the status code to "304" and removing headers that describe a response body.

Returns

static

withProtocolVersion() ¶ public

withProtocolVersion(string $version): static

Return an instance with the specified HTTP protocol version.

The version string MUST contain only the HTTP version number (e.g., "1.1", "1.0").

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the new protocol version.

Parameters

string $version: HTTP protocol version

Returns

static

withSharable() ¶ public

withSharable(bool $public, int|null $time = null): static

Create a new instance with the public/private Cache-Control directive set.

Parameters

bool $public: If set to true, the Cache-Control header will be set as public if set to false, the response will be set to private.
int|null $time optional: time in seconds after which the response should no longer be considered fresh.

Returns

static

withSharedMaxAge() ¶ public

withSharedMaxAge(int $seconds): static

Create a new instance with the Cache-Control s-maxage directive.

The max-age is the number of seconds after which the response should no longer be considered a good candidate to be fetched from a shared cache (like in a proxy server).

Parameters

int $seconds: The number of seconds for shared max-age

Returns

static

withStatus() ¶ public

withStatus(int $code, string $reasonPhrase = ''): static

Return an instance with the specified status code and, optionally, reason phrase.

If no reason phrase is specified, implementations MAY choose to default to the RFC 7231 or IANA recommended reason phrase for the response's status code.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the updated status and reason phrase.

If the status code is 304 or 204, the existing Content-Type header will be cleared, as these response codes have no body.

There are external packages such as fig/http-message-util that provide HTTP status code constants. These can be used with any method that accepts or returns a status code integer. However, keep in mind that these constants might include status codes that are not allowed which will throw an \InvalidArgumentException.

Parameters

int $code: The 3-digit integer status code to set.
string $reasonPhrase optional: The reason phrase to use with the provided status code; if none is provided, implementations MAY use the defaults as suggested in the HTTP specification.

Returns

static

Throws

InvalidArgumentException
For invalid status code arguments.

Links

https://tools.ietf.org/html/rfc7231#section-6

https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

withStreamOptions() ¶ public

withStreamOptions(array<string, mixed> $options): static

Return an instance with updated streaming options.

The body callback is rebuilt so the new instance streams using the updated options.

Parameters

array<string, mixed> $options: Options to merge with existing options.

Returns

static

withStringBody() ¶ public

withStringBody(string|null $string): static

Convenience method to set a string into the response body

Parameters

string|null $string: The string to be sent

Returns

static

withType() ¶ public

withType(string $contentType): static

Get an updated response with the content type set.

If you attempt to set the type on a 304 or 204 status code response, the content type will not take effect as these status codes do not have content-types.

Parameters

string $contentType: Either a file extension which will be mapped to a mime-type or a concrete mime-type.

Returns

static

withVary() ¶ public

withVary(array<string>|string $cacheVariances): static

Create a new instance with the Vary header set.

If an array is passed values will be imploded into a comma separated string. If no parameters are passed, then an array with the current Vary header value is returned

Parameters

array<string>|string $cacheVariances: A single Vary string or an array containing the list for variances.

Returns

static

withoutHeader() ¶ public

withoutHeader(string $name): static

Return an instance without the specified header.

Header resolution MUST be done without case-sensitivity.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that removes the named header.

Parameters

string $name: Case-insensitive header field name to remove.

Returns

static

withoutLink() ¶ public

withoutLink(Psr\Link\LinkInterface $link): static

Create a new response without a specific hypermedia link.

Parameters

Psr\Link\LinkInterface $link: The link to remove.

Returns

static

Property Detail

`$_cacheDirectives` ¶ protected

Holds all the cache directives that will be converted into headers when sending the response

Type

array<string, mixed>

`$_charset` ¶ protected

The charset the response body is encoded with

Type

string

`$_config` ¶ protected

Runtime config

Type

array<string, mixed>

`$_configInitialized` ¶ protected

Whether the config property has already been configured with defaults

Type

bool

`$_cookies` ¶ protected

Collection of cookies to send to the client

Type

Cake\Http\Cookie\CookieCollection

`$_defaultConfig` ¶ protected

Default streaming options shared by all concrete subclasses.

Subclasses extend this array with their format-specific options.

Type

array<string, mixed>

`$_file` ¶ protected

File object for file to be read out as response

Type

SplFileInfo|null

`$_fileRange` ¶ protected

File range. Used for requesting ranges of files.

Type

array<int>

`$_reasonPhrase` ¶ protected

Reason Phrase

Type

string

`$_status` ¶ protected

Status code to send to the client

Type

int

`$_statusCodes` ¶ protected

Allowed HTTP status codes and their default description.

Type

array<int, string>

`$_streamMode` ¶ protected

Stream mode options.

Type

string

`$_streamTarget` ¶ protected

Stream target or resource object.

Type

resource|string

`$data` ¶ protected

The iterable data to stream.

Type

iterable

`$headerNames` ¶ protected

Map of normalized header name to original name used to register header.

Type

array

`$headers` ¶ protected

List of all registered headers, as key => array of values.

Type

array

`$links` ¶ protected

Collection of hypermedia links (PSR-13).

Type

Psr\Link\EvolvableLinkProviderInterface

`$rowsSinceLastFlush` ¶ protected

Number of streamed rows since the last flush.

Type

int

Namespaces

Class AbstractStreamResponse

Constants

Property Summary

Method Summary

__construct() public

__debugInfo() public

__toString() public

_clearHeader() protected

_configDelete() protected

_configRead() protected

_configWrite() protected

_createStream() protected

_fileRange() protected

_getUTCDate() protected

_setCacheControl() protected

_setContentType() protected

_setHeader() protected

_setStatus() protected

applyStreamingHeaders() protected

compress() public

configShallow() public

contentType() abstract protected

cors() public

createStreamCallback() protected

deleteConfig() public

flushOutputBuffers() protected

getBody() public

getCharset() public

getConfig() public

getConfigOrFail() public

getCookie() public

getCookieCollection() public

getCookies() public

getFile() public

getHeader() public

getHeaderLine() public

getHeaders() public

getLinks() public

getMimeType() public

getProtocolVersion() public

getReasonPhrase() public

getRfc7231() protected

getStatusCode() public

getStreamOptions() public

getType() public

hasHeader() public

isNotModified() public

logStreamError() protected

mapType() public

normalizeStreamOptions() protected

output() protected

outputAndFlush() protected

outputCompressed() public

resolveType() protected

setConfig() public

setTypeMap() public

streamData() abstract protected

validateFile() protected

withAddedHeader() public

withAddedLink() public

withBody() public

withCache() public

withCharset() public

withCookie() public

withCookieCollection() public

withDisabledCache() public

withDownload() public

withEtag() public

withExpiredCookie() public

withExpires() public

withFile() public

withHeader() public

withLength() public

withLink() public

withLinkProvider() public

withLocation() public

withMaxAge() public

withModified() public

withMustRevalidate() public