$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.137

Twitter updates

  • ProcessWire 3.0.144 and 3.0.145 add improved field template context override settings and include a new Inputfields API, along with numerous other issue fixes, optimizations and improvements to the core. More
    8 November 2019
  • ProcessWire 3.0.144 core updates: Upgraded overrides section in the field editor, a new Inputfields JS API, and more— More
    1 November 2019
  • ProcessWire 3.0.143 core updates — 26 commits and 18 resolved issue reports, plus some other useful improvements and additions. More here: More
    25 October 2019

Latest news

  • ProcessWire Weekly #288
    In the 288th issue of ProcessWire Weekly we'll cover the latest core updates, introduce WireMailSendGrid, host a new weekly poll, and showcase a new site of the week. Read on!
    Weekly.pw / 16 November 2019
  • ProcessWire 3.0.145 core updates
    ProcessWire 3.0.144 and 3.0.145 add improved field template context override settings and include a new Inputfields API, along with numerous other issue fixes, optimizations and improvements to the core.
    Blog / 8 November 2019
  • Subscribe to weekly ProcessWire news

“To Drupal, or to ProcessWire? The million dollar choice. We decided to make an early switch to PW. And in retrospect, ProcessWire was probably the best decision we made. Thanks are due to ProcessWire and the amazing system and set of modules that are in place.” —Unni Krishnan, Founder of PigtailPundits