class HTTPCacheControlMiddleware implements HTTPMiddleware, Resettable (View source)

Traits

Provides extensions to this object to integrate it with standard config API methods.

A class that can be instantiated or replaced via DI

Constants

STATE_ENABLED

STATE_PUBLIC

STATE_PRIVATE

STATE_DISABLED

LEVEL_FORCED

Forcing level forced, optionally combined with one of the below.

LEVEL_DISABLED

Forcing level caching disabled. Overrides public/private.

LEVEL_PRIVATE

Forcing level private-cached. Overrides public.

LEVEL_PUBLIC

Forcing level public cached. Lowest priority.

LEVEL_ENABLED

Forcing level caching enabled.

Config options

defaultState string

Set default state

defaultVary array

Default vary

defaultForcingLevel int

Default forcing level

allowed_directives array

A list of allowed cache directives for HTTPResponses

Properties

protected array $stateDirectives

List of states, each of which contains a key of standard directives.

protected string $state

Current state

protected int $forcingLevel

Forcing level of previous setting; higher number wins Combination of consts below

protected array|null $vary

List of vary keys

protected int $modificationDate

Latest modification date for this response

Methods

public static 
config()

Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).

public
mixed
uninherited(string $name)

Gets the uninherited value for the given config option

public static 
create(mixed ...$args)

An implementation of the factory method, allows you to create an instance of a class

public static 
singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

public
process(HTTPRequest $request, callable $delegate)

Generate response for the given request

public
array
getVary()

Get current vary keys

public
$this
addVary(string|array $vary)

Add a vary

public
$this
setVary(array|string $vary)

Set vary

protected
array
combineVary(string|array[] ...$varies)

Combine vary strings/arrays into a single array, or normalise a single vary

public
registerModificationDate(string|int $date)

Register a modification date. Used to calculate the "Last-Modified" HTTP header.

protected
$this
setState(string $state)

Set current state. Should only be invoked internally after processing precedence rules.

public
string
getState()

Get current state

protected
bool
applyChangeLevel(int $level, bool $force)

Instruct the cache to apply a change with a given level, optionally modifying it with a force flag to increase priority of this action.

public
$this
setStateDirective(array|string $states, string $directive, int|string|bool $value = true)

Low level method for setting directives include any experimental or custom ones added via config.

public
$this
setStateDirectivesFromArray(array|string $states, array $directives)

Low level method to set directives from an associative array

public
$this
removeStateDirective(array|string $states, string $directive)

Low level method for removing directives

public
bool
hasStateDirective(string $state, string $directive)

Low level method to check if a directive is currently set

public
bool
hasDirective(string $directive)

Check if the current state has the given directive.

public
int|string|bool
getStateDirective(string $state, string $directive)

Low level method to get the value of a directive for a state.

public
bool|int|string
getDirective(string $directive)

Get the value of the given directive for the current state

public
array
getStateDirectives(string $state)

Get directives for the given state

public
array
getDirectives()

Get all directives for the currently active state

public
$this
setNoStore(bool $noStore = true)

The cache should not store anything about the client request or server response.

public
$this
setNoCache(bool $noCache = true)

Forces caches to submit the request to the origin server for validation before releasing a cached copy.

public
$this
setMaxAge(int $age)

Specifies the maximum amount of time (seconds) a resource will be considered fresh.

public
$this
setSharedMaxAge(int $age)

Overrides max-age or the Expires header, but it only applies to shared caches (e.g., proxies) and is ignored by a private cache.

public
$this
setMustRevalidate(bool $mustRevalidate = true)

The cache must verify the status of the stale resources before using it and expired ones should not be used.

public
$this
enableCache(bool $force = false, int $maxAge = null)

Simple way to set cache control header to a cacheable state.

public
$this
disableCache(bool $force = false)

Simple way to set cache control header to a non-cacheable state.

public
$this
privateCache(bool $force = false)

Advanced way to set cache control header to a non-cacheable state.

public
$this
publicCache(bool $force = false, int $maxAge = null)

Advanced way to set cache control header to a cacheable state.

public
$this
applyToResponse(HTTPResponse $response)

Generate all headers to add to this object

protected
string
generateCacheHeader()

Generate the cache header

public
array
generateHeadersFor(HTTPResponse $response)

Generate all headers to output

public static 
reset()

Reset registered http cache control and force a fresh instance to be built

protected
int
getForcingLevel()

No description

protected
string|null
generateVaryHeader(HTTPResponse $response)

Generate vary http header

protected
string|null
generateLastModifiedHeader()

Generate Last-Modified header

protected
null|string
generateExpiresHeader()

Generate Expires http header

protected
augmentState(HTTPRequest $request, HTTPResponse $response)

Update state based on current request and response objects

Details

static Config_ForClass config()

Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).

Return Value

Config_ForClass

mixed uninherited(string $name)

Gets the uninherited value for the given config option

Parameters

string $name

Return Value

mixed

static Injectable create(mixed ...$args)

An implementation of the factory method, allows you to create an instance of a class

This method will defer class substitution to the Injector API, which can be customised via the Config API to declare substitution classes.

This can be called in one of two ways - either calling via the class directly, or calling on Object and passing the class name as the first parameter. The following are equivalent: $list = DataList::create(SiteTree::class); $list = SiteTree::get();

Parameters

mixed ...$args

Return Value

Injectable

static Injectable singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

It will always return the same instance for this class, which can be used for performance reasons and as a simple way to access instance methods which don't rely on instance data (e.g. the custom SilverStripe static handling).

Parameters

string $class

Optional classname to create, if the called class should not be used

Return Value

Injectable

The singleton instance

HTTPResponse process(HTTPRequest $request, callable $delegate)

Generate response for the given request

Parameters

HTTPRequest $request
callable $delegate

Return Value

HTTPResponse

Exceptions

HTTPResponse_Exception

array getVary()

Get current vary keys

Return Value

array

$this addVary(string|array $vary)

Add a vary

Parameters

string|array $vary

Return Value

$this

$this setVary(array|string $vary)

Set vary

Parameters

array|string $vary

Return Value

$this

protected array combineVary(string|array[] ...$varies)

Combine vary strings/arrays into a single array, or normalise a single vary

Parameters

string|array[] ...$varies

Each vary as a separate arg

Return Value

array

HTTPCacheControlMiddleware registerModificationDate(string|int $date)

Register a modification date. Used to calculate the "Last-Modified" HTTP header.

Can be called multiple times, and will automatically retain the most recent date.

Parameters

string|int $date

Date string or timestamp

Return Value

HTTPCacheControlMiddleware

protected $this setState(string $state)

Set current state. Should only be invoked internally after processing precedence rules.

Parameters

string $state

Return Value

$this

string getState()

Get current state

Return Value

string

protected bool applyChangeLevel(int $level, bool $force)

Instruct the cache to apply a change with a given level, optionally modifying it with a force flag to increase priority of this action.

If the apply level was successful, the change is made and the internal level threshold is incremented.

Parameters

int $level

Priority of the given change

bool $force

If usercode has requested this action is forced to a higher priority. Note: Even if $force is set to true, other higher-priority forced changes can still cause a change to be rejected if it is below the required threshold.

Return Value

bool

True if the given change is accepted, and that the internal level threshold is updated (if necessary) to the new minimum level.

$this setStateDirective(array|string $states, string $directive, int|string|bool $value = true)

Low level method for setting directives include any experimental or custom ones added via config.

You need to specify the state (or states) to apply this directive to. Can also remove directives with false

Parameters

array|string $states

State(s) to apply this directive to

string $directive
int|string|bool $value

Flag to set for this value. Set to false to remove, or true to set. String or int value assign a specific value.

Return Value

$this

$this setStateDirectivesFromArray(array|string $states, array $directives)

Low level method to set directives from an associative array

Parameters

array|string $states

State(s) to apply this directive to

array $directives

Return Value

$this

$this removeStateDirective(array|string $states, string $directive)

Low level method for removing directives

Parameters

array|string $states

State(s) to remove this directive from

string $directive

Return Value

$this

bool hasStateDirective(string $state, string $directive)

Low level method to check if a directive is currently set

Parameters

string $state

State(s) to apply this directive to

string $directive

Return Value

bool

bool hasDirective(string $directive)

Check if the current state has the given directive.

Parameters

string $directive

Return Value

bool

int|string|bool getStateDirective(string $state, string $directive)

Low level method to get the value of a directive for a state.

Returns false if there is no directive. True means the flag is set, otherwise the value of the directive.

Parameters

string $state
string $directive

Return Value

int|string|bool

bool|int|string getDirective(string $directive)

Get the value of the given directive for the current state

Parameters

string $directive

Return Value

bool|int|string

array getStateDirectives(string $state)

Get directives for the given state

Parameters

string $state

Return Value

array

array getDirectives()

Get all directives for the currently active state

Return Value

array

$this setNoStore(bool $noStore = true)

The cache should not store anything about the client request or server response.

Affects all non-disabled states. Use setStateDirective() instead to set for a single state. Set the no-store directive (also removes max-age and s-maxage for consistency purposes)

Parameters

bool $noStore

Return Value

$this

$this setNoCache(bool $noCache = true)

Forces caches to submit the request to the origin server for validation before releasing a cached copy.

Affects all non-disabled states. Use setStateDirective() instead to set for a single state.

Parameters

bool $noCache

Return Value

$this

$this setMaxAge(int $age)

Specifies the maximum amount of time (seconds) a resource will be considered fresh.

This directive is relative to the time of the request. Affects all non-disabled states. Use enableCache(), publicCache() or setStateDirective() instead to set the max age for a single state.

Parameters

int $age

Return Value

$this

$this setSharedMaxAge(int $age)

Overrides max-age or the Expires header, but it only applies to shared caches (e.g., proxies) and is ignored by a private cache.

Affects all non-disabled states. Use setStateDirective() instead to set for a single state.

Parameters

int $age

Return Value

$this

$this setMustRevalidate(bool $mustRevalidate = true)

The cache must verify the status of the stale resources before using it and expired ones should not be used.

Affects all non-disabled states. Use setStateDirective() instead to set for a single state.

Parameters

bool $mustRevalidate

Return Value

$this

$this enableCache(bool $force = false, int $maxAge = null)

Simple way to set cache control header to a cacheable state.

Needs either setMaxAge() or the $maxAge method argument in order to activate caching.

The resulting cache-control headers will be chosen from the 'enabled' set of directives.

Does not set public directive. Usually, setMaxAge() is sufficient. Use publicCache() if this is explicitly required. See https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/http-caching#public_vs_private

Parameters

bool $force

Force the cache to public even if its unforced private or public

int $maxAge

Shortcut for setMaxAge(), which is required to actually enable the cache.

Return Value

$this

See also

https://docs.silverstripe.org/en/developer_guides/performance/http_cache_headers/

$this disableCache(bool $force = false)

Simple way to set cache control header to a non-cacheable state.

Use this method over privateCache() if you are unsure about caching details. Takes precedence over unforced enableCache(), privateCache() or publicCache() calls.

The resulting cache-control headers will be chosen from the 'disabled' set of directives.

Removes all state and replaces it with no-cache, no-store, must-revalidate. Although no-store is sufficient the others are added under recommendation from Mozilla (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#Examples)

Does not set private directive, use privateCache() if this is explicitly required. See https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/http-caching#public_vs_private

Parameters

bool $force

Force the cache to disabled even if it's forced private or public

Return Value

$this

See also

https://docs.silverstripe.org/en/developer_guides/performance/http_cache_headers/

$this privateCache(bool $force = false)

Advanced way to set cache control header to a non-cacheable state.

Indicates that the response is intended for a single user and must not be stored by a shared cache. A private cache (e.g. Web Browser) may store the response.

The resulting cache-control headers will be chosen from the 'private' set of directives.

Parameters

bool $force

Force the cache to private even if it's forced public

Return Value

$this

See also

https://docs.silverstripe.org/en/developer_guides/performance/http_cache_headers/

$this publicCache(bool $force = false, int $maxAge = null)

Advanced way to set cache control header to a cacheable state.

Indicates that the response may be cached by any cache. (eg: CDNs, Proxies, Web browsers). Needs either setMaxAge() or the $maxAge method argument in order to activate caching.

The resulting cache-control headers will be chosen from the 'private' set of directives.

Parameters

bool $force

Force the cache to public even if it's private, unless it's been forced private

int $maxAge

Shortcut for setMaxAge(), which is required to actually enable the cache.

Return Value

$this

See also

https://docs.silverstripe.org/en/developer_guides/performance/http_cache_headers/

$this applyToResponse(HTTPResponse $response)

Generate all headers to add to this object

Parameters

HTTPResponse $response

Return Value

$this

protected string generateCacheHeader()

Generate the cache header

Return Value

string

array generateHeadersFor(HTTPResponse $response)

Generate all headers to output

Parameters

HTTPResponse $response

Return Value

array

static reset()

Reset registered http cache control and force a fresh instance to be built

protected int getForcingLevel()

No description

Return Value

int

protected string|null generateVaryHeader(HTTPResponse $response)

Generate vary http header

Parameters

HTTPResponse $response

Return Value

string|null

protected string|null generateLastModifiedHeader()

Generate Last-Modified header

Return Value

string|null

protected null|string generateExpiresHeader()

Generate Expires http header

Return Value

null|string

protected augmentState(HTTPRequest $request, HTTPResponse $response)

Update state based on current request and response objects

Parameters

HTTPRequest $request
HTTPResponse $response