Repository navigation
Page Cache
With Proxy Cache Purge active, PhotoPress keeps a Varnish or NGINX page cache current as images and image taxonomy terms change. The status appears in the Page cache and search index card on PhotoPress › Settings › Pages & Search.
- A page cache in front of the site, such as Varnish.
- Proxy Cache Purge (
varnish-http-purge), active and configured for that cache. Without it, PhotoPress sends no purges and nothing on this page applies. - PhotoPress purges image pages only while Attachment pages is on, and term archive pages only while Image taxonomy pages is on. See Attachment and Taxonomy Pages.
PhotoPress has no page cache settings. Proxy Cache Purge's own settings apply: how it sends purges, whether through WP-Cron, and when it empties the whole cache instead.
The Proxy Cache Purge status on the Pages & Search tab.
The Proxy Cache Purge row shows Active, Disabled (installed, not active) or Not installed.
| Change | Purged |
|---|---|
| An image's title, caption, description or slug edited | The image's page, while attachment pages are on. Every page of each of its terms' archives, while image taxonomy pages are on. |
| An image saved or deleted | Proxy Cache Purge purges it itself, since PhotoPress adds images' status (inherit) to the statuses it purges. PhotoPress's URL filter adds the term archives and drops the addresses listed under "What is left out". |
| An image joins or leaves a term, as when it is edited or reprocessed | The image's pages, with every page of the archives of the terms it joined or left. |
| A term renamed, given a new slug, or deleted, with 25 images or fewer | Each of its images' pages, with every page of the term's archive. On a rename, both the old and new archive addresses are purged. |
| A term renamed, given a new slug, or deleted, with more than 25 images | The whole cache is emptied. |
| A post's dynamic gallery gains, loses or reorders images (an image uploaded to it, attached, moved, detached, deleted, or given a new date or title) | The post's pages. |
| A page whose Child Pages Gallery shows a changed child page | That page's pages. |
| An image joins or leaves a term, or one of its images is edited or deleted | The published posts whose Taxonomy Gallery shows that term (Taxonomy Gallery). |
| An image uploaded, edited or deleted | The published posts whose Taxonomy Gallery shows the latest images. |
| An image's file replaced | The image's pages, with its old and new files. Also its parent post and the posts whose stored content was rewritten. Posts that show the image (in their content or as featured image) are purged too: always after Enable Media Replace, and after PhotoPress's own replace when the image's text changed with the new file. |
| A background job over images, such as re-reading their metadata | Nothing per image. The whole cache is emptied once, when the job ends, if any of its batches changed a page. |
| PhotoPress installed or updated | The whole cache is emptied on the first request that sees the new version. |
"Every page of an archive" means the archive address with Proxy Cache Purge's ?vhp-regex suffix, which purges the archive and its paginated pages.
- An image's own page address while attachment pages are off. It redirects to the file.
- The REST API addresses of an image's terms (
/wp-json/wp/v2/<taxonomy>/<id>/). Proxy Cache Purge adds them, but page caches do not cache the REST API and only editors can read these routes. - While both Attachment pages and Image taxonomy pages are off, PhotoPress sends no purges of its own for images. It also skips emptying the cache for a term change or a job.
- A second purge of the same post or image in the same request, unless it brings more URLs.
Proxy Cache Purge collects the URLs of a request's purges and sends them at the end of the request, or queues them for WP-Cron in its cron mode. When the collected URLs number 50 or more, it empties the whole cache instead. 50 is its default, set in its own settings or by the VHP_VARNISH_MAXPOSTS constant. Every URL counts toward it, including the term REST addresses PhotoPress removes and each image a job batch changes.
PhotoPress runs long operations as background jobs, in batches.
- During a batch: PhotoPress sends no purges for the items it changes. Proxy Cache Purge's own image purges are suspended for the batch.
- After a batch that would have purged: the job is recorded.
- When the job ends: the cache is emptied once.
- If the job is cancelled during such a batch: the cache is emptied at once.
A Child Pages Gallery is built when the page is viewed, so the parent page's stored content never changes. PhotoPress announces the parent page as changed (photopress_post_changed), and so purges it, when a child page changes in a way the gallery shows:
- A child page published, unpublished, trashed or deleted.
- A child page moved to another parent. Both parents are announced.
- A child page's title, slug or page order changed.
- A child page's featured image added, changed or removed.
- For a child page without a featured image: its content changed, or the images its gallery shows changed.
The parent is announced only when it shows its child pages: a Child Pages Gallery or a legacy Child Pages block in its content, or either block in any template or template part edited in the Site Editor (showsChildPages).
One template or template part edited in the Site Editor that holds either block makes every page count as showing its child pages.
A Taxonomy Gallery that chooses its own images (a term's, or the latest) is filled when the page is viewed. PhotoPress records each such gallery when the post is saved, in the post meta _photopress_gallery_terms, and purges the post when its images may have changed:
| Gallery shows | Purged when an image… |
|---|---|
| A term's images | joins or leaves the term, or one of its images is edited (title, caption, slug) or deleted |
| The latest images | is uploaded, edited (title, caption, slug) or deleted |
The posts are announced with photopress_post_changed. Only published posts are announced, up to 200 per change. None are announced during a background job's batch, because the whole cache is emptied when the job ends. Posts saved before PhotoPress 2.0 are recorded by a one-off background job after the update (Background Jobs). A Taxonomy Gallery on an archive template shows the archive's images and is purged with the archive page.
A Taxonomy Gallery in a template, template part or synced pattern, outside an archive, is not recorded, because it has no page of its own. The pages that show it stay cached until they expire. A gallery in random order shows a new selection only when its page is purged or expires.
When Proxy Cache Purge is not installed or not active, PhotoPress sends nothing. Pages stay cached until the cache's own expiry. The settings card shows what activating Proxy Cache Purge would do.
| Hook | Type | Code | Purpose |
|---|---|---|---|
attachment_updated |
action | PageCache.php#L83 | Purges an image whose post_title, post_excerpt, post_content or post_name changed (imageEdited()). |
wp_loaded |
action | PageCache.php#L85 | Empties the cache when photopress_version differs from the running version (versionChanged()). |
added_term_relationship, deleted_term_relationships, edit_terms, edited_term, pre_delete_term, delete_term
|
action | TermChanges.php#L55 | Turned into photopress_image_terms_changed and photopress_term_images_changed (TermChanges). |
wp_after_insert_post |
action | TaxonomyGalleryPages.php#L48 | Records a saved post's query galleries in _photopress_gallery_terms (record). Not for revisions, autosaves or post types without pages |
add_attachment, attachment_updated, delete_attachment
|
action | TaxonomyGalleryPages.php#L50 | Announces the posts whose galleries may show the image (announce) |
PhotoPress hooks it listens to:
| Hook | Code | Purpose |
|---|---|---|
photopress_post_changed |
PageCache.php#L80 | Purges the post, with $context['files'] (postChanged()). |
photopress_image_terms_changed |
PageCache.php#L81 | Purges the image with $context['archives']. Skipped when $context['job'] is true (imageTermsChanged()). |
photopress_term_images_changed |
PageCache.php#L82 | Empties the cache, once per request (purgeAll()). |
photopress_job_batch_started |
PageCache.php#L87 | Starts holding back purges (batchStarted()). |
photopress_job_batch_ended |
PageCache.php#L88 | Records the job if a purge was held back. Empties the cache at once if the job was cancelled (batchEnded()). |
photopress_job_ended |
PageCache.php#L89 | Empties the cache for a recorded job (jobEnded()). |
Data stored:
| Option | Content |
|---|---|
photopress_version |
The PhotoPress version the cache was last emptied for. Autoloaded. |
photopress_purge_after_jobs |
IDs of jobs whose batches held back purges. Not autoloaded. Deleted when empty. |
_photopress_gallery_terms (post meta) |
One row per Taxonomy Gallery that chooses its images: <taxonomy>:<term ID>, or latest. Rewritten when the post is saved. Deleted on uninstall. |
PhotoPress uses only Proxy Cache Purge's documented filters. It never calls the plugin's functions or reads its settings. All PhotoPress logic is in PageCache.php.
| Hook | Type | Code | Purpose |
|---|---|---|---|
varnish_http_purge_events |
filter | PageCache.php#L75 | Registers two events: photopress_purge_post (a post or image, by ID) and photopress_purge_all (events()). |
varnish_http_purge_events_full |
filter | PageCache.php#L76 | Marks photopress_purge_all as an event that empties the whole cache (fullEvents()). |
varnish_http_purge_valid_post_statuses |
filter | PageCache.php#L77 | Adds inherit for images, except during a job's batch (statuses()). |
vhp_purge_urls |
filter | PageCache.php#L78 | For an image: removes its own page while attachment pages are off, removes its terms' REST addresses, and turns its term archives into ?vhp-regex purges. Adds the extra URLs given with PhotoPress's event (urls()). |
PhotoPress treats Proxy Cache Purge as active when it listens for photopress_purge_post (purges()).
| Hook | Type | Arguments | When | Code |
|---|---|---|---|---|
photopress_purge_post |
action (Proxy Cache Purge event) | int $id |
PhotoPress purges a post or image. | PageCache.php#L313 |
photopress_purge_all |
action (Proxy Cache Purge event) | none | PhotoPress empties the cache. | PageCache.php#L325 |
photopress_job_batch_started |
action |
array $job (id, type, status…) |
A batch of a background job starts, in this request. | Jobs.php#L311 |
photopress_job_batch_ended |
action |
array $job, status running, done or cancelled
|
A batch ended, in this request. | Jobs.php#L376 |
photopress_job_ended |
action | array $job |
A job finished, was cancelled, or was abandoned because its job type is no longer registered. | Jobs.php#L391 |
photopress_post_changed, photopress_image_terms_changed and photopress_term_images_changed are described on Image Search and Hooks Reference.
- The 25-image threshold for a renamed or deleted term is fixed (
TermChanges::NOW). - A job's single emptying of the cache happens at its end. Pages changed early in a long job stay stale until then.
- Proxy Cache Purge's 50-URL limit can still be reached when many posts change in one request, for example a replaced image shown in many posts.