Cloudflare

This plugin makes it possible to purge Cloudflare caches directly from Craft CMS. You can initiate purges manually, either for individual URLs or an entire zone, and configure the plugin to automatically purge Entry and Asset URLs when they’re updated.

License #

This plugin is licensed for free under the MIT License.

Requirements #

This plugin requires Craft CMS 3.6.0 or later, or 4.0.0 or later, or 5.0.0 or later.

Installation #

To install the plugin, search for “Cloudflare” in the Craft Plugin Store, or install manually using composer.

composer require putyourlightson/craft-cloudflare

Configuration #

After you’ve installed the plugin, visit Settings → Cloudflare and add your API credentials and the Cloudflare Zone for your site.

Choosing an Authentication Method #

The plugin supports both methods of authentication with the Cloudflare API:

An account-level API key
A scope-limited API token

If you use an API token, be sure it has cache_purge:edit and zone:read permissions at minimum for whatever zone you plan to use.

Zone Permissions #

Once it has API credentials, the plugin will attempt to read all the zones on your account so you can select one from a convenient dropdown list. If your token’s permissions don’t permit zone listing, you’ll need to specify the relevant Zone ID from a static config file:

<?php
// config/cloudflare.php
return [
    'zone' => 'YOUR_ZONE_ID_HERE'
];

This will hard-code that Zone ID and disable the listing UI in the control panel.

You can also use config/cloudflare.php to provide any settings you’d like, rather than setting them up in the control panel:

<?php

return [
    'apiKey' => '',
    'email' => '[email protected]',
    'zone' => '', // zone ID
    'purgeElements' => [
        'craft\elements\Asset',
    ],
];

If you’d like to use environment variables, you can do that too:

<?php

return [
    'apiKey' => getenv('CLOUDFLARE_API_KEY'),
    'email' => getenv('CLOUDFLARE_EMAIL'),
    'zone' => getenv('CLOUDFLARE_ZONE_ID'), // zone ID
];

The authType, apiKey, email, zone, and apiToken parameters will also be parsed for environment variables, so you could supply each like so:

<?php

return [
    'authType' => 'token',
    'apiToken' => '$CLOUDFLARE_API_TOKEN',
    'zone' => '$CLOUDFLARE_API_ZONE',
];

Once you’ve added your credentials, use the “Verify Credentials” button to test them. This will attempt to list zones with an API key, or call the token verification endpoint with an API token. Individual token permissions won’t be checked, only that the token is valid.

Settings #

Cloudflare API Key + Cloudflare Account Email #

If you’ve chosen “Key” for your auth type, you’ll need to provide the Global API Key you’ll find in My Profile in Cloudflare’s control panel along with your Cloudflare account email address.

Cloudflare API Token #

If you’ve chosen “Token” for your auth type, provide the app token you set up. Be sure it has cache_purge:edit and zone:read permissions.

Cloudflare Zone #

Choose relevant Cloudflare Zone for your site. Once you save the plugin settings, the Cloudflare plugin will be ready to do stuff. If you’re hard-coding the zone setting, it needs to be the related Zone ID (not name!) for the site.

Automatically Purge Entry URLs #

If enabled, any time an entry with a URL is updated or deleted, the plugin will send its URL to Cloudflare to be purged. This can be helpful if you’re fully caching your site, and you’d know if you were. By default, Cloudflare only caches static assets like images, JavaScript, and stylesheets. If you want to cache your site’s HTML, you’ll need to use Cloudflare’s Page Rules to do that regardless of whatever HTTP headers are sent with your page responses.

Automatically Purge Asset URLs #

When enabled, as it is by default, the plugin will automatically have Cloudflare purge caches whenever an Asset with a URL is updated or deleted. This solves the common problem of re-uploading an image and not seeing it change on the front end because Cloudflare’s hanging onto the version it cached.

Purge Individual URLs #

This isn’t a setting, just a tool in an awkward place. Add whatever absolute URLs you want, one per line, and choose Purge URLs to have Cloudflare try and purge them.

Purge Cloudflare Cache #

This one button will purge the entire cache for the zone you’ve specified. Be very sure you want to push it.

Purging #

Manually Purging Caches #

You can manually purge individual URLs or the entire zone, either from the plugin settings page or via the convenient Cloudflare Purge Dashboard widget, whose function is identical but with a more elegant façade.

Automatically Purge URLs #

You can use the previously-mentioned Automatically Purge Entry URLs and Automatically Purge Asset URLs settings to proactively clear caches on specific URLs immediately after actions are taken in the control panel. You can also use simple pattern rules to clear specific URLs. (See Rule-Based Purging below.)

Console Commands #

Clear your entire zone cache or specific URLs from the console! Useful for deployments.

#- Purge entire zone
./craft cloudflare/purge/purge-all

#- Purge comma-separated list of urls
./craft cloudflare/purge/purge-urls https://foo.com/wombat.jpg,https://cdn.foo.com/stoat.jpg

Purge Rules #

This timid feature, found in the Clouflare Utility, allows you to add rows to a table that define simple rules for clearing specific URLs. If you’ve cached your blog index, for example, at /blog, and you post a new entry at /blog/my-new-entry, you’re going to want your index purged so the new post shows up. In this case, you’d add a URL Trigger Pattern of blog/*, and blog in the Clear URLs column. (You can list a new relative URL on each line, just know that Cloudflare will only accept up to 30 of them per API request.)

Extending #

The plugin exposes services for working with Cloudflare’s API and simple URL-based purging rules specific to the Craft install.

API Service #

The API service is a small wrapper for Cloudflare’s REST API.

`getZones()` #

Returns a list of zones available for the supplied Cloudflare account. Each zone is basically a domain.

`purgeZoneCache()` #

Purges the entire zone cache for whichever zone you’ve specified in the plugin’s settings.

`purgeUrls(array $urls)` #

Purges the supplied array of absolute URLs. These URLs must use the same domain name as the zone or it won’t work.

RulesService #

The rules service deals with custom purge rules you can configure based on the URL of an element being updated.

`getRulesForTable()` #

Returns all RuleRecords formatted for the simple editor at /admin/cloudflare/rules.

`saveRules()` #

Saves rules from the editor, automatically converting the second column’s lines to a JSON array.

`purgeCachesForUrl(string $url)` #

Takes the supplied URL and purges any related URLs as defined by matching rules.

`getRulesForUrl(string $url)` #

Returns an array of RuleRecords whose trigger pattern matches the supplied URL.

Troubleshooting #

The plugin will alert you from the beginning if your credentials are incorrect, but you can check Craft’s web.log if you need to dig further. The Cloudflare plugin traces its initialization as well as any attempts to clear URLs or an entire zone. Each API interaction will include the ID Cloudflare responded with and any relevant URLs.

Have a suggestion to improve the docs? Create an issue with details, and we'll do our best to integrate your ideas.

Purge Cloudflare caches from Craft.