Limb 2.2+ introduces full page caching functionality which allows you to cache specific parts of the site using pretty flexible sets of caching rules.

The idea is pretty straight-forward: fetch the dynamic content, save it into the static file and spit it out to the client every time it requests it without fetching overhead.

The common problem about caching is determining the validity of page cache, which sometimes indeed is a difficult task. At the moment Limb has the simpliest implementation - it doesn't make any sophisticated cache expiry date checks. The cache is removed manually by the admin or via a cron job. However this simplicity proved to be very effective.

So in order to define specific caching rules you have to edit your PROJECT_DIR/core/settings/full_page_cache.ini file (…can't find one? Simply create it!).

Let's take a closer look at the example of such a file:

[rule-name1]
  path_regex = |^/root/documents.*$|

  groups[] = visitors
  groups[] = members

  required[] = parameter3
  required[] = parameter4
  
  optional[] = parameter1
  optional[] = parameter2
      
  type = allow
  
[rule-name2]
  
  path_regex = |^.*$|
  groups[] = admins
  type = deny

As you can note there're special sections in the file with some strange attributes. Well this sections are rules. When cache manager parses this file it finds all sections beginning with «rule» keyword. This way «rule-name1» and «rule-name2» are valid examples of such rule sections and «not-valid-rule» is not.

When cache manager is done with parsing of the .ini file it has neat rule sections with bunch of parameters. What are they and what do they mean? Glad you asked :)

Before answering this question it's neccessary to understand the cache_manager basic workflow:

• The requested uri is passed to the cache manager
• The cache manger determines whether the uri is cacheable, if not - exit
• The cache manger determines whether the uri was already cached on the disk: if yes the cache is retrieved, if not the cache is written.

The cache rule attributes affect step 2 or step 3.

The precedence of rules in the configuration file is important. The cache manager goes from the 'top' rule to the «bottom» one.

'path_regex' parameter defines a regular expression to be matched against the path of the requested url.

So if you have it set to |^/root/documents.*$| it matches http://yourdomain.com/root/documents/123 and not http://yourdomain.com/root/archive.

This is important to remember that only the 'path' component is matched against the regular expression, other parts like «query items», «port», etc are simply omitted.

This parameter is mandatory.

If there's no match the cache manager proceeds to the next rule.

'type' parameter, the most simplest one - just defines if the rule is permissive or inhibitory.

Only two values are allowed: 'allow' and 'deny'. 'allow' - by default

This parameter is optional.

If rule is valid and type has 'deny' value - manager won't cache the page.

groups parameter defines an array of user groups the rule is restricted to be applied to. Filling an array is pretty easy: use [] operator to append as many values as you need.

This is particulary useful for setting up cache only for certain types of users. It's obvious that administrators need to see the current state of the site while for speed issues visitors may see the cached version. Well it's up to you.

Not logged in user belongs by default to the system vistitors group.

This parameter is optional.

If the user's group doesn't match the cache manager proceeds to the next rule.

required parameter defines the neccessary set of query item keys to be present in the requested uri. As mentioned above 'path_regex' is matched against path component of the uri while 'required' helps you to set required keys of the query items. Well it's better to show you a simple example.

Take a look at this uri http://yourdomain.com/path?pager=1&offset=2. As we can see there're 2 query item keys 'pager' and 'offset'. The 'required' option will make cache manager match query item keys to the specified ones.

Please remember at this point we're not talking of value matching, value 1 of 'pager' and 2 of 'offset' query items will be used a bit later on the stage of cache retrieval.

So if we had

  required[] = pager
  required[] = offset

or

  required[] = pager

…it would definitely match to http://yourdomain.com/path?pager=1&offset=2.

And

  required[] = pager
  required[] = limit

…wouldn't!

It means that the query keys defined in 'required' MUST be among the requested uri query keys. If not the cache manager proceeds to the next rule.

This parameter is optional.

optional parameter plays no role in determining if the uri is cacheable or not(unlike the 'required' option). It's used to determine if cache exists on the disk. This requires some further explanation.

Say we have http://yourdomain.com/path?pager=1&offset=2 request, and say it's cacheable. Now it's time to find out if it exists on the disk. The cache should have a unique identifier for every cacheable request. But how do we know the way to figure out this unique identifier? The most straight forward way will be to use the 'path' component of the requested uri and serialized query items values as md5 arguments(for our example it will be md5('path' . serialize(array('pager' ⇒ 1, 'offset' ⇒ 2)))).

Well, not exactly since we can have some optional(or even unneccessary) query items in the requested uri. Say we have also http://yourdomain.com/path?pager=1&offset=2&//rn=1000// request and we know that only 'pager' and 'offset' attributes have meaningful data. How do we omit the 'rn' attribute?

Meet 'optional' option! It allows you to define which values of the requested query keys will be used for generating the cache unique identifier.

When figuring out the cache unique id, both 'required' and 'optional' query values are used. They are merged together and sorted by keys, this way http://yourdomain.com/path?pager=1&offset=2 and http://yourdomain.com/path?offset=2&pager=1 uris point to the same cache id.

This parameter is optional(it's even called 'optional' ).