class HTTPCacheControlMiddleware implements HTTPMiddleware, Resettable

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
defaultForcingLevel int Default forcing level
allowed_directives array A list of allowed cache directives for HTTPResponses

Methods

static Config_ForClass
config()

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

mixed
stat(string $name) deprecated

Get inherited config value

mixed
uninherited(string $name)

Gets the uninherited value for the given config option

$this
set_stat(string $name, mixed $value) deprecated

Update the config value for a given property

static Injectable
create(array $args)

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

static Injectable
singleton(string $class = null)

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

process(HTTPRequest $request, callable $delegate)

Generate response for the given request

array
getVary()

Get current vary keys

$this
addVary(string|array $vary)

Add a vary

$this
setVary(array|string $vary)

Set vary

registerModificationDate(string|int $date)

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

string
getState()

Get current state

$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.

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

Low level method to set directives from an associative array

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

Low level method for removing directives

bool
hasStateDirective(string $state, string $directive)

Low level method to check if a directive is currently set

bool
hasDirective(string $directive)

Check if the current state has the given directive.

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

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

bool|int|string
getDirective(string $directive)

Get the value of the given directive for the current state

array
getStateDirectives(string $state)

Get directives for the given state

array
getDirectives()

Get all directives for the currently active state

$this
setNoStore(bool $noStore = true)

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

$this
setNoCache(bool $noCache = true)

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

$this
setMaxAge(int $age)

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

$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.

$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.

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

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

$this
disableCache(bool $force = false)

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

$this
privateCache(bool $force = false)

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

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

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

$this
applyToResponse(HTTPResponse $response)

Generate all headers to add to this object

array
generateHeadersFor(HTTPResponse $response)

Generate all headers to output

static 
reset()

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

Details

in Configurable at line 20
static Config_ForClass config()

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

....).

Return Value

Config_ForClass

in Configurable at line 32
mixed stat(string $name) deprecated

deprecated 5.0 Use ->config()->get() instead

Get inherited config value

Parameters

string $name

Return Value

mixed

in Configurable at line 44
mixed uninherited(string $name)

Gets the uninherited value for the given config option

Parameters

string $name

Return Value

mixed

in Configurable at line 57
$this set_stat(string $name, mixed $value) deprecated

deprecated 5.0 Use ->config()->set() instead

Update the config value for a given property

Parameters

string $name
mixed $value

Return Value

$this

in Injectable at line 26
static Injectable create(array $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'); $list = SiteTree::get();

Parameters

array $args

Return Value

Injectable

in Injectable at line 43
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

at line 39
HTTPResponse process(HTTPRequest $request, callable $delegate)

Generate response for the given request

Parameters

HTTPRequest $request
callable $delegate

Return Value

HTTPResponse

Exceptions

HTTPResponse_Exception

at line 201
array getVary()

Get current vary keys

Return Value

array

at line 219
$this addVary(string|array $vary)

Add a vary

Parameters

string|array $vary

Return Value

$this

at line 232
$this setVary(array|string $vary)

Set vary

Parameters

array|string $vary

Return Value

$this

at line 266
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

at line 295
string getState()

Get current state

Return Value

string

at line 335
$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

at line 367
$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

at line 382
$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

at line 395
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

at line 407
bool hasDirective(string $directive)

Check if the current state has the given directive.

Parameters

string $directive

Return Value

bool

at line 421
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

at line 436
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

at line 447
array getStateDirectives(string $state)

Get directives for the given state

Parameters

string $state

Return Value

array

at line 457
array getDirectives()

Get all directives for the currently active state

Return Value

array

at line 471
$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

at line 492
$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

at line 515
$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

at line 535
$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

at line 554
$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

at line 575
$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/

at line 606
$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 precendence 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 diabled even if it's forced private or public

Return Value

$this

See also

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

at line 626
$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/

at line 647
$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/

at line 668
$this applyToResponse(HTTPResponse $response)

Generate all headers to add to this object

Parameters

HTTPResponse $response

Return Value

$this

at line 703
array generateHeadersFor(HTTPResponse $response)

Generate all headers to output

Parameters

HTTPResponse $response

Return Value

array

at line 716
static reset()

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