Documentation

HttpCache
in package
implements HttpKernelInterface, TerminableInterface

Cache provides HTTP caching.

Tags
author

Fabien Potencier fabien@symfony.com

Interfaces, Classes and Traits

HttpKernelInterface
HttpKernelInterface handles a Request to convert it to a Response.
TerminableInterface
Terminable extends the Kernel request/response cycle with dispatching a post response event after sending the response and before shutting down the kernel.

Table of Contents

BODY_EVAL_BOUNDARY_LENGTH  = 24
$kernel  : mixed
$options  : mixed
$request  : mixed
$store  : mixed
$surrogate  : mixed
$surrogateCacheStrategy  : mixed
$traces  : mixed
__construct()  : mixed
Constructor.
getKernel()  : HttpKernelInterface
Gets the Kernel instance.
getLog()  : string
Returns a log message for the events of the last request processing.
getRequest()  : Request
Gets the Request instance associated with the main request.
getStore()  : StoreInterface
Gets the current store.
getSurrogate()  : SurrogateInterface
Gets the Surrogate instance.
getTraces()  : array<string|int, mixed>
Returns an array of events that took place during processing of the last request.
handle()  : Response
Handles a Request to convert it to a Response.
terminate()  : mixed
Terminates a request/response cycle.
fetch()  : Response
Unconditionally fetches a fresh response from the backend and stores it in the cache if is cacheable.
forward()  : Response
Forwards the Request to the backend and returns the Response.
invalidate()  : Response
Invalidates non-safe methods (like POST, PUT, and DELETE).
isFreshEnough()  : bool
Checks whether the cache entry is "fresh enough" to satisfy the Request.
lock()  : bool
Locks a Request during the call to the backend.
lookup()  : Response
Lookups a Response from the cache for the given Request.
pass()  : Response
Forwards the Request to the backend without storing the Response in the cache.
processResponseBody()  : mixed
store()  : mixed
Writes the Response to the cache.
validate()  : Response
Validates that a cache entry is fresh.
addTraces()  : mixed
getTraceKey()  : string
Calculates the key we use in the "trace" array for a given request.
isPrivateRequest()  : bool
Checks if the Request includes authorization or other sensitive information that should cause the Response to be considered private by default.
mayServeStaleWhileRevalidate()  : bool
Checks whether the given (cached) response may be served as "stale" when a revalidation is currently in progress.
record()  : mixed
Records that an event took place.
restoreResponseBody()  : mixed
Restores the Response body.
waitForLock()  : bool
Waits for the store to release a locked entry.

Constants

BODY_EVAL_BOUNDARY_LENGTH

public mixed BODY_EVAL_BOUNDARY_LENGTH = 24

Properties

$surrogateCacheStrategy

private mixed $surrogateCacheStrategy

Methods

__construct()

Constructor.

public __construct(HttpKernelInterface $kernel, StoreInterface $store[, SurrogateInterface|null $surrogate = null ][, array<string|int, mixed> $options = [] ]) : mixed

The available options are:

  • debug If true, exceptions are thrown when things go wrong. Otherwise, the cache will try to carry on and deliver a meaningful response.

  • trace_level May be one of 'none', 'short' and 'full'. For 'short', a concise trace of the main request will be added as an HTTP header. 'full' will add traces for all requests (including ESI subrequests). (default: 'full' if in debug; 'none' otherwise)

  • trace_header Header name to use for traces. (default: X-Symfony-Cache)

  • default_ttl The number of seconds that a cache entry should be considered fresh when no explicit freshness information is provided in a response. Explicit Cache-Control or Expires headers override this value. (default: 0)

  • private_headers Set of request headers that trigger "private" cache-control behavior on responses that don't explicitly state whether the response is public or private via a Cache-Control directive. (default: Authorization and Cookie)

  • allow_reload Specifies whether the client can force a cache reload by including a Cache-Control "no-cache" directive in the request. Set it to true for compliance with RFC 2616. (default: false)

  • allow_revalidate Specifies whether the client can force a cache revalidate by including a Cache-Control "max-age=0" directive in the request. Set it to true for compliance with RFC 2616. (default: false)

  • stale_while_revalidate Specifies the default number of seconds (the granularity is the second as the Response TTL precision is a second) during which the cache can immediately return a stale response while it revalidates it in the background (default: 2). This setting is overridden by the stale-while-revalidate HTTP Cache-Control extension (see RFC 5861).

  • stale_if_error Specifies the default number of seconds (the granularity is the second) during which the cache can serve a stale response when an error is encountered (default: 60). This setting is overridden by the stale-if-error HTTP Cache-Control extension (see RFC 5861).

Parameters
$kernel : HttpKernelInterface
$store : StoreInterface
$surrogate : SurrogateInterface|null = null
$options : array<string|int, mixed> = []
Return values
mixed —

getLog()

Returns a log message for the events of the last request processing.

public getLog() : string
Return values
string —

getRequest()

Gets the Request instance associated with the main request.

public getRequest() : Request
Return values
Request —

getTraces()

Returns an array of events that took place during processing of the last request.

public getTraces() : array<string|int, mixed>
Return values
array<string|int, mixed> —

handle()

Handles a Request to convert it to a Response.

public handle(Request $request[, int $type = HttpKernelInterface::MAIN_REQUEST ][, bool $catch = true ]) : Response
Parameters
$request : Request
$type : int = HttpKernelInterface::MAIN_REQUEST

The type of the request (one of HttpKernelInterface::MAIN_REQUEST or HttpKernelInterface::SUB_REQUEST)

$catch : bool = true

Whether to catch exceptions or not

Return values
Response —

fetch()

Unconditionally fetches a fresh response from the backend and stores it in the cache if is cacheable.

protected fetch(Request $request[, bool $catch = false ]) : Response
Parameters
$request : Request
$catch : bool = false

Whether to process exceptions

Return values
Response —

forward()

Forwards the Request to the backend and returns the Response.

protected forward(Request $request[, bool $catch = false ][, Response|null $entry = null ]) : Response

All backend requests (cache passes, fetches, cache validations) run through this method.

Parameters
$request : Request
$catch : bool = false

Whether to catch exceptions or not

$entry : Response|null = null

A Response instance (the stale entry if present, null otherwise)

Return values
Response —

invalidate()

Invalidates non-safe methods (like POST, PUT, and DELETE).

protected invalidate(Request $request[, bool $catch = false ]) : Response
Parameters
$request : Request
$catch : bool = false

Whether to process exceptions

Tags
throws
Exception
see
RFC2616

13.10

Return values
Response —

isFreshEnough()

Checks whether the cache entry is "fresh enough" to satisfy the Request.

protected isFreshEnough(Request $request, Response $entry) : bool
Parameters
$request : Request
$entry : Response
Return values
bool —

lock()

Locks a Request during the call to the backend.

protected lock(Request $request, Response $entry) : bool
Parameters
$request : Request
$entry : Response
Return values
bool —

true if the cache entry can be returned even if it is staled, false otherwise

lookup()

Lookups a Response from the cache for the given Request.

protected lookup(Request $request[, bool $catch = false ]) : Response

When a matching cache entry is found and is fresh, it uses it as the response without forwarding any request to the backend. When a matching cache entry is found but is stale, it attempts to "validate" the entry with the backend using conditional GET. When no matching cache entry is found, it triggers "miss" processing.

Parameters
$request : Request
$catch : bool = false

Whether to process exceptions

Tags
throws
Exception
Return values
Response —

pass()

Forwards the Request to the backend without storing the Response in the cache.

protected pass(Request $request[, bool $catch = false ]) : Response
Parameters
$request : Request
$catch : bool = false

Whether to process exceptions

Return values
Response —

store()

Writes the Response to the cache.

protected store(Request $request, Response $response) : mixed
Parameters
$request : Request
$response : Response
Tags
throws
Exception
Return values
mixed —

validate()

Validates that a cache entry is fresh.

protected validate(Request $request, Response $entry[, bool $catch = false ]) : Response

The original request is used as a template for a conditional GET request with the backend.

Parameters
$request : Request
$entry : Response
$catch : bool = false

Whether to process exceptions

Return values
Response —

getTraceKey()

Calculates the key we use in the "trace" array for a given request.

private getTraceKey(Request $request) : string
Parameters
$request : Request
Return values
string —

isPrivateRequest()

Checks if the Request includes authorization or other sensitive information that should cause the Response to be considered private by default.

private isPrivateRequest(Request $request) : bool
Parameters
$request : Request
Return values
bool —

mayServeStaleWhileRevalidate()

Checks whether the given (cached) response may be served as "stale" when a revalidation is currently in progress.

private mayServeStaleWhileRevalidate(Response $entry) : bool
Parameters
$entry : Response
Return values
bool —

record()

Records that an event took place.

private record(Request $request, string $event) : mixed
Parameters
$request : Request
$event : string
Return values
mixed —

restoreResponseBody()

Restores the Response body.

private restoreResponseBody(Request $request, Response $response) : mixed
Parameters
$request : Request
$response : Response
Return values
mixed —

waitForLock()

Waits for the store to release a locked entry.

private waitForLock(Request $request) : bool
Parameters
$request : Request
Return values
bool —

Search results