silverstripe-framework/docs/en/reference/staticpublisher.md

Static Publisher

Introduction

Many sites get too much traffic to justify dynamically sending every request. Caching is needed. Static Publishing will generate static versions of your content (HTML) that can be served without ever hitting PHP or the Database.

See [api:StaticExporter] for a less flexible, but easier way of building a local static cache from all of your pages.

See Partial-Caching for a much more flexible way of building in caching without statically delivering content. Partial Caching is recommended as a basic enhancement to any SilverStripe site however if your site is planning a vast amount of traffic (eg an article is being dug) then Static Publisher will be appropriate.

Requirements

Requires SilverStripe 2.3

Usage

SilverStripe doesn't have enough information about your template and data-structures to automatically determine which URLs need to be cached, and at which time they are considered outdated. By adding a custom method allPagesToCache() to your Page class, you can determine which URLs need caching, and hook in custom logic. This array of URLs is used by the publisher to generate folders and HTML-files.

:::php
class Page extends SiteTree {
  // ...

  /**

   * Return a list of all the pages to cache
   */
  public function allPagesToCache() {
    // Get each page type to define its sub-urls
    $urls = array();

    // memory intensive depending on number of pages
    $pages = DataObject::get("SiteTree");

    foreach($pages as $page) {
      $urls = array_merge($urls, (array)$page->subPagesToCache());
    }
    
    // add any custom URLs which are not SiteTree instances
    $urls[] = "sitemap.xml";

    return $urls;
  }

 /**

   * Get a list of URLs to cache related to this page
   */
  public function subPagesToCache() {
    $urls = array();

    // add current page
    $urls[] = $this->Link();
    
    // cache the RSS feed if comments are enabled
    if ($this->ProvideComments) {
      $urls[] = Director::absoluteBaseURL() . "pagecomment/rss/" . $this->ID;
    }
    
    return $urls;
  }
  
  public function pagesAffectedByChanges() {
    $urls = $this->subPagesToCache();
    if($p = $this->Parent) $urls = array_merge((array)$urls, (array)$p->subPagesToCache());
    return $urls;
  }
}

Excluding Pages

The allPagesToCache function returns all the URLs needed to cache. So if you want to exclude specific pages from the cache then you unset these URLs from the returned array. If you do not want to cache a specific class (eg UserDefinedForms) you can also add an exclusion

:::php
public function allPagesToCache() {
	$urls = array();
	$pages = DataObject::get("SiteTree");
	
	// ignored page types
	$ignored = array('UserDefinedForm');
	
	foreach($pages as $page) {
		// check to make sure this page is not in the classname
		if(!in_array($page->ClassName, $ignored)) {
			$urls = array_merge($urls, (array)$page->subPagesToCache());
		}
	}
	
	return $urls;
}

You can also pass the filtering to the original DataObject::get("SiteTree");

:::php
public function allPagesToCache() {
	$urls = array();
	$pages = DataObject::get("SiteTree", "ClassName != 'UserDefinedForm'");
	...

Single server Caching

This setup will store the cached content on the same server as the CMS. This is good for a basic performance enhancement.

Setup

Put this in mysite/_config.php. This will create static content in a "cache/" subdirectory, with an HTML suffix.

:::php
Object::add_extension("SiteTree", "FilesystemPublisher('cache/', 'html')");

• Put this into your .htaccess. It will serve requests from the cache, statically, if the cache file exists. Replace sitedir with the a subdirectory that you would like to serve the site from (for example, in your dev environment).

View .htaccess example

• New for 2.4: In 2.4, we use a simple PHP script, static-main.php, to control cache lookup. This make the .htaccess update simpler.

Just look for this line:

RewriteRule .* sapphire/main.php?url=%1&%{QUERY_STRING} [L]

And change the PHP script from main.php to static-main.php:

RewriteRule .* sapphire/static-main.php?url=%1&%{QUERY_STRING} [L]

Using Static Publisher With Subsites Module

Append the following code to mysite/config.php

:::php
FilesystemPublisher::$domain_based_caching = true;

Instead of the above code snippet for Page.php, use the following code:

:::php
class Page extends SiteTree {

        // ...

	public function allPagesToCache() {
            // Get each page type to define its sub-urls
	    $urls = array();

	    // memory intensive depending on number of pages
	    $pages = Subsite::get_from_all_subsites("SiteTree");

	    foreach($pages as $page) {
		$urls = array_merge($urls, (array)$page->subPagesToCache());
	    }

	    return $urls;
	}

	public function subPagesToCache() {
		$urls = array();
		$urls[] = $this->AbsoluteLink();
		return $urls;
	}

	public function pagesAffectedByChanges() {
		$urls = $this->subPagesToCache();
		if($p = $this->Parent) $urls = array_merge((array)$urls, (array)$p->subPagesToCache());
		return $urls;
	}

        // ... some other code ...

}

And the last thing you need to do is adding your main site's host mapping to subsites/host-map.php. For example, your main site's host is mysite.com the content of the file would be:

:::php
<?php 
$subsiteHostmap = array (
  // .. subsite hots mapping ..,
  'mysite.com', 'mysite.com' 
);

Remember that you need to add main site's host mapping every time a subsite is added or modified because the operation overwrites your manual modification to the file and subsite module does not add main site's hot mapping automatically at the moment.

Another note for host-map.php file. This file doesn't not exist until you have created at least one subsite.

Multiple Server Caching

In this setup, you have one server that is your dynamic CMS server, and one or more separate servers that are responsible for serving static content. The publication system on the CMS will rsync changes to the static content servers as needed. No PHP files will be synced to the static content servers unless explicitly requested. All static assets (images, javascript, etc.) will be rsynced from their original locations. You can then put a load-balancer on the front of the static content servers.

This approach is very secure, because you can lock the CMS right down (for example, by IP) and hide all the PHP code away from potential hackers. It is also good for high-traffic situations.

Setup

Add the RsyncMultiHostPublisher extension to your SiteTree objects in mysite/_config.php. This will create static content in a "cache/" subdirectory, with an HTML suffix.

:::php
Object::add_extension("SiteTree", "RsyncMultiHostPublisher('cache/', 'html')");
RsyncMultiHostPublisher::set_targets(array(
	'<rsyncuser>@<static-server1>:<webroot>',
	'<rsyncuser>@<static-server2>:<webroot>',
));

Where <rsyncuser> is a unix account with write permissions to <webroot> (e.g. /var/www), and <static-server1> and <static-server2> are the names of your static content servers. The number of servers is flexible and depends on your infrastructure and scalability needs.

• Ensure that the rsync unix tool is installed on the CMS server, and ssh access is enabled on the static content servers.

• No password can be specified for the SSH connection . The class assumes a key-based authentication without requiring a password for the username specified in <rsyncuser> (see [http://www.csua.berkeley.edu/~ranga/notes/ssh_nopass.html tutorial](http://www.csua.berkeley.edu/~ranga/notes/ssh_nopass.html tutorial)).

• Put the .htaccess file linked below into the webroot of each static content server (and rename it to .htaccess). It will serve requests from the cache, statically, if the cache file exists. Replace sitedir with the a subdirectory that you would like to serve the site from (for example, in your dev environment).

View .htaccess example

Cache Control

There is also the option to wrap some PHP logic around the static HTML content served by the content servers, which can greatly reduce the bandwidth required on your content servers. This code takes care of cache control through HTTP headers (''Cache-control'', If-modified-since), meaning the files will only be delivered if they changed since the browser client last requested them. The last modification date for each static file is controlled by the publication script, meaning the cache gets invalidated on each publication.

To enable cache control, specify "php" instead of "html" in the RsyncMultiHostPublisher definition.

:::php
Object::add_extension("SiteTree", "RsyncMultiHostPublisher('cache/', 'php')");

And use this slightly different .htaccess file. Make sure that index.php can be used as a directory index!

View .htaccess example

Deployment

Once you've set up your rewrite rules and defined which pages need caching, you can build the static HTML files. This is done by the [api:RebuildStaticCacheTask]

Execution via URL

http://www.example.com/dev/buildcache?flush=1

Execution on CLI (via sake)

sake dev/buildcache flush=1

Depending on which extension you've set up for your SiteTree (FilesystemPublisher or RsyncMultiHostPublisher), the method publishPages() either stores the generated HTML-files on the server's filesystem, or deploys them to other servers via rsync.

It is adviseable to set dev/buildcache up as an automated task (e.g. unix cron) which continually rebuilds and redeploys the cache.

Related

• [api:StaticExporter]
• Partial-Caching

API Documentation

• [api:StaticPublisher]