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

Twitter updates

  • ProcessWire 3.0.174 core updates: improvements to the new path/URL hooks and more— More
    12 March 2021
  • ProcessWire 3.0.173 adds several new requested features and this post focuses on one of my favorites: the ability to hook into and handle ProcessWire URLs, independent of pages— More
    5 March 2021
  • This week ProcessWire gained powerful new tools for finding pages and controlling how they are loaded. If you like to maximize performance and efficiency, you’ll like what 3.0.172 brings— More
    5 February 2021

Latest news

  • ProcessWire Weekly #357
    In the 357th issue of ProcessWire Weekly we'll check out ProcessWire 3.0.174, some forum highlights, and more. Read on!
    Weekly.pw / 14 March 2021
  • ProcessWire 3.0.173 core updates: New URL hooks
    ProcessWire 3.0.173 adds several new requested features and this post focuses on one of my favorites: the ability to hook into and handle ProcessWire URLs, independent of pages.
    Blog / 5 March 2021
  • Subscribe to weekly ProcessWire news

“The end client and designer love the ease at which they can update the website. Training beyond how to log in wasn’t even necessary since ProcessWire’s default interface is straightforward.” —Jonathan Lahijani