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:
You have to use these functions everywhere where it is applicable or the cache will not work reliably.
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.
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)
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.
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.
stringThe etag header associated with the current document.
booleanTrue, if an 304 match was detected and the appropriate headers were sent.
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.
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.
stringname of the header, for example "Cache-Control"
stringfull header string with value, for example "Cache-Control: no-cache"
Call this before any output is made. MidCOM's startup sequence will automatically do this.
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.
stringThe content type to use.
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.
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.
intThe UNIX timestamp from which the cached page should be invalidated.
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.
midcom_application::header() will automatically call this function, you need to do this only if you use the PHP header function.
stringThe header that was sent.
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.
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.
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.
It defaults to text/html, but must be set correctly, so that the client gets the correct type delivered upon cache deliveries.
If null (unset), the page does not expire.
This prevents the cache processing at the end of the request.
If false, the usual no-cache headers will be generated.
They will be sent when a cached page is delivered.
All other headers will be created as usual though, so 304 processing will kick in for example.