silverstripe-cloudflare-purger

Simple Silverstripe plugin to automatically purge pages from Cloudflare when a Page or a related DataObject is published/saved.

Requirements

jamesryanbell/cloudflare: ^1.7
silverstripe/cms: ^3.1

NB: The plugin has been tested against Silverstripe 3.4 but has not been toroughly tested against all versions of Silverstripe 3.x. It should in theory work with all sub-version of Silversrtipe 3. If you come accross an issue using an older version of Silverstripe 3, log an issue or do a PR and I'll look into it.

Installation

composer require syrp-nz/silverstripe-cloudlfare-purger "^0.0"

Getting CloudFlare to cache your content

This plugin doesn't automatically configure SilverStripe or CloudFlare to automatically cache your web content.

Before installaing the plugin, you'll need to configure your SilverStripe site to play nice with CloudFlare.

Configuring CloudFlare to cache SilverStripe pages

Configuration the plugin

This plugin can be configured via a YML file or via the Site Configuration page. The YML configuration will have precedence over the Site Configuration. You can use a combination of both if you want.

The following configuration options are available:

• Email which should be your Cloudflare account's email address.
• AuthKey which is your Cloudflare account's AuthKey (can be obtain under My Settings > API Key)
• ZoneIdentifier which is the numeric identifier of the Zone to which your website domain belongs. There's not really any easy way of retrieving this in Cloudflare without using the API. This will appear as a user friendly drop down in your site configuration page.
• Paths which should be an array of absolute paths where your website can be accessed. If your website is only available under one path, you can leave this value blank.
• HideSiteConfig is an optional boolean value you can define, if you want to configure all Cloudflare settings in a YML file. Setting this value to true will hide the Cloudflare tab from your site configuration.

Sample YML file

CloudflarePurger:
  Email: [email protected]
  AuthKey: yourhexadecimalauthkey
  ZoneIdentifier: yourhexadecimalzoneid
  HideSiteConfig: true
  Paths:
  - "https://example.com/"
  - "http://example.com/"
  - "https://www.example.com/"
  - "http://www.example.com/"

Using the site config

All the parameters can be defined in your site configuration page without the need to edit any YML file.

If some values are defined via the YML file and the HideSiteConfig flag is undefined, those values will appear as readonly fields in your Site Configuration.

If your concerned about your AuthKey key being visible in the site configuration, make sure to set the HideSiteConfig flag to true.

How does the plugin work

The plugin defines a CloudflarePurgerExtension DataExtension.This extension can be applied to any DataObject class. It will automatically be applied to the SiteTree class.

If the DataObject supports versioning, a call will be made to the Cloudflare API on publication to attempt to purge the the URLs associated to this object. If the DataObject doesn't support versioning, the purge call will occur after each write.

The DataObject can expose a CloudflarePurgeLinks() method to specify which URLs should be purged. This method can return either a single URL or array of URLs. The URLs should be relative to the site root.

Otherwise, the Link() method will be called on your DataObject.

The plugin also attempts to detect when your site navigation changes. Site navigation changes will cause your entire CloudFlare zone to be purge.

Applying CloudflarePurgerExtension to a DataObject

If you have a Page type that relies on a child DataObject for its content or if your DataObject is accessible via its own URL, you should implement the CloudflarePurgerExtension on it.

You can do so via a YML file.

PromoDataObject:
  extensions:
    - CloudflarePurgerExtension

Here's how you could customise the URLs that get purged when the PromoDataObject gets saved.

class PromoDataObject extends DataObject {

    private static $db = [
        'SomeContent' => 'HTMLText'
    ];

    private static $has_one = [
        'Parent' => 'PromoHolderPage'
    ];

    public function Link()
    {
        // This DO can be accessed as a sub-action on the controller of its parent page through its ID.
        // If `CloudflarePurgeLinks` wasn't defined, the individual URL of this DO would be purge, but
        // not its parent.
        return $this->Parent()->Link($this->ID);
    }

    public function CloudflarePurgeLinks()
    {
        // The content of this DO is used when rendering the parent page. So when this DO is saved, we
        // want to purge the parent's page URL as well.
        return [$this->Link(), $this->Parent()->Link()];
    }

}