\midcom_services_cache_module_content

This is the Output Caching Engine of MidCOM. It will intercept page output, map it using the currently used URL and use the cached output on subsequent requests.

Important note for application developers

Please read the documentation of the following functions thoroughly:

  • midcom_services_cache_module_content::no_cache();
  • midcom_services_cache_module_content::uncached();
  • midcom_services_cache_module_content::expires();
  • midcom_services_cache_module_content::invalidate_all();
  • midcom_services_cache_module_content::content_type();
  • midcom_services_cache_module_content::enable_live_mode();

You have to use these functions everywhere where it is applicable or the cache will not work reliably.

Caching strategy

The cache takes three parameters into account when storing in or retrieving from the cache: The current User ID, the current language and the request's URL.

Only on a complete match a cached page is displayed, which should take care of any permission checks done on the page. When you change the permissions of users, you need to manually invalidate the cache though, as MidCOM currently cannot detect changes like this (of course, this is true if and only if you are not using a MidCOM to change permissions).

When the HTTP request is not cacheable, the caching engine will automatically and transparently go into no_cache mode for that request only. This feature does neither invalidate the cache or drop the page that would have been delivered normally from the cache. If you change the content, you need to do that yourself.

HTTP 304 Not Modified support is built into this module, and it will kill the output buffer and send a 304 reply if applicable.

Internal notes

This module's startup code will exit with _midcom_stop_request() in case of a cache hit, and it will enclose the entire request using PHP's output buffering.

Module configuration (see also midcom_config)

  • string cache_module_content_name: The name of the cache database to use. This should usually be tied to the actual MidCOM site to have exactly one cache per site. This is mandatory (and populated by a sensible default by midcom_config, see there for details).
  • boolean cache_module_content_uncached: Set this to true to prevent the saving of cached pages. This is useful for development work, as all other headers (like E-Tag or Last-Modified) are generated normally. See the uncached() and _uncached members.

Summary

Methods
Properties
Constants
initialize()
shutdown()
_on_initialize()
_on_shutdown()
invalidate_all()
invalidate()
start_caching()
no_cache()
uncached()
expires()
content_type()
enable_live_mode()
disable_ob()
register_sent_header()
register()
finish_caching()
write_meta_cache()
check_dl_hit()
store_dl_content()
cache_control_headers()
No public properties found
No constants found
_create_backend()
$_backends
$_prefix
N/A
prepare_backend()
generate_request_identifier()
get_strategy()
_check_hit()
store_context_guid_map()
apply_headers()
complete_sent_headers()
$_no_cache
$_expires
$_last_modified
$_sent_headers
$_content_type
$_obrunning
$_live_mode
$_uncached
$_headers_strategy
$_headers_strategy_authenticated
$_default_lifetime
$_default_lifetime_authenticated
$_meta_cache
$_data_cache
$context_guids
$_force_headers
N/A

Properties

$_backends

$_backends : array<mixed,\Doctrine\Common\Cache\CacheProvider>

A list of all backends created by _create_backend(). They will be automatically shut down when the module shuts down. They are indexed by their name.

Type

array<mixed,\Doctrine\Common\Cache\CacheProvider>

$_prefix

$_prefix : string

The cache key prefix.

Type

string

$_no_cache

$_no_cache : boolean

Flag, indicating whether the current page may be cached. If false, the usual no-cache headers will be generated.

Type

boolean

$_expires

$_expires : integer

Page expiration in seconds. If null (unset), the page does not expire.

Type

integer

$_last_modified

$_last_modified : integer

The time of the last modification, set during auto-header-completion.

Type

integer

$_sent_headers

$_sent_headers : array

An array storing all HTTP headers registered through register_sent_header().

They will be sent when a cached page is delivered.

Type

array

$_content_type

$_content_type : string

The MIME content-type of the current request. It defaults to text/html, but must be set correctly, so that the client gets the correct type delivered upon cache deliveries.

Type

string

$_obrunning

$_obrunning : boolean

Internal flag indicating whether the output buffering is active.

Type

boolean

$_live_mode

$_live_mode : boolean

This flag is true if the live mode has been activated. This prevents the cache processing at the end of the request.

Type

boolean

$_uncached

$_uncached : boolean

Set this to true if you want to inhibit storage of the generated pages in the cache database. All other headers will be created as usual though, so 304 processing will kick in for example.

Type

boolean

$_headers_strategy

$_headers_strategy : string

Controls cache headers strategy 'no-cache' activates no-cache mode that actively tries to circumvent all caching 'revalidate' is the default which sets must-revalidate and expiry to current time 'public' and 'private' enable caching with the cache-control header of the same name, default expiry timestamps are generated using the default_lifetime

Type

string

$_headers_strategy_authenticated

$_headers_strategy_authenticated : string

Controls cache headers strategy for authenticated users, needed because some proxies store cookies, too, making a horrible mess when used by mix of authenticated and non-authenticated users

Type

string

$_default_lifetime

$_default_lifetime : integer

Default lifetime of page for public/private headers strategy When generating the default expires header this is added to time().

Type

integer

$_default_lifetime_authenticated

$_default_lifetime_authenticated : integer

Default lifetime of page for public/private headers strategy for authenticated users

Type

integer

$_meta_cache

$_meta_cache : \Doctrine\Common\Cache\CacheProvider

Cache backend instance.

Type

\Doctrine\Common\Cache\CacheProvider

$_data_cache

$_data_cache : \Doctrine\Common\Cache\CacheProvider

A cache backend used to store the actual cached pages.

Type

\Doctrine\Common\Cache\CacheProvider

$context_guids

$context_guids : 

GUIDs loaded per context in this request

Type

$_force_headers

$_force_headers : 

Forced headers

Type

Methods

initialize()

initialize() 

Initialize the module. This will initialize the class configuration and call the corresponding event handler.

shutdown()

shutdown() 

Shuts the module down. This will call the corresponding event handler

_on_initialize()

_on_initialize() 

Initialize the cache.

The first step is to initialize the cache backends. The names of the cache backends used for meta and data storage are derived from the name defined for this module (see the 'name' configuration parameter above). The name is used directly for the meta data cache, while the actual data is stored in a backend postfixed with '_data'.

After core initialization, the module checks for a cache hit (which might trigger the delivery of the cached page and exit) and start the output buffer afterwards.

_on_shutdown()

_on_shutdown() 

Shutdown handler, called during midcom_application::finish(). Note, that for example the page cache will not use this cleanup handler, as it produces a complete html page based on a previous request.

invalidate_all()

invalidate_all() 

Invalidate the cache completely, dropping all entries. The default implementation will drop all entries from all registered cache backends using CacheProvider::flushAll().

Override this function if this behavior doesn't suit your needs.

invalidate()

invalidate(string  $guid, object  $object = null) 

Looks for list of content and request identifiers paired with the given guid and removes all of those from the caches.

Parameters

string $guid

The GUID that has to be invalidated.

object $object

The object that has to be invalidated (if available).

start_caching()

start_caching(\Symfony\Component\HttpFoundation\Request  $request) 

Start the output cache. Call this before any output is made. MidCOM's startup sequence will automatically do this.

Parameters

\Symfony\Component\HttpFoundation\Request $request

no_cache()

no_cache(\Symfony\Component\HttpFoundation\Response  $response = null) 

Call this, if the currently processed output must not be cached for any reason. Dynamic pages with sensitive content are a candidate for this function.

Note, that this will prevent any content invalidation related headers like E-Tag to be generated automatically, and that the appropriate no-store/no-cache headers from HTTP 1.1 and HTTP 1.0 will be sent automatically. This means that there will also be no 304 processing.

You should use this only for sensitive content. For simple dynamic output, you are strongly encouraged to use the less strict uncached() function.

Parameters

\Symfony\Component\HttpFoundation\Response $response

uncached()

uncached() 

Call this, if the currently processed output must not be cached for any reason. Dynamic pages or form processing results are the usual candidates for this mode.

Note, that this will still keep the caching engine active so that it can add the usual headers (ETag, Expires ...) in respect to the no_cache flag. As well, at the end of the processing, the usual 304 checks are done, so if your page doesn't change in respect of E-Tag and Last-Modified, only a 304 Not Modified reaches the client.

Essentially, no_cache behaves the same way as if the uncached configuration directive is set to true, it is just limited to a single request.

If you need a higher level of client side security, to avoid storage of sensitive information on the client side, you should use no_cache instead.

expires()

expires(integer  $timestamp) 

Sets the expiration time of the current page (Unix (GMT) Timestamp).

Note: This generate error call will add browser-side cache control headers as well to force a browser to revalidate a page after the set expiry.

You should call this at all places where you have timed content in your output, so that the page will be regenerated once a certain article has expired.

Multiple calls to expires will only save the "youngest" timestamp, so you can safely call expires where appropriate without respect to other values.

The cache's default (null) will disable the expires header. Note, that once an expiry time on a page has been set, it is not possible, to reset it again, this is for dynamic_load situation, where one component might depend on a set expiry.

Parameters

integer $timestamp

The UNIX timestamp from which the cached page should be invalidated.

content_type()

content_type(string  $type) 

Sets the content type for the current page. The required HTTP Headers for are automatically generated, so, to the contrary of expires, you just have to set this header accordingly.

This is usually set automatically by MidCOM for all regular HTML output and for all attachment deliveries. You have to adapt it only for things like RSS output.

Parameters

string $type

The content type to use.

enable_live_mode()

enable_live_mode() 

Put the cache into a "live mode". This will disable the cache during runtime, correctly flushing the output buffer and sending cache control headers. You will not be able to send any additional headers after executing this call therefore you should adjust the headers in advance.

The midcom-exec URL handler of the core will automatically enable live mode.

disable_ob()

disable_ob() 

register_sent_header()

register_sent_header(string  $header, string  $value = null) 

Store a sent header into the cache database, so that it will be resent when the cache page is delivered. midcom_application::header() will automatically call this function, you need to do this only if you use the PHP header function.

Parameters

string $header

The header that was sent.

string $value

register()

register(  $guid) 

All objects loaded within a request are stored into a list for cache invalidation purposes

Parameters

$guid

finish_caching()

finish_caching(\Symfony\Component\HttpFoundation\Request  $request) 

This completes the output caching, post-processes it and updates the cache databases accordingly.

The first step is to check against _no_cache pages, which will be delivered immediately without any further post processing. Afterwards, the system will complete the sent headers by adding all missing headers. Note, that E-Tag will be generated always automatically, you must not set this in your component.

If the midcom configuration option cache_uncached is set or the corresponding runtime function has been called, the cache file will not be written, but the header stuff will be added like usual to allow for browser-side caching.

Parameters

\Symfony\Component\HttpFoundation\Request $request

write_meta_cache()

write_meta_cache(  $content_id,   $etag) 

Writes meta-cache entry from context data using given content id Used to be part of finish_caching, but needed by serve-attachment method in midcom_application as well

Parameters

$content_id
$etag

check_dl_hit()

check_dl_hit(  $context,   $dl_config) 

Parameters

$context
$dl_config

store_dl_content()

store_dl_content(  $context,   $dl_config,   $dl_cache_data) 

Parameters

$context
$dl_config
$dl_cache_data

cache_control_headers()

cache_control_headers(\Symfony\Component\HttpFoundation\Response  $response) 

Parameters

\Symfony\Component\HttpFoundation\Response $response

_create_backend()

_create_backend(string  $name, array  $config) : \Doctrine\Common\Cache\CacheProvider

Creates an instance of the handler described by the configuration passed to the function.

The configuration array must include the configuration parameters driver and directory, as outlined in the midcom_services_cache_backend class documentation.

All backends will be collected in the $_backends array, indexed by their name.

Any duplicate instantiation will be intercepted, throwing a critical error.

Parameters

string $name

The name of the backend, must be unique throughout the system.

array $config

The configuration of the backend to create. It must contain the key 'driver', which indicates which backend to use.

Returns

\Doctrine\Common\Cache\CacheProvider —

The new backend.

prepare_backend()

prepare_backend(array  $config,   $name) 

Parameters

array $config
$name

generate_request_identifier()

generate_request_identifier(  $context,   $customdata = null) 

Generate a valid cache identifier for a context of the current request

Parameters

$context
$customdata

get_strategy()

get_strategy(  $name) 

Parameters

$name

_check_hit()

_check_hit(\Symfony\Component\HttpFoundation\Request  $request) 

This function holds the cache hit check mechanism. It searches the requested URL in the cache database. If found, it checks, whether the cache page has expired. If not, the cached page is delivered to the client and processing ends. In all other cases this method simply returns.

The midcom-cache URL methods are handled before checking for a cache hit.

Also, any HTTP POST request will automatically circumvent the cache so that any component can process the request. It will set no_cache automatically to avoid any cache pages being overwritten by, for example, search results.

Note, that HTTP GET is not checked this way, as GET requests can be safely distinguished by their URL.

Parameters

\Symfony\Component\HttpFoundation\Request $request

store_context_guid_map()

store_context_guid_map(  $context,   $content_id,   $request_id) 

Parameters

$context
$content_id
$request_id

apply_headers()

apply_headers(\Symfony\Component\HttpFoundation\Response  $response, array  $headers) 

Parameters

\Symfony\Component\HttpFoundation\Response $response
array $headers

complete_sent_headers()

complete_sent_headers(\Symfony\Component\HttpFoundation\Response  $response) 

This little helper ensures that the headers Content-Length and Last-Modified are present. The lastmod timestamp is taken out of the component context information if it is populated correctly there; if not, the system time is used instead.

To force browsers to revalidate the page on every request (login changes would go unnoticed otherwise), the Cache-Control header max-age=0 is added automatically.

Parameters

\Symfony\Component\HttpFoundation\Response $response