class Cache (View source)

The Cache class holds all methods for evaluating, reading and writing the HTML output and the Automad object from/to AM_DIR_CACHE.

Basically there are three things which get cached - the latest modification time of all the site's files and directories (site's mTime), the page's HTML and the Automad object.

The workflow:

1. A virtual file name of a possibly existing cached version of the visited page gets determined from the PATH_INFO, the QUERY_STRING and the SERVER_NAME. To keep the whole site portable, the SERVER_NAME within the path is very important, to make sure, that all links/URLs are relative to the correct root directory. ("sub.domain.com/" and "www.domain.com/sub" will return different root relative URLs > "/" and "/sub", but may host the same site > each will get its own /cache/directory)

2. The site's mTime gets determined. To keep things fast, the mTime gets only re-calculated after a certain delay and then stored in AM_FILE_SITE_MTIME. In between the mTime just gets loaded from that file. That means that not later then AM_CACHE_MONITOR_DELAY seconds, all pages will be up to date again. To determine the latest changed item, all directories and files under /pages, /shared, /themes and /config get collected in an array. The filemtime for each item in that array gets stored in a new array ($mTimes[$item]). After sorting, all keys are stored in $mTimesKeys. The last modified item is then = end($mTimesKeys), and its mtime is $mTimes[$lastItem]. Compared to using max() on the $mTime array, this method is a bit more complicated, but also determines, which of the items was last edited and not only its mtime. (That gives a bit more control for debugging)

3. When calling now pageCacheIsApproved() from outside, true will be returned if the cached file exists, didn't reach the maximum lifetime and is newer than the site's mTime (and of course caching is active). If the cache is validated, readPageFromCache() can return the full HTML to be echoed.

4. In case the page's cached HTML is deprecated, automadObjectCacheIsApproved() can be called to verify the status of the Automad object cache (a file holding the serialized Automad object ($Automad)). If the Automad object cache is approved, readAutomadObjectFromCache() returns the unserialized Automad object to be used to create an updated page from a template (outside of Cache). That step is very helpful, since the current page's cache might be outdated, but other pages might be already up to date again and therefore the Automad object cache might be updated also in the mean time. So when something got changed across the Automad, the Automad object only has to be created once to be reused to update all pages.

5. In case the page and the Automad object are deprecated, after creating both, they can be saved to cache using writePageToCache() and writeAutomadObjectToCache().

Methods

__construct()

The constructor checks whether caching is enabled for the current request and determines the $pageCacheFile to make it available within the instance.

clear()

Clearing the cache is done by simply deleting the stored Site's mTime file. That will trigger a full cache rebuild.

boolean
pageCacheIsApproved()

Verify if the cached version of the visited page is existing and still up to date.

boolean
automadObjectCacheIsApproved()

Verify if the cached version of the Automad object is existing and still up to date.

number
getSiteMTime()

Get an array of all subdirectories and all files under /pages, /shared, /themes and /config (and the version.php) and determine the latest mtime among all these items.

string
readPageFromCache()

Read the rendered page from the cached version.

object
readAutomadObjectFromCache()

Read (unserialize) the Automad object from AM_FILE_OBJECT_CACHE and update the context to the requested page.

writePageToCache(string $output)

Write the rendered HTML output to the cache file.

writeAutomadObjectToCache(object $Automad)

Write (serialize) the Automad object to AM_FILE_OBJECT_CACHE.

Details

__construct()

The constructor checks whether caching is enabled for the current request and determines the $pageCacheFile to make it available within the instance.

In case of any submitted data (get or post), caching will be disabled to make sure that possible modifications of the session data array will always be reflected in the cache. Note that caching of such submitted data (get or post) would possibly only update the session data array for the requesting user. All other user could therefore not trigger any updates to their sessions, because the request is already cached and the template would not be parsed again.

clear()

Clearing the cache is done by simply deleting the stored Site's mTime file. That will trigger a full cache rebuild.

boolean pageCacheIsApproved()

Verify if the cached version of the visited page is existing and still up to date.

A page gets approved as long as it is newer than the site's mTime and didn't reach the cache's lifetime. When reaching the cache's lifetime, the page cache always gets rebuilt, also if the site's content didn't change. This enforced rebuilt is needed to avoid issues when deploying a site via tools like rsync and therefore possibly having inconsistent timestamps. The lifetime therefore makes sure, that - after a certain period - the page gets rendered correctly in all cases.

Return Value

boolean True, if the cached version is valid.

boolean automadObjectCacheIsApproved()

Verify if the cached version of the Automad object is existing and still up to date.

The object cache gets approved as long as it is newer than the site's mTime and didn't reach the cache's lifetime. When reaching the cache's lifetime, the Automad object cache always gets rebuilt, also if the site's content didn't change. This enforced rebuilt is needed to avoid issues when deploying a site via tools like rsync and therefore possibly having inconsistent timestamps. The lifetime therefore makes sure, that - after a certain period - the object gets created correctly in all cases.

Return Value

boolean

number getSiteMTime()

Get an array of all subdirectories and all files under /pages, /shared, /themes and /config (and the version.php) and determine the latest mtime among all these items.

That time basically represents the site's modification time, to find out the lastes edit/removal/add of a page. To be efficient under heavy traffic, the Site-mTime only gets re-determined after a certain delay.

Return Value

number The latest found mtime, which equal basically the site's modification time.

string readPageFromCache()

Read the rendered page from the cached version.

Return Value

string The full cached HTML of the page.

object readAutomadObjectFromCache()

Read (unserialize) the Automad object from AM_FILE_OBJECT_CACHE and update the context to the requested page.

Return Value

object Automad object

writePageToCache(string $output)

Write the rendered HTML output to the cache file.

Parameters

string $output

writeAutomadObjectToCache(object $Automad)

Write (serialize) the Automad object to AM_FILE_OBJECT_CACHE.

Parameters

object $Automad