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().

Properties

private $automadObjectCachingIsEnabled The status of the Automad object cache.
private $objectCacheFile The filename for the object cache.
private $pageCacheFile The determined matching file of the cached version of the currently visited page.
private $pageCachingIsEnabled In contrast to the AM_CACHE_ENABLED constant, this variable is only for storing the status of the page cache, independent from the Automad object cache.
private $siteMTime The latest modification time of the whole website (any file or directory).

Methods

__construct()

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

bool
automadObjectCacheIsApproved()

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

static 
clear()

Clearing the cache is done by simply setting the stored Site's mTime to the current timestamp.

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.

bool
pageCacheIsApproved()

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

object
readAutomadObjectFromCache()

Read (unserialize) the Automad object from $this->objectCacheFile and update the context to the requested page.

string
readPageFromCache()

Read the rendered page from the cached version.

static int
readSiteMTime()

Read the site's modification time from file.

writeAutomadObjectToCache(Automad $Automad)

Write (serialize) the Automad object to $this->objectCacheFile.

writePageToCache(string $output)

Write the rendered HTML output to the cache file.

array
getDirectoriesRecursively(string $dir)

Get all subdirectories of a given directory.

string
getPageCacheFilePath()

Determine the corresponding file in the cache for the requested page in consideration of a possible session data.

static 
writeSiteMTime(int $siteMTime)

Write the site's modification time to the 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.

bool 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

bool

static clear()

Clearing the cache is done by simply setting the stored Site's mTime to the current timestamp.

That will trigger a full cache rebuild. Note that this method is only being called from outside and doesn't require any cache instance. It therefore should be static in order to avoid unneeded scanning of files when creating a new cache object.

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.

bool 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

bool True, if the cached version is valid.

object readAutomadObjectFromCache()

Read (unserialize) the Automad object from $this->objectCacheFile and update the context to the requested page.

Return Value

object Automad object

string readPageFromCache()

Read the rendered page from the cached version.

Return Value

string The full cached HTML of the page.

static int readSiteMTime()

Read the site's modification time from file.

This methods doesn't require any cache instance and should be static for performance reasons.

Return Value

int The site's modification time.

writeAutomadObjectToCache(Automad $Automad)

Write (serialize) the Automad object to $this->objectCacheFile.

Parameters

Automad $Automad

writePageToCache(string $output)

Write the rendered HTML output to the cache file.

Parameters

string $output

private array getDirectoriesRecursively(string $dir)

Get all subdirectories of a given directory.

Parameters

string $dir

Return Value

array The array of directories including the given directory itself

private string getPageCacheFilePath()

Determine the corresponding file in the cache for the requested page in consideration of a possible session data.

To get unique cache files for all kind of data within $SESSION['data'], a hashed JSON representation of a that data array is appended to the cache file prefix like "cached{hash}.html" in case the array is not empty.

Return Value

string The determined file name of the matching cached version of the visited page.

static private writeSiteMTime(int $siteMTime)

Write the site's modification time to the cache.

This method is also used in other static methods and doesn't require any cache instance. It therefore should be static for performance reasons.

Parameters

int $siteMTime