Download the PHP package aimeos/pagible-cdn without Composer

Pagible CDN

Purges changed pages and removed files of Pagible CMS from CDNs and caching proxies using FOSHttpCache. Supported are Cloudflare, Fastly and Varnish.

This package is part of the Pagible CMS monorepo.

Installation

Purge requests are sent by queued jobs on the CMS queue (CMS_QUEUE_CONNECTION, CMS_QUEUE), so run a queue worker:

Configuration

Settings are in config/cms/cdn.php. Each client is used as soon as its token or servers are set, all others are skipped:

Further settings:

Cache lifetime

Public pages are sent with Cache-Control: public, s-maxage=... using the cache time of each page, while pages with access rules and pages viewed by editors are private. As changed pages are purged, the CDN can keep pages longer, e.g. CMS_CDN_MAXAGE=86400. CMS_CDN_STALE=60 adds stale-while-revalidate and stale-if-error, so the CDN serves the old page while fetching the new one or if your server is unavailable. If CMS_CDN_MAXAGE is set, the Expires header is removed so the CDN can't use the shorter lifetime of the page instead.

Varnish must be configured to accept PURGE requests from the application servers, see the FOSHttpCache proxy configuration.

Stacked caches

If a CDN caches the responses of Varnish, the inner cache must be purged first, otherwise the CDN fetches the outdated page from the inner cache again. Set a longer delay for the CDN client, e.g. 'delay' => 10. cms:cdn:purge purges the clients in the configured order, so list the inner cache first. If the purge of the inner cache fails, the CDN may cache the outdated page again until its cache lifetime expires.

Several zones or services

Add a client per zone or service and limit it to its host names with hosts, e.g. for multi-domain setups with one Cloudflare zone per domain:

What is purged

• Pages: The same pages the complete-page cache of the theme package invalidates. Pages are purged when

  • a new version is published, also by scheduled publishing
  • the URL path or domain changes on publishing; the page is purged at its old and new URL
  • access rules are set or removed
  • the page is deleted or permanently removed, including its subpages
  • files they use are deleted from storage or moved to the private disk
  • editors use the "Clear cache" action

  Moving a page in the page tree doesn't change its URL and doesn't purge it. The URLs are generated from the cms.page route and CMS_CDN_URL or APP_URL, or the page domain if cms.multidomain is enabled. Without the theme package, no page URLs are purged.

• Files: The public URLs of files and previews deleted from storage or moved to the private disk. New uploads always get new file names, so their URLs never serve outdated content.
• Shared content: All pages which use a published, deleted or restored shared element or file. The pages are found by queued jobs on the core queue (CMS_QUEUE_CONNECTION, CMS_QUEUE), also if the items are finally removed. Pages using deleted items were purged when the items were deleted, so finally removing them doesn't purge them again.

Not purged are:

• URLs with query strings, e.g. search or pagination parameters. The CDN caches each query string separately, so configure it to ignore query strings for pages that don't use them, e.g. with a Cloudflare cache rule, or keep the cache lifetime of these responses short
• sitemaps, which are updated when their CDN cache expires
• other pages which show the changed page, e.g. in the navigation. They are updated when their CDN cache expires, so keep the cache lifetime of HTML pages short

Editors can purge a page and all its subpages with the "Clear cache" action of the admin panel. For the root page, this purges the whole site and large sites remove all content at once.

Commands

Removing all content is only supported by Cloudflare and Fastly.

Equal purges which are still queued aren't queued again, so large changes of shared content remove all content only once instead of once per batch of pages.

Removing all content also removes the cached images, CSS and JavaScript files, which are then fetched from your server again. If shared elements or files like the footer are used by more pages than the limit, each of their changes does this, so raise the limit or use 0 for large sites with frequent changes of shared content.

Protected content

Pages which get access rules and files moved to the private disk are only removed from the CDN by their purge. Until it succeeds, the CDN still serves the public copy:

• during the delay of the client
• until the cache lifetime (maxage) expires if the purge fails after all retries or with the sync queue, and during stale seconds while your server fails
• if the hosts of the client don't contain the host of the file URLs, e.g. cdn.example.com

For sites with protected content, use a real queue, keep maxage moderate and add the host of the public files to hosts.

Failures

Failed purges are retried after 10 seconds, 1, 5 and 15 minutes, also if the CDN API rejects requests because of its rate limit. Purges which failed after the last retry are stored as failed jobs by Laravel. Each client uses its own jobs, so a failing CDN doesn't delay the others. The job only contains the client name and URLs; credentials are read from the configuration when the job runs, so changed credentials apply to queued purges too and removed clients don't receive them any more.

With the sync queue, the URLs are purged after the response is sent to keep the admin panel fast. Failed purges are only reported then and not retried, so use a real queue in production.