$_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.
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:
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)
$_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
_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.
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.
| string | $guid | The GUID that has to be invalidated. |
| object | $object | The object that has to be invalidated (if available). |
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.
| \Symfony\Component\HttpFoundation\Response | $response |
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(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.
| integer | $timestamp | The UNIX timestamp from which the cached page should be invalidated. |
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.
| string | $type | The content type to use. |
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.
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.
| string | $header | The header that was sent. |
| string | $value |
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.
| \Symfony\Component\HttpFoundation\Request | $request |
_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.
| 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. |
The new backend.
_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.
| \Symfony\Component\HttpFoundation\Request | $request |
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.
| \Symfony\Component\HttpFoundation\Response | $response |