$cache->renderFile() method

Render a file as a ProcessWire template file and cache the output

This method is similar to the $files->render() method and actually delegates the file rendering to that method (when creating the cache). The important difference is that this method caches the output according to WireCache rules for the $expire argument, rather than re-rendering the file on every call.

If there are any changes to the source file $filename the cache will be automatically re-created, regardless of what is specified for the $expire argument.

Available since version 3.0.130.

Example

// render primary nav from site/templates/partials/primary-nav.php 
// and cache for 3600 seconds (1 hour)
echo $cache->renderFile('partials/primary-nav.php', 3600); 

Usage

// basic usage
$string = $cache->renderFile(string $filename);

// usage with all arguments
$string = $cache->renderFile(string $filename, $expire = null, array $options = []);

Arguments

NameType(s)Description
filenamestring

Filename to render (typically PHP file). Can be full path/file, or dir/file relative to current work directory (which is typically /site/templates/). If providing a file relative to current dir, it should not start with "/". File must be somewhere within site/templates/, site/modules/ or wire/modules/, or provide your own allowedPaths option. Please note that $filename receives API variables already (you don’t have to provide them).

expire (optional)int, Page, string, null

Lifetime of this cache, in seconds, OR one of the following:

  • Specify one of the WireCache::expire* constants.
  • Specify the future date you want it to expire (as unix timestamp or any strtotime() compatible date format)
  • Provide a Page object to expire when any page using that template is saved.
  • Specify WireCache::expireNever to prevent expiration.
  • Specify WireCache::expireSave to expire when any page or template is saved.
  • Specify selector string matching pages that–when saved–expire the cache.
  • Omit for default value, which is WireCache::expireDaily.
options (optional)array

Accepts all options for the WireFileTools::render() method, plus these additional ones:

  • name (string): Optionally specify a unique name for this cache, otherwise $filename will be used as the unique name. (default='')
  • vars (array): Optional associative array of extra variables to send to template file. (default=[])
  • allowedPaths (array): Array of paths that are allowed (default is anywhere within templates, core modules and site modules)
  • throwExceptions (bool): Throw exceptions when fatal error occurs? (default=true)

Return value

string bool

Rendered template file or boolean false on fatal error (and throwExceptions disabled)

Exceptions

Method can throw exceptions on error:

  • WireException - if given file doesn’t exist

See Also


$cache methods and properties

API reference based on ProcessWire core version 3.0.185

Twitter updates

  • ProcessWire 3.0.185 (dev) core updates, plus new Session Allow module— More
    17 September 2021
  • Three new ProcessWire Textformatter modules: Find/Replace, Markdown in Markup, and Emoji— More
    3 September 2021
  • This week we have a new master version released after a year in the making. With nearly 40 pull requests, hundreds of new additions and more than 100 issue reports resolved, this new version has a ton of great new stuff— More
    27 August 2021

Latest news

  • ProcessWire Weekly #388
    In the 388th issue of ProcessWire Weekly we'll check out the latest core update, introduce two new third party modules, and more. Read on!
    Weekly.pw / 16 October 2021
  • ProcessWire 3.0.184 new master/main version
    This week we have a new master/main version released after a full year in the making. As you might imagine, this new version has a ton of great new stuff and we’ll try to cover much of it here.
    Blog / 27 August 2021
  • Subscribe to weekly ProcessWire news

“Yesterday I sent the client a short documentation for their ProcessWire-powered website. Today all features already used with no questions. #cmsdoneright—Marc Hinse, Web designer/developer