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

Special care is taken when HTTP POST request data is present. In that case, the caching engine will automatically and transparently go into no_cache mode for that request only, allowing your application to process form data. 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 is the first cache module which is initialized, and it will be the last one in the shutdown sequence. Its 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.php)

  • 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.php, 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.
package midcom.services

 Methods

_check_not_modified (int $last_modified, string $etag, $additional_headers)

Checks, whether the browser supplied if-modified-since or if-none-match headers match the passed etag/last modified timestamp.

If yes, a 304 not modified header is emitted and true is returned. Otherwise the function will return false without modifications to the current runtime state.

If the headers have already been sent, something is definitely wrong, so we ignore the request silently returning false.

Note, that if both If-Modified-Since and If-None-Match are present, both must actually match the given stamps to allow for a 304 Header to be emitted.

Parameters

$last_modified

intThe last modified timestamp of the current document. This timestamp is assumed to be in local time, and will be implicitly converted to a GMT time for correct HTTP header comparisons.

$etag

stringThe etag header associated with the current document.

$additional_headers

Returns

booleanTrue, if an 304 match was detected and the appropriate headers were sent.

_finish_caching ($etag)

This helper will be called during module shutdown, it 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

$etag

_on_initialize ()

This function is responsible for initializing 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 ()

The shutdown event handler will finish the caching sequence by storing the cached data, if required.

_replace_sent_header (string $header, string $header_string)

Scans the _sent_headers array for similar header and replaces with new value, if header is not found adds it to the array

Parameters

$header

stringname of the header, for example "Cache-Control"

$header_string

stringfull header string with value, for example "Cache-Control: no-cache"

_start_caching ()

This function will start the output cache.

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

_use_auth_headers ()

cache_control_headers ()

check_dl_hit ($context, $dl_config)

Parameters

$context

$dl_config

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

$type

stringThe content type to use.

disable_ob ()

enable_live_mode ()

Use this function to 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.

see \midcom_application::_exec_file()

expires (int $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

$timestamp

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

generate_content_identifier ($context)

Generate a valid cache identifier for a context of the current content (all loaded objects).

Parameters

$context

generate_request_identifier ($context, $customdata)

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

Parameters

$context

$customdata

invalidate ($guid)

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

Parameters

$guid

no_cache ()

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.

see \uncached()

register ($guid)

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

Parameters

$guid

register_sent_header (string $header)

This method stores 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

$header

stringThe header that was sent.

store_dl_content ($context, $dl_config, $dl_cache_data)

Parameters

$context

$dl_config

$dl_cache_data

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.

see \no_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_hit ()

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.

_complete_sent_headers (array $cache_data)

This little helper ensures that the headers Accept-Ranges, 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

$cache_data

array&$cache_data The current cache data that will be written to the database.

store_context_guid_map ($context, $content_id, $request_id)

Parameters

$context

$content_id

$request_id

 Properties

 

\midcom_services_cache_backend $_data_cache

A cache backend used to store the actual cached pages.
 

mixed $_force_headers

Forced headers
 

\midcom_services_cache_backend $_meta_cache

Cache backend instance.
 

string $_content_type

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.

 

int $_default_lifetime

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

int $_default_lifetime_authenticated

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

int $_expires

Page expiration in seconds.

If null (unset), the page does not expire.

 

string $_headers_strategy

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
 

string $_headers_strategy_authenticated

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
 

int $_last_modified

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

boolean $_live_mode

This flag is true if the live mode has been activated.

This prevents the cache processing at the end of the request.

 

boolean $_no_cache

Flag, indicating whether the current page may be cached.

If false, the usual no-cache headers will be generated.

 

boolean $_obrunning

Internal flag indicating whether the output buffering is active.
 

array $_sent_headers

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

They will be sent when a cached page is delivered.

 

boolean $_uncached

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.

 

mixed $context_guids

GUIDs loaded per context in this request