WordPress
This guide covers integrating smoxy with WordPress (and WooCommerce shops) using the official smoxy plugin. The plugin takes care of two things for you:
- Keeps the smoxy edge cache in sync with your content — no manual flushing after every change, including image uploads and re-generations.
- Sets up and watches the conditional rules your site needs so the admin bar, checkout flow, and admin area never get served from cache, and so static images use a tight URI-only cache key.
INFO
Prerequisites: Complete the Getting Started guide first. You'll also need an API token issued in the smoxy hub — the plugin uses it during one-time setup so you don't have to copy any other settings by hand.
INFO
Requirements: WordPress 6.0 or newer, PHP 8.0 or newer.
Installation
The plugin is published as a versioned zip on its GitHub releases page.
- Download the latest
smoxy-X.Y.Z.zip. - In WordPress, go to Plugins → Add New → Upload Plugin and upload the zip.
- Activate smoxy.
- Open the smoxy menu (cloud icon in the sidebar).
Connecting your site (one-time setup)
The settings page walks you through a short wizard the first time you open it.
Step 1 — Paste your API token
Generate an API token in the smoxy hub and paste it on the settings page. Once it's accepted, the rest of the wizard appears.
Step 2 — Pick a zone
- If you already have a smoxy zone for this site, choose Use existing zone and pick it from the list.
- If not, choose Create a new zone. You'll also pick (or create) an origin — the place smoxy should fetch your content from. The plugin pre-fills the origin's server IP, port and hostname from this WordPress install; adjust them if smoxy needs to reach the origin via a different address.
When you submit the wizard the plugin creates everything that's missing (origin, zone, hostname binding) and installs the four conditional rules described below. New zones are switched on with acceleration and security enabled, so they go live right away.
If your site's hostname is already attached to a different smoxy zone, the wizard doesn't fail — the connected view shows a warning with a Move hostname to this zone button, so you can decide whether to move it across.
The conditional rules the plugin installs
Smoxy caches HTML at the edge by host + path. A typical WordPress site mixes anonymous public pages with logged-in admin chrome, checkout flows and a wp-admin backend on the same URLs — so without targeted rules, the edge would happily serve the wrong HTML to the wrong visitor. Images, on the other hand, are the same bytes for everyone and should be cached as aggressively as possible.
To get both behaviours right, the plugin sets up four Conditional Rules on your zone — one that trims the cache key for images so every visitor reuses the same cached file, and three that turn smoxy off for requests that must always reach the live origin.
| Position | Rule | What it does | Why it has to exist |
|---|---|---|---|
| 1 | WordPress: cache images on URI only | Matches any URL ending in .png, .jpeg, .jpg, .gif, .webp, .avif, or .svg. Narrows the cache key to the URI (no host or cookie variance) and sets stop=true so the bypass rules below are skipped for image responses. | Images are byte-identical for every visitor, so varying the cache key on host or cookies just splinters the cache. Stopping further rule evaluation also keeps the logged-in / WooCommerce bypasses from accidentally turning caching off for an add-to-cart link inside an image URL or a logged-in user's image gallery. |
| 2 | WordPress: bypass cache for logged-in users | Any request that carries the WordPress logged-in cookie. | When you're logged in, WordPress sets a cookie and you should see your personalised admin bar and any drafts/previews. Without this rule, an anonymous visitor could land on a cached page that still shows your admin bar — or you'd see stale public HTML instead of your own changes. |
| 3 | WordPress: bypass cache for WooCommerce and account paths | Cart, checkout, my-account, product pages, add-to-cart links, and Woo's REST/webhook endpoints. | These pages must always reach the live shop: cached carts would mix customers' sessions, cached "add to cart" links would silently fail, and cached checkouts could break order completion. |
| 4 | WordPress: bypass cache for wp-admin | Anything under wp-admin. | The WordPress admin area is per-user and changes on every action — it must never be served from cache. |
The plugin uses the rule name to find these rules later, so please don't rename them in the hub. If you do, the plugin will think they're missing and offer to re-create them. The images rule is pinned to position 1; the three bypass rules can be reordered between themselves without triggering a drift alert.
Audit & one-click repair
Every time you open the settings page, the plugin checks all four rules on your zone and shows one of three states:
- OK — the rule is in place and matches the plugin's defaults (and, for the images rule, sits at position 1).
- Drifted — the rule exists but has been edited in the hub (expression, action,
stopflag, or — for the images rule — position). A Fix button restores the default. - Missing — the rule was deleted. A Create button puts it back.
If you want to keep a customised version of one of these rules, rename it in the hub. The plugin will treat it as a separate rule and create its own default alongside it.
How invalidation works
For everything except the bypass rules above, smoxy does cache HTML and static assets — and the plugin keeps that cache fresh as your content changes.
Behind the scenes the plugin uses tag-based invalidation: every cacheable response is labelled with one or more tags that describe what's on the page (e.g. which post, which category, the home page, etc.). When you change something in WordPress, the plugin works out which tags are affected and tells smoxy to invalidate just those — instead of flushing the whole cache. See Cache Invalidation for the broader picture.
The tags it uses are:
| Tag | Applied to |
|---|---|
p-<post_id> | A single post or page, and every post listed on an archive page |
t-<term_id> | The current term on category, tag, and custom-taxonomy pages |
a-<author_id> | Author archives |
home | The front page |
feed | RSS / Atom feeds |
What triggers an invalidation
The plugin reacts to the everyday content events in WordPress:
| Change | What gets refreshed |
|---|---|
| Post published, updated, trashed, or deleted | The post itself, every category/tag it's in, its author, home and feeds |
| Comment added, edited, approved, unapproved, or deleted | The post the comment belongs to |
| Category / tag / custom term created, edited, or deleted | The term archive and the home page |
| User profile updated or user deleted | That user's author archive |
| Media uploaded, regenerated, edited, or deleted | The full image URL and every generated thumbnail size for that attachment |
| Menu, widgets, theme switch, customizer save, plugin (de)activation | A full cache refresh |
| Site option changes (blogname, home, siteurl, permalinks, …) | A full cache refresh |
All the affected pages from a single edit are bundled together and refreshed in one go — so a bulk edit of ten posts is one refresh, not ten. Image purges from a single media event are dispatched in parallel, so refreshing a gallery image with a dozen thumbnail sizes finishes in about the same time as refreshing one.
Images and thumbnails
When you upload, replace, regenerate (e.g. via Regenerate Thumbnails), edit, or delete a media item, the plugin reads the attachment's size metadata and BANs every URL WordPress knows about: the full image, the pre--scaled original (WordPress 5.3+), and each entry under metadata['sizes']. Non-image attachments (PDFs, audio, etc.) are ignored — only mime types beginning with image/ are processed.
Because /wp-content/uploads/ is served as static files directly by the web server, the plugin can't attach a per-attachment cache tag at the origin the way it does for HTML pages — image invalidation goes through per-URL BANs instead. The combination with the WordPress: cache images on URI only rule keeps that cheap: every visitor reuses the same cached file, so the BAN actually clears something rather than a handful of cookie-keyed variants.
INFO
Cloudflare users: If you front your site with Cloudflare, invalidation requests may be blocked. See Cloudflare Setup for the recommended workaround.
WooCommerce
The plugin includes WooCommerce-aware invalidation out of the box — no extra setup. The listeners stay inert if WooCommerce isn't installed.
| Event | What gets refreshed |
|---|---|
| Product created or saved (including price-only edits) | The product page plus every category, tag, attribute, and brand archive it appears on |
| Variation saved (including variant price edits) | The parent product and its archives (the variation itself has no public URL) |
| Stock quantity changed (admin field, REST writes, order-driven decrement) | The product (or its parent, for variations) and the archives it shows up on |
Stock status changed (instock / outofstock / onbackorder) | The product (or its parent, for variations) and the archives it shows up on |
The shop page, product category, product tag, and brand archives are tagged for every product they list — so updating any listed product refreshes the archive automatically.
TIP
Variant price edits are a common gotcha with other WordPress cache plugins: changing a variant's price often skips the standard WordPress save hook, leaving the parent product page stale. The smoxy plugin listens for WooCommerce's own update events, so variant changes always invalidate the parent product.
Manual purge tools
Most invalidation happens automatically, but the plugin gives you manual controls when you want to force a refresh:
- Admin bar — Purge smoxy cache: one-click full purge, available on every admin and front-end page for users with
manage_options. - smoxy → Settings — Purge all cache: same as the admin-bar button.
- smoxy → Settings — Purge by URL: refresh a single cached resource. Works for any cacheable asset — pages, images, JS, CSS, fonts, and other static files. Accepts a full URL, a site-relative path (e.g.
/sample-page/), or leave blank for the home page. - smoxy → Settings — Purge by tag: refresh every page carrying one or more cache tags. Useful when you integrate with third-party plugins that emit their own tags (enter a single tag or a comma-separated list, e.g.
p-42, t-7, home).
Extending the invalidation flow
The plugin re-broadcasts the WordPress events it listens to as smoxy_* actions, so other plugins can join the same pipeline without touching core WP hooks:
| Action | Fired when |
|---|---|
smoxy_post_updated | A published post is saved or transitioned to publish |
smoxy_post_deleted | A published post is trashed or permanently deleted |
smoxy_comment_changed | A comment is created, edited, moderated, or deleted |
smoxy_term_changed | A taxonomy term is created, edited, or deleted |
smoxy_author_changed | A user is updated or deleted |
smoxy_flush_all | A site-wide change requires a full refresh |
Hook into these actions to add extra tags or trigger a flush from a third-party plugin without depending on the plugin's internals.
Troubleshooting
- The wizard says the token is rejected. The API token is missing, expired, or doesn't belong to your account. Generate a fresh one in the hub and paste it again.
- The wizard says the zone has no purge secret configured. Open the zone's Basic Configuration in the hub and save it once — that initialises the token the plugin uses to authenticate purges.
- The connected view warns about a hostname on a different zone. Your site's hostname is already attached to another zone in smoxy. Click Move hostname to this zone to re-attach it, or Dismiss if you'd rather keep it on the other zone (the new zone won't receive traffic until the hostname moves).
- One of the conditional rules shows Drifted. Someone edited the rule in the hub (or, for the images rule, moved it off position 1). Click Fix to restore the default. If you want a custom version, rename the hub rule so the plugin treats it as separate.
- Old image thumbnails are still being served after a regeneration. The plugin only knows about sizes recorded in WordPress's attachment metadata at the moment the change fires. If a previous regeneration left orphan files on disk under different dimensions, those URLs will linger in the cache until their TTL expires; clear them with Purge by URL if you need them gone immediately.
- A specific page won't refresh. Use Purge by URL with the exact public URL. If the page is still stale afterwards, check that smoxy is actually receiving the request — a Cloudflare layer in front of your site can swallow purge traffic.
- You don't want a particular event to flush everything. Most automatic triggers are tag-based; only menu, widget, theme, customizer, plugin, and site-option events do a full refresh. Avoid scripting bulk option updates against
blogname,home,siteurl, orpermalink_structureoutside maintenance windows. - Disconnecting the plugin. Use the Disconnect link on the settings page to clear the saved API token and zone binding. The four conditional rules stay on the zone — delete them in the hub if you no longer want them.