Cache
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
The constructor checks whether caching is enabled for the current request and determines the $pageCacheFile to make it available within the instance.
Verify if the cached version of the Automad object is existing and still up to date.
Clearing the cache is done by simply setting the stored Site's mTime to the current timestamp.
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.
Verify if the cached version of the visited page is existing and still up to date.
Read (unserialize) the Automad object from $this->objectCacheFile and update the context to the requested page.
Read the rendered page from the cached version.
Read the site's modification time from file.
Write (serialize) the Automad object to $this->objectCacheFile.
Write the rendered HTML output to the cache file.
Get all subdirectories of a given directory.
Determine the corresponding file in the cache for the requested page in consideration of a possible session data.
Write the site's modification time to the cache.
Details
at line 120
__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.
at line 174
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.
at line 214
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.
at line 227
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.
at line 303
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.
at line 345
object
readAutomadObjectFromCache()
Read (unserialize) the Automad object from $this->objectCacheFile and update the context to the requested page.
at line 356
string
readPageFromCache()
Read the rendered page from the cached version.
at line 368
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.
at line 379
writeAutomadObjectToCache(Automad $Automad)
Write (serialize) the Automad object to $this->objectCacheFile.
at line 401
writePageToCache(string $output)
Write the rendered HTML output to the cache file.
at line 416
private array
getDirectoriesRecursively(string $dir)
Get all subdirectories of a given directory.
at line 437
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.
at line 485
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.