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 throughoutly:
- 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();
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 mach a cached page is displayed, which should take care of any permission check 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 exit() in case of a cache hit, and it will enclose the entire request using PHPs 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).
- bool cache_module_content_multilang: Set this to true (the default) if you want to have a cache which distinguishes between languages on each request.
- bool 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.
Located in /midcom/services/cache/module/content.php (line 68)
midcom_services_cache_module | --midcom_services_cache_module_content
string
$_content_type
= 'text/html' (line 114)
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.
Internal runtime state variable.
midcom_services_cache_backend
$_data_cache
= null (line 179)
An cache backend used to store the actual cached pages.
Cache backend instance.
int
$_expires
= null (line 90)
Page expiration in seconds. If NULL (unset), the page does not expire.
Internal runtime state variable.
int
$_last_modified
= 0 (line 97)
The time of the last modification, set during auto-header-completion.
Internal runtime state variable.
bool
$_live_mode
= false (line 129)
This flag is true if the live mode has been activiated. This prevents the cache processing at the end of the request.
Internal runtime state variable.
midcom_services_cache_backend
$_meta_cache
= null (line 172)
This is true, if the pages produced by the cache should not be
Cache backend instance.
stored in the cache database. Use this f.x. during development for a quasi-uncached behvoir (all headers are generated, the content just is not stored in the cache database, and all header processing is done nevertheless).
bool
$_multilang
= true (line 144)
True, if the cache should honor the language settings.
Module configuration variable.
bool
$_no_cache
= false (line 82)
Flag, indicating wether the current page may be cached. If false, the usual no-cache headers will be generated.
Internal runtime state variable.
bool
$_obrunning
= false (line 121)
Internal flag indicating wether the output buffering is active.
Internal runtime state variable.
array
$_sent_headers
= array() (line 105)
An array storing all HTTP headers registered through register_sent_header().
Internal runtime state variable.
They will be sent when a cached page is delivered.
bool
$_uncached
= false (line 153)
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.
Module configuration variable.
Inherited Variables
Inherited from midcom_services_cache_module
midcom_services_cache_module::$_backends
Module constructor, relay to base class.
Sets the content type for the current page. The required HTTP Headers for are automatically generated, so, to the contratry 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.
- string $type: The content type to use.
Use this funciton 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.
The midcom-exec URL handler of the core will automatically enable live mode.
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.
- int $timestamp: The UNIX timestamp from which the cached page should be invalidated.
This function currently maps to invalidate_all unconditionally, as there is no leaf-level invalidation of content cache objects yet.
- midcom_services_cache_module::invalidate()
- Invalidate all cache objects related to the given GUID.
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.
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.
- string $header: The header that was sent.
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.
This function holds the cache hit check meachnism. It seraches the requested URL in the cache database. If found, it checks, wether 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.
Checks, wether 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 definitly 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.
- int $last_modified: The 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.
- string $etag: The etag header accociated with the current document.
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.
- Array& $cache_data: The current cache data that will be written to the database.
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.
Wrapper for number_format(number, 0, "", "."), used in the cache_stats call.
- int $number: Number to be formatted
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.
- midcom_services_cache_module::_on_initialize()
- Startup handler, called during service start up at the start of the request.
The shutdown event handler will finish the caching sequence by storing the cached data, if required.
- midcom_services_cache_module::_on_shutdown()
- Shutdown hanlder, 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.
This function will start the output cache. Call this before any output is made. MidCOM's startup sequence will automatically do this.
Inherited Methods
Inherited From midcom_services_cache_module
midcom_services_cache_module::midcom_services_cache_module()
midcom_services_cache_module::initialize()
Documentation generated on Mon, 21 Nov 2005 18:12:57 +0100 by phpDocumentor 1.3.0RC3