Automad
 All Classes Functions Variables Pages
Automad\Core\Cache Class Reference

Public Member Functions

 __construct ()
 
 clear ()
 
 pageCacheIsApproved ()
 
 automadObjectCacheIsApproved ()
 
 getSiteMTime ()
 
 readPageFromCache ()
 
 readAutomadObjectFromCache ()
 
 writePageToCache ($output)
 
 writeAutomadObjectToCache ($Automad)
 

Private Member Functions

 getPageCacheFilePath ()
 

Private Attributes

 $pageCacheFile
 
 $siteMTime
 

Detailed Description

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.

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

Author
Marc Anton Dahmen hello.nosp@m.@mar.nosp@m.cdahm.nosp@m.en.d.nosp@m.e
License
MIT license - http://automad.org/license

Definition at line 82 of file cache.php.

Constructor & Destructor Documentation

Automad\Core\Cache::__construct ( )

The constructor just determines $pageCacheFile to make it available within the instance.

Definition at line 103 of file cache.php.

References Automad\Core\Debug\log().

Member Function Documentation

Automad\Core\Cache::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.

Returns
boolean

Definition at line 209 of file cache.php.

References Automad\Core\Debug\log().

Automad\Core\Cache::clear ( )

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

Definition at line 125 of file cache.php.

Automad\Core\Cache::getPageCacheFilePath ( )
private

Determine the corresponding file in the cache for the visited page in consideration of a possible query string. A page gets for each possible query string (to handle sort/filter) an unique cache file.

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

Definition at line 264 of file cache.php.

References Automad\Core\Parse\sanitize().

Automad\Core\Cache::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.

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

Definition at line 300 of file cache.php.

References Automad\Core\Debug\log().

Automad\Core\Cache::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.

Returns
boolean - true, if the cached version is valid.

Definition at line 147 of file cache.php.

References Automad\Core\Debug\log().

Automad\Core\Cache::readAutomadObjectFromCache ( )

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

Returns
Automad object

Definition at line 407 of file cache.php.

References Automad\Core\Debug\log().

Automad\Core\Cache::readPageFromCache ( )

Read the rendered page from the cached version.

Returns
The full cached HTML of the page.

Definition at line 393 of file cache.php.

References Automad\Core\Debug\log().

Automad\Core\Cache::writeAutomadObjectToCache (   $Automad)

Write (serialize) the Automad object to AM_FILE_OBJECT_CACHE.

Definition at line 456 of file cache.php.

References Automad\Core\Debug\log().

Automad\Core\Cache::writePageToCache (   $output)

Write the rendered HTML output to the cache file.

Definition at line 419 of file cache.php.

References Automad\Core\Debug\log().

Member Data Documentation

Automad\Core\Cache::$pageCacheFile
private

The determined matching file of the cached version of the currently visited page.

Definition at line 89 of file cache.php.

Automad\Core\Cache::$siteMTime
private

The latest modification time of the whole website (any file or directory).

Definition at line 96 of file cache.php.


The documentation for this class was generated from the following file: