WordPress
Diese Anleitung beschreibt die Integration von smoxy mit WordPress (und WooCommerce-Shops) über das offizielle Plugin smoxy. Das Plugin übernimmt zwei Aufgaben:
- Hält den smoxy Edge-Cache automatisch synchron mit den Inhalten — kein manuelles Leeren nach Änderungen, auch nicht nach Bild-Uploads oder Thumbnail-Regenerierungen.
- Richtet die Conditional Rules ein und überwacht sie, die nötig sind, damit die Admin-Bar, der Checkout-Flow und der Admin-Bereich nie aus dem Cache ausgeliefert werden — und damit statische Bilder einen knappen, URI-only Cache-Key nutzen.
INFO
Voraussetzungen: Zuerst die Erste Schritte-Anleitung abschließen. Zusätzlich wird ein API-Token aus dem smoxy Hub benötigt — das Plugin verwendet ihn bei der einmaligen Einrichtung, damit keine weiteren Einstellungen manuell übertragen werden müssen.
INFO
Anforderungen: WordPress 6.0 oder neuer, PHP 8.0 oder neuer.
Installation
Das Plugin wird als versioniertes ZIP auf der GitHub-Releases-Seite bereitgestellt.
- Die aktuelle
smoxy-X.Y.Z.zipherunterladen. - In WordPress unter Plugins → Installieren → Plugin hochladen die ZIP-Datei hochladen.
- smoxy aktivieren.
- Das smoxy-Menü öffnen (Wolken-Icon in der Seitenleiste).
Site verbinden (einmalige Einrichtung)
Die Einstellungsseite führt beim ersten Aufruf durch einen kurzen Assistenten.
Schritt 1 — API-Token einfügen
Im smoxy Hub einen API-Token erzeugen und auf der Einstellungsseite einfügen. Sobald er akzeptiert ist, erscheinen die nächsten Schritte.
Schritt 2 — Zone wählen
- Wenn bereits eine smoxy-Zone für die Site existiert, Vorhandene Zone verwenden auswählen und aus der Liste wählen.
- Andernfalls Neue Zone anlegen wählen. Dazu wird auch ein Origin ausgewählt (oder neu angelegt) — die Adresse, von der smoxy die Inhalte abholen soll. Server-IP, Port und Hostname werden aus der aktuellen WordPress-Installation vorausgefüllt; anpassen, falls smoxy den Origin über eine andere Adresse erreichen soll.
Beim Absenden legt der Assistent alles Fehlende an (Origin, Zone, Hostname-Verknüpfung) und installiert die vier unten beschriebenen Conditional Rules. Neue Zonen werden direkt mit Acceleration und Security aktiviert, sodass sie sofort produktiv sind.
Falls der Hostname bereits an einer anderen smoxy-Zone hängt, bricht der Assistent nicht ab — die verbundene Ansicht zeigt eine Warnung mit der Schaltfläche Hostname auf diese Zone verschieben, sodass selbst entschieden werden kann.
Die Conditional Rules, die das Plugin anlegt
Smoxy cached HTML am Edge nach host + Pfad. Eine typische WordPress-Seite mischt jedoch anonyme öffentliche Seiten mit eingeloggter Admin-Chrome, Checkout-Flows und einem wp-admin-Backend auf denselben URLs — ohne gezielte Regeln würde der Edge also fröhlich das falsche HTML an den falschen Besucher ausliefern. Bilder hingegen sind für jeden Besucher dieselben Bytes und sollten möglichst aggressiv gecached werden.
Damit beide Verhalten stimmen, legt das Plugin vier Conditional Rules an der Zone an — eine, die den Cache-Key für Bilder verschlankt, sodass jeder Besucher dieselbe gecachte Datei wiederverwendet, und drei, die smoxy ausschalten für Anfragen, die immer den Live-Origin erreichen müssen.
| Position | Regel | Was sie tut | Warum sie existieren muss |
|---|---|---|---|
| 1 | WordPress: cache images on URI only | Trifft alle URLs, die auf .png, .jpeg, .jpg, .gif, .webp, .avif oder .svg enden. Reduziert den Cache-Key auf die URI (kein Host- oder Cookie-Vary) und setzt stop=true, sodass die Bypass-Regeln unten für Bild-Antworten übersprungen werden. | Bilder sind für jeden Besucher byte-identisch; ein Cache-Key, der nach Host oder Cookies variiert, zersplittert den Cache unnötig. Das frühe stop verhindert außerdem, dass die Logged-in-/WooCommerce-Bypasses Caching für einen add-to-cart-Parameter in einer Bild-URL oder eine Bildergalerie im eingeloggten Zustand versehentlich ausschalten. |
| 2 | WordPress: bypass cache for logged-in users | Jede Anfrage mit dem WordPress-Login-Cookie. | Im eingeloggten Zustand setzt WordPress ein Cookie, und die personalisierte Admin-Bar sowie Entwürfe/Previews sollen sichtbar sein. Ohne diese Regel könnte ein anonymer Besucher auf einer gecachten Seite die Admin-Bar des eingeloggten Nutzers sehen — oder der eingeloggte Nutzer sieht statt seiner Änderungen veraltetes öffentliches HTML. |
| 3 | WordPress: bypass cache for WooCommerce and account paths | Warenkorb, Checkout, my-account, Produktseiten, add-to-cart-Links und Woos REST-/Webhook-Endpunkte. | Diese Seiten müssen immer den Live-Shop erreichen: gecachte Warenkörbe würden Kundensessions vermischen, gecachte "In den Warenkorb"-Links würden stillschweigend fehlschlagen, und gecachte Checkouts könnten die Bestellabwicklung brechen. |
| 4 | WordPress: bypass cache for wp-admin | Alles unterhalb von wp-admin. | Der WordPress-Admin-Bereich ist benutzerspezifisch und ändert sich bei jeder Aktion — er darf nie aus dem Cache ausgeliefert werden. |
Das Plugin erkennt diese Regeln am Namen, also bitte nicht im Hub umbenennen. Andernfalls behandelt das Plugin sie als fehlend und bietet ein erneutes Anlegen an. Die Bilder-Regel ist auf Position 1 gepinnt; die drei Bypass-Regeln können untereinander umsortiert werden, ohne einen Drift-Alarm auszulösen.
Audit & Ein-Klick-Reparatur
Bei jedem Aufruf der Einstellungsseite prüft das Plugin alle vier Regeln an der Zone und zeigt einen von drei Zuständen:
- OK — die Regel existiert und entspricht den Plugin-Defaults (und liegt bei der Bilder-Regel auf Position 1).
- Drifted — die Regel existiert, wurde aber im Hub bearbeitet (Expression, Action,
stop-Flag oder — bei der Bilder-Regel — Position). Mit Fix wird der Default wiederhergestellt. - Missing — die Regel wurde gelöscht. Mit Create wird sie neu angelegt.
Wenn eine angepasste Version einer dieser Regeln gewünscht ist, die Regel im Hub umbenennen. Das Plugin behandelt sie dann als eigenständige Regel und legt seinen Default daneben an.
Wie die Invalidierung funktioniert
Für alles außer den oben genannten Bypass-Regeln cached smoxy HTML und statische Assets — und das Plugin hält diesen Cache aktuell, sobald sich Inhalte ändern.
Im Hintergrund nutzt das Plugin Tag-basierte Invalidierung: jede cachebare Antwort wird mit ein oder mehreren Tags markiert, die beschreiben, was auf der Seite steht (welcher Beitrag, welche Kategorie, die Startseite usw.). Wenn etwas in WordPress geändert wird, ermittelt das Plugin die betroffenen Tags und sagt smoxy, nur diese zu invalidieren — anstatt den ganzen Cache zu leeren. Siehe Cache-Invalidierung für den größeren Kontext.
Verwendete Tags:
| Tag | Wird gesetzt für |
|---|---|
p-<post_id> | Einen einzelnen Beitrag/Seite, und jeden Beitrag in einer Archivseite |
t-<term_id> | Den aktuellen Term auf Kategorie-, Tag- und Custom-Taxonomy-Seiten |
a-<author_id> | Autorenarchive |
home | Die Startseite |
feed | RSS- / Atom-Feeds |
Was eine Invalidierung auslöst
Das Plugin reagiert auf die alltäglichen Inhaltsereignisse in WordPress:
| Änderung | Was aktualisiert wird |
|---|---|
| Beitrag veröffentlicht, aktualisiert, in den Papierkorb oder gelöscht | Der Beitrag selbst, alle Kategorien/Tags, der Autor, Startseite und Feeds |
| Kommentar erstellt, bearbeitet, freigeschaltet, abgelehnt oder gelöscht | Der zugehörige Beitrag |
| Kategorie / Tag / Custom-Term erstellt, bearbeitet oder gelöscht | Das Term-Archiv und die Startseite |
| Benutzerprofil aktualisiert oder Benutzer gelöscht | Das Autorenarchiv des Nutzers |
| Medium hochgeladen, regeneriert, bearbeitet oder gelöscht | Die vollständige Bild-URL und jede generierte Thumbnail-Größe des Mediums |
| Menü, Widgets, Theme-Wechsel, Customizer-Save, Plugin-(De)Aktivierung | Vollständige Cache-Aktualisierung |
Änderungen an Site-Optionen (blogname, home, siteurl, Permalinks …) | Vollständige Cache-Aktualisierung |
Alle betroffenen Seiten einer Bearbeitung werden gesammelt und in einem Rutsch aktualisiert — eine Massenbearbeitung von zehn Beiträgen ist also eine Aktualisierung, nicht zehn. Bild-Purges aus einem einzelnen Medien-Event werden parallel ausgeführt, sodass die Aktualisierung eines Galerie-Bildes mit einem Dutzend Thumbnail-Größen ungefähr so schnell ist wie die eines einzelnen Bildes.
Bilder und Thumbnails
Beim Hochladen, Ersetzen, Regenerieren (z. B. über Regenerate Thumbnails), Bearbeiten oder Löschen eines Mediums liest das Plugin die Größenmetadaten der Attachment-Datei und BANt jede URL, die WordPress kennt: das Originalbild, das pre--scaled Original (WordPress 5.3+) und jeden Eintrag unter metadata['sizes']. Nicht-Bild-Attachments (PDFs, Audio usw.) werden ignoriert — verarbeitet werden nur MIME-Typen, die mit image/ beginnen.
Da /wp-content/uploads/ direkt vom Webserver als statische Dateien ausgeliefert wird, kann das Plugin nicht — wie bei HTML-Seiten — einen Cache-Tag pro Attachment am Origin setzen; die Bild-Invalidierung läuft daher über Per-URL-BANs. In Kombination mit der WordPress: cache images on URI only-Regel bleibt das günstig: jeder Besucher verwendet dieselbe gecachte Datei, sodass der BAN tatsächlich etwas leert und nicht nur eine Handvoll Cookie-gekeyter Varianten trifft.
INFO
Cloudflare-Nutzer: Wenn die Seite hinter Cloudflare läuft, kann Cloudflare die Invalidierungs-Anfragen blockieren. Siehe Cloudflare-Einrichtung für die empfohlene Lösung.
WooCommerce
Das Plugin enthält WooCommerce-Awareness ab Werk — keine zusätzliche Einrichtung nötig. Die Listener sind inaktiv, solange WooCommerce nicht installiert ist.
| Ereignis | Was aktualisiert wird |
|---|---|
| Produkt angelegt oder gespeichert (auch reine Preisänderungen) | Die Produktseite plus jede Kategorie, jeder Tag, jedes Attribut und Markenarchiv, in dem es vorkommt |
| Variation gespeichert (auch reine Preisänderungen am Variant) | Das übergeordnete Produkt und seine Archive (die Variation selbst hat keine öffentliche URL) |
| Lagerbestand geändert (Admin-Feld, REST-Writes, bestellungsgetriebene Reduktion) | Das Produkt (bzw. das übergeordnete Produkt bei Variationen) und seine Archive |
Lagerstatus geändert (instock / outofstock / onbackorder) | Das Produkt (bzw. das übergeordnete Produkt bei Variationen) und seine Archive |
Die Shop-Seite sowie Produktkategorie-, Produkttag- und Markenarchive sind für jedes gelistete Produkt getaggt — eine Änderung an einem gelisteten Produkt aktualisiert das Archiv also automatisch.
TIP
Variant-Preisänderungen sind bei anderen WordPress-Cache-Plugins eine bekannte Falle: das Ändern eines Variant-Preises überspringt häufig den Standard-WordPress-Save-Hook, sodass die Produktseite veraltet bleibt. Das smoxy-Plugin reagiert auf WooCommerces eigene Update-Ereignisse — Variant-Änderungen invalidieren also immer das übergeordnete Produkt.
Manuelle Purge-Werkzeuge
Die meiste Invalidierung läuft automatisch. Für die Fälle, in denen eine erzwungene Aktualisierung gewünscht ist, stellt das Plugin manuelle Steuerelemente bereit:
- Admin-Bar — smoxy-Cache leeren: Ein-Klick-Komplett-Purge, sichtbar auf jeder Admin- und Frontend-Seite für Benutzer mit
manage_options. - smoxy → Einstellungen — Gesamten Cache leeren: Äquivalent zum Admin-Bar-Button.
- smoxy → Einstellungen — Per URL leeren: Eine einzelne gecachte Ressource aktualisieren. Funktioniert für alle cachebaren Assets — Seiten, Bilder, JS, CSS, Schriften und andere statische Dateien. Akzeptiert eine vollständige URL, einen site-relativen Pfad (z. B.
/sample-page/), oder leer für die Startseite. - smoxy → Einstellungen — Per Tag leeren: Alle Seiten aktualisieren, die ein oder mehrere Cache-Tags tragen. Nützlich bei Integration mit Drittanbieter-Plugins, die eigene Tags ausgeben (einzelner Tag oder komma-separierte Liste, z. B.
p-42, t-7, home).
Invalidierungs-Flow erweitern
Das Plugin sendet die beobachteten WordPress-Ereignisse als smoxy_*-Actions weiter, damit andere Plugins sich in dieselbe Pipeline einklinken können, ohne Core-WP-Hooks zu nutzen:
| Action | Wird ausgelöst, wenn … |
|---|---|
smoxy_post_updated | Ein veröffentlichter Beitrag gespeichert oder publish gesetzt wird |
smoxy_post_deleted | Ein veröffentlichter Beitrag in den Papierkorb oder gelöscht wird |
smoxy_comment_changed | Ein Kommentar erstellt, bearbeitet, moderiert oder gelöscht wird |
smoxy_term_changed | Ein Taxonomy-Term erstellt, bearbeitet oder gelöscht wird |
smoxy_author_changed | Ein Benutzer aktualisiert oder gelöscht wird |
smoxy_flush_all | Eine site-weite Änderung eine Komplett-Aktualisierung erfordert |
Über diese Actions lassen sich aus Drittanbieter-Plugins zusätzliche Tags hinzufügen oder ein Flush auslösen, ohne von den Plugin-Internas abhängig zu sein.
Fehlerbehebung
- Der Assistent meldet, dass der Token abgelehnt wurde. Der API-Token fehlt, ist abgelaufen oder gehört nicht zum Account. Im Hub einen neuen Token erzeugen und erneut einfügen.
- Der Assistent meldet, dass die Zone kein Purge-Secret hat. Die Grundkonfiguration der Zone im Hub einmal speichern — dadurch wird der Purge-Token initialisiert, mit dem das Plugin sich gegenüber smoxy authentifiziert.
- Die verbundene Ansicht warnt vor einem Hostname an einer anderen Zone. Der Hostname der Site hängt bereits an einer anderen Zone in smoxy. Auf Hostname auf diese Zone verschieben klicken, um ihn umzuhängen — oder Verwerfen, falls er an der anderen Zone bleiben soll (die neue Zone empfängt dann keinen Traffic, bis der Hostname umzieht).
- Eine der Conditional Rules zeigt "Drifted". Jemand hat die Regel im Hub bearbeitet (oder die Bilder-Regel von Position 1 verschoben). Mit Fix werden die Defaults wiederhergestellt. Für eine angepasste Version die Regel im Hub umbenennen — dann behandelt das Plugin sie als eigenständige Regel.
- Nach einer Thumbnail-Regenerierung werden noch alte Bildgrößen ausgeliefert. Das Plugin kennt nur die Größen, die im Moment der Änderung in WordPress' Attachment-Metadaten stehen. Hat eine frühere Regenerierung verwaiste Dateien mit anderen Abmessungen auf der Platte hinterlassen, bleiben deren URLs bis zum TTL-Ablauf im Cache; bei Bedarf mit Per URL leeren sofort entfernen.
- Eine bestimmte Seite aktualisiert sich nicht. Per URL leeren mit der exakten öffentlichen URL nutzen. Falls die Seite anschließend weiterhin veraltet ist, prüfen, ob smoxy die Anfrage überhaupt erhält — eine Cloudflare-Schicht vor der Seite kann Purge-Traffic verschlucken.
- Ein Ereignis soll keine Komplett-Aktualisierung auslösen. Die meisten automatischen Trigger sind tag-basiert; nur Menü-/Widget-/Theme-/Customizer-/Plugin-/Site-Option-Änderungen führen eine vollständige Aktualisierung durch. Massen-Updates von
blogname,home,siteurloderpermalink_structureaußerhalb von Wartungsfenstern vermeiden. - Plugin trennen. Über den Disconnect-Link auf der Einstellungsseite werden der gespeicherte API-Token und die Zone-Bindung entfernt. Die vier Conditional Rules an der Zone bleiben bestehen — bei Bedarf manuell im Hub löschen.