CacheManager::purgeConfiguredPath() is the single transition from a purge
request to local deletion and follow-up work.
| Trigger | Route | Immediate effect | Deferred effect |
|---|---|---|---|
| Content/user/term/option hooks | AutomaticPurgeSubscriber → merger → queue or CacheManager |
None when queued; otherwise validated local/endpoint purge | Successful non-dry runs may queue prewarm, layer sync, remote purge, or Cloudflare |
| Admin purge action | SettingsPage → CacheManager |
Capability/nonce-gated local or endpoint purge | Same side-effect queue |
REST /purge |
CacheRestController → queue or CacheManager |
URL/site/network meta capability; REST nonce for cookie authentication; URLs must be same-origin | Same side-effect queue |
CLI nginx-cache:purge |
PurgeCommand → queue or CacheManager |
Explicit local, endpoint, or dry-run purge | Same side-effect queue |
CLI nginx-cache:config --section=... |
ConfigCommand → NginxConfigGenerator |
Prints HTTP/server/logging/FastCGI include text; no directory creation, file deletion, server reload or remote request | None |
| Dashboard / diagnostics KPIs | CacheStatusInspector, queue/tag stores, CacheMetricsReader |
Read-only cache scan, database counts and bounded private log read | None; Nginx writes metric records only after an operator applies the logging include |
| Purge queue hook | PurgeQueueProcessor → CacheManager |
Drains merged purge requests | Successful requests may create side-effect tasks |
| Side-effect hook/CLI | PurgeSideEffectProcessor |
Resumes partial site scans through the validated CachePurger lock |
Prewarm, cache-layer sync, signed remote dispatch, Cloudflare dispatch after the scan finishes |
CLI nginx-cache:work |
CacheWorker → queue processors |
Runtime/task-bounded processing; network mode visits only durable pending site IDs | Same scoped side-effect queue; worker heartbeat |
| Anonymous cacheable response | SurrogateTagSubscriber → TagIndexRepository |
Registers canonical URL/tag mappings; fresh identical mappings issue no writes | Schedules tag maintenance |
Anonymous GET/HEAD 404 (nocache_headers filter) |
NotFoundCacheSubscriber |
Replaces WordPress' no-store headers with Cache-Control: public, max-age=60 so Nginx honors the generated one-minute 404 rule; logged-in, admin, AJAX, cron and authorized requests keep no-store |
None |
Keep-warm cron (sympress_nginx_cache_keep_warm), scheduled on init |
KeepWarmRefresher → Prewarmer |
Only with prewarm enabled and retention keep_warm: same-origin, five-second GET requests (same-origin redirects revalidated, at most three hops) for at most five planned prewarm targets per tick; no purge, filesystem deletion, queue or tag-index mutation |
Schedules the next batch after one second, or the next cycle at half the inactivity timeout; records keep_warm diagnostics |
| Tag-maintenance cron / side-effect tick | TagIndexMaintenance |
Deletes at most 500 index rows per call under the index mutation lock, enforcing TTL and retention limits | Schedules another maintenance event; no filesystem deletion or HTTP |
The plugin-list settings link is registered through
plugin_action_links_ns-nginx-cache/ns-nginx-cache.php, matching the Composer
and archive entry. It only links to the settings page and triggers no purge.
Tag retention no longer prunes on each insertion. Maintenance commits the
bounded batch in one transaction and rolls back its rows and metadata on
failure, invalidating WordPress option caches. It uses the current site's
table and limits; global tag age is its newest URL timestamp. The
sympress_nginx_cache_prune_tags event runs independently of purge work and is
cleared on explicit data-deleting uninstall. Dry runs never invoke maintenance.
With WP-Cron disabled, idle sites require an external cron runner for due events.
Failed batches reschedule the consumed event before propagating the error.
Simple-mode changes and preset application require the manage capability and a nonce. Preview is read-only; applying a preset changes only writable settings, respecting constant and network ownership. Neither action modifies Nginx files, reloads the server, starts a purge or installs system cron.
When Polylang is available, public translation APIs expand the existing content URL/tag collection. Language changes request the existing site-scoped full purge. The same URL validation, capability, queue and dry-run boundaries apply. Prewarm planning orders affected URLs before home, archives and sitemap entries; the configured rate limit applies within each site's bounded worker task.
Changes to non-public post types or taxonomies, such as stored contact forms or block pattern categories, request a full site invalidation because their own permalinks cannot identify the public pages that embed them. These internal permalinks and unpublished posts are excluded from affected prewarm URLs. The full request still warms configured public URLs and sitemap entries, without attempting to fetch the internal object itself.
Requests default to site scope, including legacy queue records. Site and
network requests never merge. In Multisite, a shared local root is scanned under
the existing purge lock. Only a parsed Nginx KEY: matching the current site's
hosts and longest matching network path is removed. Unknown keys remain and are
reported. Each chunk reads at most 4096 header bytes per file and scans at most
20,000 files or ten seconds; a durable cursor resumes unfinished scans. Dry runs
never persist a cursor. Single-site installations retain their full-root purge.
SYMPRESS_NGINX_CACHE_SITE_ISOLATED_PATH=true explicitly confirms separate roots.
Redis uses literal host/path prefixes for both supported key formats and parses
every returned key again before deletion. A Multisite site full purge never
flushes Cloudflare's entire zone: it uses site:<blog_id>. Global object-cache
and OPcache flushes require explicit network scope in Multisite. Custom layer
hooks receive the scoped result and must preserve its ownership boundaries.
--network --full selects one network purge; --network otherwise processes
each site separately. No failed scoped backend falls back to a broader purge.
Multisite full HTTP endpoints require
SYMPRESS_NGINX_CACHE_ENDPOINT_SUPPORTS_SITE_SCOPE=true. The receiver must
enforce X-SymPress-Purge-Scope, X-SymPress-Purge-Host,
X-SymPress-Purge-Path, and the base64 JSON X-SymPress-Site-Boundaries
(roots and all same-host paths, longest prefix wins). The HMAC input is
timestamp.full-purge.scope.host.path.boundaries for a site, or
timestamp.full-purge.network for the network. Existing single-site endpoint
signatures remain timestamp.full-purge. Excessive ownership metadata fails
closed. The endpoint must reject missing boundaries or unsupported scopes.
Configuration resolves constants first, then published locked network values, site values, network defaults, and code defaults. Existing networks retain site configuration until values are explicitly adopted. Cache roots, backends, connections, credentials, key templates and purge roles become locked once published. A generic option-write filter rejects site overrides of locked values, including forged settings submissions. Adopting network configuration does not replace the original site options. Meta capabilities are mapped at runtime and never added to role records.
Network queue producers maintain generation-tagged pending markers under a network-wide advisory lock; contention retains durable per-site inbox markers. Workers clear a marker only when both queues are empty and its producer generation is unchanged. Queue work executes under the existing process locks; no network pending lock is held during purge or provider I/O.
Configuration export is read-only. Applying its HTTP include and restarting or
reloading Nginx is an explicit operator action; Nginx then creates the configured
cache root. Keep the plugin path and fastcgi_cache_path identical, and grant
the PHP and Nginx process users access to that dedicated root. Existing path
validation, purge locks and private-request bypass rules remain in force.
composer tests:nginx uses a temporary cache root and a loopback-only Nginx
instance, stops its own process and removes only that fixture on completion.
Sitemap prewarming is opt-in and runs inside the existing deferred prewarm task
after full purges or explicit prewarm requests with no URL list. It does not run
on dry purges. Discovery follows only same-origin index entries, prohibits HTTP
redirects and XML DTD/entities, limits each streamed XML response to 2 MiB, visits
at most 20 maps, and shares the configured 0..200 URL budget with explicit URLs.
Discovery failures remain prewarm errors and retain the task for retry, but they
no longer block targets that are already known; see the follow-up queue below.
Each failed map is reported as <sitemap URL>: <fixed reason>, distinguishing
HTTP status, idle or five-second timeout, other request failures, the 2 MiB
budget, invalid XML, non-sitemap documents and forbidden XML declarations; a
configured sitemap outside the site origin is reported without its URL. Provider
exception messages and response bodies are never stored. The newest failure (at
most five reasons and a timestamp) is kept in the non-autoloaded
sympress_nginx_cache_sitemap_discovery_failure option, exposed as
sitemap_discovery_failure in side-effect details and prewarm diagnostics, and
deleted by the next successful discovery.
MultisiteMapGenerator::refresh() handles site creation/update/deletion and
admin initialization. Without the private SYMPRESS_NGINX_CACHE_MULTISITE_MAP_FILE
constant it performs no file writes. The absolute .conf destination and its
parents must not be symlinks; data is validated before atomic replacement.
Unchanged content is left untouched and failures retain the prior map and expose
a network-admin error. No Nginx reload occurs. Multiple networks must have
separate destinations. The HTML stamp is independently opt-in, runs at shutdown,
and writes only a fixed-format anonymous text/html comment, never JSON/XML,
authenticated/admin/login, REST, cron or AJAX responses.
The optional purge_backend setting selects local files (the existing default),
Redis page-cache keys, or same-origin Nginx GET /purge/<path> requests. All
entry points still pass through CacheManager, history, events, and the durable
side-effect queue. Redis uses a lazy Predis connection with TCP/ACL or Unix socket
credentials; its password uses the existing authenticated encryption and empty
password-field preservation. Full Redis purges use bounded SCAN/DEL batches only
under a nonempty literal, site-dedicated prefix, never FLUSHDB or FLUSHALL. A
budget-exhausted scan fails and remains retryable. Dry runs perform no Redis I/O.
Selective keys cover GET/HEAD, HTTP/HTTPS and both SymPress and nginx-srcache's
concatenated key format. The server's cache key must match one of these formats.
HTTP URL purges validate every URL before the first request, keep functional queries, prohibit redirects, and require the existing signing secret. Protect the Nginx location with an IP allowlist and/or a signature verifier; a purge module alone does not verify the added signature headers. HTTP 404 means already absent; other non-2xx responses fail and retain queued work. Full HTTP purges require the existing protected full-purge endpoint; they never fall back to deleting disk files. Redis/HTTP modes do not require access to the local Nginx cache directory.
CachePathValidatorrejects unsafe/unmanaged paths;CachePurgerlocks the validated directory and preserves its sentinel and lock files.UrlPolicyrestricts URL purges to same-origin URLs and rejects unsafe remote destinations. Remote requests have no redirects and finite timeouts.- Full endpoint and remote payloads are signed when their configured contract requires a secret.
- A dry run resolves the purge but skips deletion, directory/sentinel/lock creation, tag-index mutation and the side-effect queue. It checks an existing lock without writing it; without a lock, the preview is a best-effort filesystem snapshot. A missing root is reported without creating it. Empty hexadecimal Nginx levels remain a recognized cache layout after expiry. History/events may still record the probe.
- Side effects run only after a successful non-dry purge and are inspectable via
nginx-cache:side-effectsbefore flushing.
The purge-rule matrix separates home, singular pages and archives/listings for edit/publish, deletion/trash, new/approved comments and removed/unapproved comments. Defaults preserve the existing all-scope behavior. Limited scopes use explicit URL invalidation instead of shared surrogate tags, so Cloudflare also receives URLs rather than tags that could invalidate a disabled scope. Once a rule is customized, generic post/comment cache-clean hooks are omitted because they cannot distinguish edit/delete/comment intent; explicit content hooks and comment status transitions retain that context. Unapproved new comments are no-ops. Whole-cache modes, imports and the documented queue-overflow full purge remain whole-cache operations. Use selective mode for the matrix's URL scopes.
TagIndexRepository::install() runs at init priority 5. It creates the site's
{$wpdb->prefix}sympress_cache_tags InnoDB table and migrates the legacy
sympress_nginx_cache_tag_index option once. The legacy option is deleted only
after the schema version is saved. Failed installation retains the source for
retry. WordPress 6.2 or later identifier placeholders are required. The database
account needs CREATE for installation, ordinary SELECT/INSERT/DELETE permissions
for operation, and DROP only for explicitly enabled uninstall.
The index stores individual (tag, sha256(url)) rows. New registrations remove
tracking query strings from canonical index URLs. Tracking-only queries (utm_*, gclid,
fbclid, msclkid) share the query-free FastCGI cache key in generated snippets,
so distinct tracking values reuse the same cached response. Queries containing
other parameters retain the bypass policy unless explicitly allowlisted.
Semantic and mixed queries are excluded from the index before any database call.
If an operator explicitly caches semantic query variants, use matching URL or
full purges; the default tag index does not describe those custom cache entries.
Regenerate and reload existing snippets; deploy the cache-key change together
with purge tooling. Tracking values must not personalize cached HTML.
An unchanged retained URL mapping performs reads only: no option rewrite, timestamp touch, transaction or write lock. Changes are serialized per site with a nonblocking database advisory lock and committed as one transaction. Registration accepts at most 64 tags, retains at most 1,000 tags and 50 URLs per tag, and removes excess rows in bounded batches. Retention uses the last mapping change, not the last anonymous page view. A URL whose mappings have been evicted can register again. No process-local object cache is authoritative for this table. Changing a post uses its own post tags; shared site, author and collection tags cannot pull unrelated posts into that purge. Author and taxonomy archive URLs are collected explicitly.
Both queues retain each task until success. Database mutation locks are scoped by database, table prefix and queue name. Execution uses a separate process lock; producers can enqueue while HTTP or filesystem work runs. Purge producers first persist uniquely named immutable option inbox items without acquiring the merge lock. Workers acknowledge inbox items only after the merged request is durable. Existing option queue data and retry budgets remain compatible. Contended workers return immediately and retain queued and inbox data for retry; filesystem purge locks are also nonblocking. Optional anonymous tag registration skips a contended index lock and retries on a later uncached response. Each merged inbox item creates a new aggregate generation, including identical URLs, so an invalidation arriving during execution survives acknowledgement. Option caches, including cached absent options, are invalidated before reading. Failed/exceptional purges and prewarm/provider/layer work remain queued. Both queues reserve each attempt in storage before executing it, including attempts that throw or crash. Each merged purge request or side-effect task has at most five automatic attempts. Failures wait 60, 120, 240 and then at most 300 seconds before the next attempt. Early workers and CLI flushes respect the persisted due time. Exhausted work remains in the queue and schedules no further automatic execution. New purge events retain the existing retry budget, including exhausted work; their URLs remain merged and inspectable. New side-effect tasks have their own budget and can proceed past failed or exhausted tasks. When a successful purge overlaps a producer enqueue, the retained new generation gets a fresh budget; successful activity cannot exhaust a busy queue.
nginx-cache:queue and nginx-cache:side-effects show pending and exhausted
counts. Their details action prints JSON containing the retained request,
attempt count, due timestamp, exhaustion and completed side effects. After
resolving an error, use nginx-cache:queue retry or
nginx-cache:side-effects retry to explicitly reset the pending retry budgets
and schedule processing. This does not run a purge immediately. flush runs due
work and reports failure if anything remains pending. The WP-CLI equivalents are
wp nginx-cache queue details, wp nginx-cache queue retry,
wp nginx-cache side-effects details and wp nginx-cache side-effects retry.
Retry preserves the request payload and successful side-effect checkpoints.
Local purge queue details also include last_failure: the failure timestamp,
processing phase (purge, acknowledge or queue) and the existing safe purge
result message. Caught exceptions retain only their class, numeric code, source
basename and line; raw exception messages, absolute paths and traces are omitted
because they may contain provider credentials. The same record appears under
queue.last_failure in the existing capability-gated diagnostic report. It is
stored as one non-autoloaded option per site, preserved across explicit retry,
and cleared when the queue drains successfully or is explicitly drained.
Failure recording never changes the request, retry reservation, lock or generation.
Only the worker holding the process lock writes or clears the retained diagnosis;
contenders emit a log signal without overwriting the owner's failure evidence.
A credential-free structured log signal remains available if diagnostic storage
is unavailable; result messages are deliberately excluded from that log signal.
Successful cache layers and individual remote endpoints are checkpointed before
processing later providers. Successful prewarm and Cloudflare work are also
checkpointed. A failing provider therefore does not replay acknowledged actions.
The worker processes at most one due task per tick and five prewarm URLs per
batch. Its prewarm-plan: checkpoint retains a bounded JSON target list, and
prewarm-url: checkpoints retain hashes of settled URLs: warmed targets and
outdated targets that are skipped rather than retried. The prewarmer sends every
request with max_redirects: 0 and follows a same-origin Location itself for at
most three hops, revalidating each hop with UrlPolicy; external targets, loops
and longer chains are skipped. Other 3xx and 4xx responses (except 408, 425 and
429) and plan entries outside the current site origin are skipped as outdated.
Timeouts, 408/425/429 and 5xx responses stay failures. A 2xx response counts as
warmed only after its body arrived completely, because Nginx stores no entry for
an aborted transfer: the body is streamed with buffer: false inside the same
five-second limits and each chunk is discarded. A transport error or idle timeout
after the headers stays a retryable failure with the fixed reason "HTTP 2xx
response transfer was incomplete". Each batch replaces the
attempted URLs' entries in the non-autoloaded sympress_nginx_cache_prewarm_issues
option (at most 20: URL, fixed reason with HTTP status, timestamp, stale flag),
exposed as prewarm_issues in side-effect details and prewarm.issues in
diagnostics. Redirect targets, response bodies and exception messages are never
stored. Uninstall removes the option with the sympress_nginx_cache_ prefix.
Ordinary successful
continuations undo their reservation and resume after at least one second without
resetting previous failures. Failed batches keep their reserved backoff and retry
only unacknowledged URLs. The five-attempt budget still bounds actual failures and
crashes. New tasks and overflow generations cannot inherit another task's progress.
Sitemap discovery occurs once before the first batch and retains its existing
20-map / five-second-per-map limits. Only a complete discovery becomes the
prewarm-plan: snapshot. When discovery reports errors, the targets it already
knows (fixed prewarm URLs, the home page and entries of maps that did load) are stored
as a bounded prewarm-known: snapshot and warmed in ordinary batches that do not
spend the retry budget; layer, remote and Cloudflare work runs in the same
invocations. Once every known target is settled, the task fails without the
prewarm checkpoint, so the missing discovery spends one bounded retry with
backoff. Discovery runs again on every retry, that is after any failed
invocation (a prewarm-discovery:<attempts>@<time> checkpoint records the
reserved attempt of the last failed discovery), but not in budget-free
continuation batches; a known target that keeps failing therefore cannot
postpone it. Further failures add only new known targets, and a successful
discovery stores the complete plan, warms only targets without a
prewarm-url: checkpoint and completes the task. The
sympress_nginx_cache_side_effects_processed payload reports this as
prewarm.discovery_complete. Explicit CLI prewarm is synchronous.
Keep-warm retention is separate from purge follow-up work. Nginx has no
inactive=off; the generated inactive value is always the configured finite
timeout. In the default keep_warm mode, KeepWarmRefresher re-requests the
planned prewarm targets every max(60, inactive_seconds / 2) seconds; each
cache lookup renews that entry's inactivity timer, and stale entries refresh
through the generated background update, so retention never extends validity.
A cycle snapshots its target plan once, attempts every target once in batches of
five, reports failed, skipped (outdated) or undiscoverable targets in last_failure without
retrying them within the cycle, and logs a URL-free signal. A successful cycle
clears the evidence. overdue and Site Health (critical) report a missing cycle
once a full inactivity window has elapsed since the last completed cycle; before
the first completion the window counts from the first cycle's start (also when
it crashed before planning), and before any start from its due cron event. A
recent start-up or an event that is not yet due stays unremarkable, a disabled
keep-warm never alarms, and a worker heartbeat never substitutes for a completed
cycle. Other entries, and all entries in
evict_inactive mode, remain subject to the inactivity timeout; max_size
eviction under storage pressure applies in both modes. Purges are unaffected and
remove refreshed entries normally. A due event after opting out makes no request
and deletes its state. The state option is non-autoloaded, removed by the
uninstall prefix sweep, and its cron hook is cleared on explicit uninstall.
Delivery remains at least once: a crash or storage failure between the external action and its durable checkpoint can cause a repeat, so receivers and adapters must accept repeated invalidation calls. Queue lock contention prevents unreserved execution and schedules another attempt after at least 60 seconds. Contended side-effect producers retain their original payload and identity in immutable, uniquely named inbox records; no provider-wide purge or storage-error signal is caused by ordinary contention. The active queue remains bounded to 50 tasks; inbox ingestion reads at most 64 records per batch and acknowledges them only after the merged queue is durable. Production must run WordPress cron externally and monitor pending and exhausted work in both queues. Side-effect capacity is 50, including exhausted tasks. Overflow coalesces retained selective work into a fresh full invalidation, with a new identity, empty checkpoints and a bounded retry budget. This includes whole-zone Cloudflare invalidation when that provider is configured. Completed actions cannot acknowledge the fresh generation. Local purge success is retained when optional external queue storage is unavailable; an Admin notice and a credential-free deduplicated log message expose the problem. The next successful enqueue or explicit side-effect retry schedules a full recovery invalidation only after genuine storage failure has lost an invalidation. Exhausted local and external work is visible in Admin and CLI. Corrupt producer inbox payloads are quarantined as private options while valid requests continue. The existing purge URL overflow policy remains an explicit full purge above 500 URLs.
Only entirely tracking queries share a query-free tag-index identity. Functional
queries such as ?s=foo, ?p=123 and mixed tracking/search queries bypass the
default Nginx cache and never enter the index, displace the home page's tags, or
issue tag-index database calls.
WordPressOptionLockStore uses atomic INSERT IGNORE and conditional UPDATE/DELETE
against the observed serialized token. It reads ownership directly from the
database. WordPress add_option() is not an atomic lock acquisition primitive:
its duplicate-key update can overwrite another contender after concurrent cached
absence. An expired owner cannot refresh or delete a replacement owner's lock.
OptionMutex uses connection-owned GET_LOCK with zero wait and RELEASE_LOCK without lease expiry;
acquisition failure throws before any mutation. Database connection termination
releases advisory locks. See the MariaDB GET_LOCK contract
and WordPress identifier placeholders.
Automatic registration handles future actions with their arguments; it never
replays did_action() without the original event. IDs are interpreted only by
the specific post, comment, user, term or WooCommerce hook. Draft-only transitions
and unpublished products do not invalidate public cache. Product transient
clears with no product ID are no-ops. Term cache events (clean_term_cache) for WooCommerce's
internal product_visibility, product_type and product_shipping_class
taxonomies, for example when a product sells out, are left to the product hooks
instead of purging the whole cache; other non-public taxonomies still purge fully.
product_variation is excluded from the post hooks by default for the same reason
while it is not viewable: it would force a full purge, while the WooCommerce
product hooks already purge the parent product. When a plugin makes variations
viewable, their own pages are purged selectively again. Missing URLs never implicitly become a full
purge. Theme, navigation, permalink and upgrader events retain their explicit
full-purge policy. Changes to the site title, tagline, site icon, front-page and
posts-page settings, posts per page, widget placement (sidebars_widgets) and
the per-type widget options of registered widgets (widget_<id_base>) also
trigger a full purge, because their output appears on every page; update_option_*
fires only when the stored value changes. Pending automatic purges are
grouped by the blog that was current when their hook fired and run in that
blog at shutdown, so changes made through switch_to_blog() purge the site
they belong to. Sites created in the same request (wp_initialize_site) are
skipped because they have no cache yet. A failed immediate purge falls back to the durable queue.
Cloudflare API tokens and remote signing secrets use authenticated XChaCha20
Poly1305 encryption bound to the individual option name. ext-sodium is required.
The private SYMPRESS_NGINX_CACHE_ENCRYPTION_KEY constant (at least 32 bytes) takes
precedence; otherwise valid private WordPress AUTH_KEY and SECURE_AUTH_SALT supply
key material. Keep the key outside the database and public document root. Back up
the key securely alongside encrypted database backups. Losing or rotating it
makes old ciphertext unreadable: restore the old key or save freshly issued
secrets. Ciphertext, plaintext fallback and keys are never rendered in password
fields. Empty submission preserves existing storage; explicit clear requires the
settings nonce and manage_options capability. Constants configuring provider
credentials take precedence over stored settings and must be cleared at their
configuration source.
Registering settings migrates legacy plaintext secrets when encryption is
available. Failure preserves recoverable data but getters refuse plaintext,
malformed or unauthenticated ciphertext. Provider calls fail closed and queue
work waits for working credentials. Remote and full-purge endpoint requests
require signing credentials. Cloudflare HTTP 200 with success: false is a
failure. Exception messages returned to history are generic and contain no
provider exception text. Rotate credentials previously stored in plaintext.
The generated bypass does not include sympress_consent: SymPress Consent
v0.1.1 keeps the anonymous HTML response independent of that cookie and performs
consent gating in the browser. Regenerate and reload previously generated Nginx
snippets to remove an old consent bypass. For integrations whose server response
depends on consent, explicitly add their cookie name via the existing
bypass-cookie setting or sympress_nginx_cache_bypass_cookies filter and
regenerate the server configuration. Origin validation uses configured home/site
origins only. History records REMOTE_ADDR; a trusted reverse proxy must configure
that address at the server layer, rather than trusting incoming forwarding
headers in PHP.
Uninstall retains data by default. The explicit delete-on-uninstall setting removes this plugin's settings, queues, history, locks and tag table, and clears its cron hooks. On multisite each site's own opt-in is checked. Filesystem cache files, uploads, other plugin options and remote caches are never removed by uninstall. Disable/delete preserves data unless this setting was enabled.
Run composer qa, then composer tests:integration with
NGINX_TEST_WORDPRESS_DIR pointing to unpacked WordPress core and
NGINX_TEST_DB_NAME=sympress_review_nginx_<unique> pointing to a fresh disposable
schema. Set NGINX_TEST_DB_HOST, NGINX_TEST_DB_USER and
NGINX_TEST_DB_PASSWORD for an isolated MariaDB service. The harness refuses
existing schemas, creates WordPress tables, runs concurrent workers and drops
only its newly created schema in finally. Missing requirements fail, never skip.
All external WordPress HTTP is blocked; provider behavior uses MockHttpClient.
The harness checks canonical tracking URLs, subsecond lock contention, durable
producers during contention, retry budgets and concurrent acknowledgements.
Also validate the regenerated snippet in real Nginx and PHP-FPM: 50 sequential
unique ?utm_source= requests to one anonymous path must cause one PHP entry
(MISS then HITs) and one canonical index URL. Search and preview queries must
bypass cache. Use a disposable cache path and database.
QA's WordPress MariaDB integration job runs this on a separate MariaDB service
and a hash-verified WordPress 7.1.2 archive. Require this check before merging.
Manual actions, content hooks, overflow and legacy requests default to Site.
On shared Multisite roots, native cache deletion reads each cache file's KEY
and matches the current site's original/mapped hosts and longest network path.
Unknown key formats, symlinks and other sites remain untouched. Budgeted scans
persist their cursor in the existing follow-up queue and resume under the purge
lock; providers run after the completed scan. Configure
SYMPRESS_NGINX_CACHE_SITE_ISOLATED_PATH=true only for genuinely isolated roots.
An HTTP full-purge endpoint on a shared root must explicitly support scope
(SYMPRESS_NGINX_CACHE_ENDPOINT_SUPPORTS_SITE_SCOPE=true) and validate the
signed site hosts, paths and boundaries; otherwise site purges fail closed.
Network scope must be explicitly requested by Network Admin, an authorized REST
client or wp nginx-cache purge --network --full / --scope=network.
Cloudflare site-wide purges use the site:<blog_id> cache tag; only network
scope permits a whole-zone purge. The Cloudflare account must support cache-tag
purging. Global object-cache and OPcache invalidation is restricted to network
scope in Multisite. Queues preserve scope through merging and recovery.
Editor actions require sympress_nginx_cache_purge_url and a nonce, validate
public objects and same-origin URLs, then use the existing manager or queue.
Empty/invalid targets never become full purges. A REST/CLI dry run with a queue
flag executes a preview immediately and writes no queue or follow-up task.
Migration is an explicit configuration write; its preview changes no options, and reports never include plaintext credentials. Network adoption writes only network values and never modifies existing site options. Site Health reads existing filesystem/queue information; its Redis check issues one bounded PING only when Redis is selected. It performs no HTTP loopback or purge.