Download the PHP package qoliber/trident-php without Composer

Trident PHP Library

Official PHP client library for Trident HTTP Cache Proxy.

Requirements

• PHP 8.1 or higher
• PSR-7/PSR-17/PSR-18 compatible HTTP client (e.g., Guzzle)

Installation

Quick Start

Cache Purging

Purge by Tag

Purge by URL

Purge All

Convenience Methods

Cache Tags

Tag Collection

Tag Resolver

Durable invalidation for platform modules (1.3.0)

Platform-neutral building blocks shared by the platform integrations (WooCommerce today; Magento, Shopware, Sylius and PrestaShop next), so the delivery contract is written — and tested — once.

A platform provides two adapters and wires them:

TridentClient purge methods now also say whether Trident acknowledged the purge: PurgeResponse::isAcknowledged(), ->state, ->failure. The old isSuccess() is unchanged (true for any purge body) and must not be used to decide that a purge happened.

Admin screens for platform modules (1.4.0)

Everything a platform's admin needs to show and drive Trident — the screen set of the Magento module (dashboard, purge, cached pages, tags, coverage, warmer, launch, reflect, denoisers, bans, backends, discovery, live events) — with no per-platform API code.

TridentClient::forInstance($instance, $transport) builds a client over any Transport (the WordPress HTTP API, Magento's Curl); new operator calls: status(), purgeHost(), purgeVary(), coverage(), cacheVariants(), explain(), warmerStatus|Run|Cancel|Queue(), launch(), reflectStatus|Enable|Disable|Queue(), denoiserReport(), denoiserPathZones(), denoiserQueryScopes(), denoiserQuery|PathPin(), …Unpin(), denoiserReset(), esiFragments(), and EventStream::parseChunk() for a bounded read of an SSE stream.

Corrected against the engine in the same release (each was checked on a live 1.8.0 Trident): the launch calls no longer append a launch id the engine does not have; memoryStats() reads GET /admin/memory; snapshot() and the discovery calls use the engine's paths; purgePreview() sends url_pattern/tag/tags/tag_pattern and reads would_free_bytes and the sample; cacheEntries()/cacheTags() gained the engine's sort/tag/prefix filters; CacheStatsResponse now carries hits, misses, passes and the hit ratio (it always reported 0 %); LaunchResponse reads the engine's success; list and entry responses read size, content_type, vary, and discovery reads backend_name/addresses. purgeUrl() splits an absolute URL into path, host and scheme.

1.4.1 — fixes

• Anything that is not the admin API is an error. Every engine admin endpoint answers JSON. Admin\Api::call() used to turn a redirect (an http:// API URL in front of an https-only listener, a wrong path) or a proxy's HTML page into success: true, so a screen could report "Launch started" or an empty "reachable" dashboard when Trident never saw the request. A 3xx, or a 2xx whose body is not JSON, now throws ApiError; 204 No Content is still a success. Durable purge delivery (Delivery\PurgeClient, judged by Acknowledgement) is unchanged.
• purgeTagPattern() sends pattern_type, the field the engine reads. It sent type, which the engine ignored, so a regex tag pattern was purged as a wildcard.

1.5.0 — a complete admin client

Everything a platform's admin screens need is now on the typed client; the lower-level Admin\Api is for what the library does not cover yet. Nothing is removed or renamed: 1.4.x code runs unchanged (the 1.4.1 test suite passes as-is).

• Every typed response keeps the engine's full answer. raw() returns the decoded JSON it was built from, payload() the same answer as a dot-path Payload ($stats->payload()->int('hits')). Payload::raw() is the same for the untyped reads. toArray() keeps its 1.4 shape — use raw() for the complete answer.
• Fields the engine sends are no longer dropped or read under the wrong name (checked against a live 1.8.0 engine; the old names stay as fallbacks): health uptime (uptime_seconds), compressed entries (current_compressed_entries), compressionsTotal, tagIndexedKeys, urlIndexedKeys, protection enabled (protection_enabled) with the total* counters and per-backend queue figures (backends stays keyed by backend name — the 1.4.1 shape — and each row carries its name), memory footprintPercentiles, launch active, connection queued (waitingRequests), totalCreated, totalReused, latency sampleCount.
• purge(PurgeRequest) sends a purge with every option the engine has: soft/hard on every kind (tag, tags and tag pattern included), exclude_tags and the match mode for tags, pattern_type for tag patterns. The mode is sent only when you choose one (->soft() or ->hard()); a request without either leaves it to the operator's admin.default_purge_mode, whose engine default is soft. getMode() still answers hard for such a request (its 1.4.1 answer) — hasExplicitMode() says whether a mode is sent. purgeUrl() keeps sending its explicit mode, as in 1.4.1. PurgeRequest gained hard(), excluding(), hasExplicitMode(), engineEndpoint() and toEngineBody().
• clearCache(): ClearResponse — a full clear typed on the engine's clear schema (cleared, entriesRemoved, bytesFreed, isAcknowledged()). A clear has no soft/hard mode. purgeAll() is unchanged.
• Delivery reports what was purged. PurgeAttempt carries purged and state (a deferred 202 purge has purged nothing yet: purged is null); DrainReport::$purged and each instance's purged add them up. PurgeClient::clear() clears an instance, judged by the clear schema.
• explainRequest($url, $method, $headers, $cookies, $detail) — the full request context /admin/explain accepts; cookies go in the Cookie header, the URL's host becomes Host unless given. A cookie name or value that would inject another cookie or header (;, ,, control characters; a name with = or whitespace) is refused, not rewritten. The scheme is not sent: the engine evaluates explain without TLS context, so for an https page only cacheable and reason are meaningful.
• Exception\InvalidRequest (a TridentException) — a request the client refuses to send: an invalid denoiser pin, an injecting cookie. Code that catches TridentException for admin failures, as 1.4.x code does, still catches it; nothing reaches Trident.
• Denoisers: pins are validated before anything is sent (class noise|signal, status dead|alive, a non-empty parameter); denoiserPathZoneDelete(), denoiserQueryScopeDelete() and wafExport() (the trident-waf-v1 export) are new.

TridentClientInterface is frozen for 1.x. The new methods (purge(), clearCache(), explainRequest(), wafExport(), the denoiser deletes) are on the TridentClient class only: adding methods to the interface would break every class that implements it. Type against TridentClient to use them.

Which layer to use (platform authors)

1.8.1 — which Trident this is for

Packages are versioned in lockstep with the engine: MAJOR.MINOR is Trident's (library 1.8.x works with Trident 1.8), PATCH is the library's own. Qoliber\Trident\Compatibility::TRIDENT names the release line ('1.8'), and Compatibility::warning($engineVersion) returns a message for an admin screen when a connected engine runs another MAJOR.MINOR (null when it matches or is unreadable). The shared Admin\AdminService dashboard shows it as its "compatibility" row, so every platform built on it gets the warning.

1.8.0 (unreleased) — one delivery, settings and tag policy for every platform

Five public classes that were platform code before: Delivery\OutboxDelivery (record a purge per instance, flush this request's rows, drain, drainAll(), status, and a direct send when the outbox cannot be written), Config\Settings + Config\SettingsResolver (the deployment configuration wins over the admin setting; an environment token goes only to environment URLs; the host allowlist; purge mode, tag prefix, debug headers) and Tags\TagPolicy (the same tag names in the header and in the purge: prefix, 200 tags / 4 KiB, per-kind overflow tags). Used by trident-symfony and the PrestaShop module. A blank tag is now ignored instead of becoming the bare prefix. Integrations using them require ^1.8.

1.7.0 (unreleased) — the security pieces every platform needs

Moved out of the Shopware plugin, so the Sylius bundle (and every later platform) uses one implementation instead of a copy:

• Http\NetworkGuard — addresses a Trident API URL may never reach: link-local ranges (169.254.0.0/16, fe80::/10), the unspecified addresses (0.0.0.0/8, ::), every IPv6 form that carries an IPv4 address (v4-mapped, v4-compatible, NAT64 64:ff9b::/96, 6to4 2002::/16), numeric host spellings (2852039166, octal, hex), and the cloud metadata services (fd00:ec2::254, 100.100.100.200, metadata.google.internal). Checked on the RESOLVED address. Private ranges stay allowed: Trident normally is internal.
• Http\TransportFactory — the PSR-18 client for Trident's admin API: libcurl, no redirects (the token must not follow one), and no proxy: CURLOPT_NOPROXY=*, so neither Guzzle nor libcurl uses an environment proxy (http_proxy, HTTPS_PROXY, ALL_PROXY) for admin traffic — a proxy would resolve the target itself (defeating the pin and the guard) and, on http://, see the bearer token. The NetworkGuard's checked address is pinned for the connection (CURLOPT_RESOLVE), so DNS rebinding cannot swap it. A deployment that must use a proxy passes it explicitly ($proxy, http(s)://host[:port]); pinning is then off (the guard still checks the name). A custom Guzzle handler is refused unless it declares that it honours the curl options. Needs guzzlehttp/guzzle ^7.5 (suggested).
• Security\TokenVault — an admin-stored API token encrypted at rest and bound to its URL: XChaCha20-Poly1305 with the normalised URL (scheme, host, port, path) as associated data; key = HKDF-SHA256 of the application secret with a per-platform $info label. Pointing the URL elsewhere makes the token unusable until it is re-entered. Needs ext-sodium.
• Delivery\ApiHostAllowlist — the optional allowlist of API hosts (host or host:port, exact matches; case, a trailing dot and IPv6 brackets normalised), with a reason per dropped instance.

And, shared by the Shopware plugin and the Symfony bundle:

• Admin\AdminService — the admin screens' logic (dashboard, purge, cached pages, tags, coverage, warmer, launch, reflect, denoisers, bans, backends, discovery, events) over Admin\AdminClient. A platform provides an Admin\AdminContext factory (its settings, instances and PurgeOutbox — its durable delivery) and a ShopAdapter (its hosts, URLs and catalogue lookups; also EntityInvalidator when entity purges should go through the platform's own invalidation, as Shopware's do). Pattern purges and bans are scoped to the shop's own hosts: the engine matches a pattern against every host of a shared Trident.
• Second delivery (Delivery\Purger::scheduleRedelivery()) — a purge can be delivered again $redeliverAfter seconds later (Shopware and Symfony use 10 s; 0, the default, keeps the old behaviour), for a page rendered from data the purge's transaction had not yet made visible. A store that records it implements Delivery\ScheduledStore: such rows are not owed (not in pending) until due, and an identical scheduled tag set is recorded once per instance.
• Delivery\Drainer::drainAll() — "deliver now": every row, whatever its due time (second deliveries, backstop rows, rows in grace or backoff). For operators after an incident and for test suites; the platforms expose it as trident:purge:drain --now.

1.6.0

• Admin\WafView — the part of an instance's WAF export (wafExport()) and learned query scopes (denoiserQueryScopes()) that belongs to one shop: deadZones($export, $hosts) and noise($scopes, $hosts) keep the shop's own host(s), plus the * rows marked inert (no * fallback in the engine: old wildcard pins that apply to nothing and can be removed with unpin). The export is global on a shared Trident; a shop's screen must not list other shops' paths. Shared by the WooCommerce plugin and the Shopware plugin (it used to live in the WooCommerce plugin only).
• Denoiser pins need a real host. denoiserQueryPin() and denoiserPathPin() throw InvalidRequest for host * or an empty host (including the old * default). The engine keys learned scopes and zones as {host}|{path_prefix} with the request's host and has no wildcard fallback, so such a pin was accepted and never applied. Unpin and zone/scope delete still take *, to clean such pins up. Behaviour change: a caller that pinned on * (or relied on the default) now gets an exception instead of a silently inert pin.
• purgeUrls() is fixed. In 1.5 it was never acknowledged and always reported 0 purged: the engine's bulk answer carries total_purged, not purged. And absolute URLs purged nothing, because the bulk endpoint takes paths plus one host/scheme. Now:
  • URLs are grouped by origin (paths form a group of their own), one request per group;
  • each group is judged on its own (a 200 with the schema or a 202 recorded), and the result is acknowledged only when every group is;
  • every request failing throws, as 1.5 did;
  • some failing gives isSuccess() false and isAcknowledged() false, with the failed groups in failure and raw()['failed_groups'];
  • an answer that is not an acknowledgement counts as a success, as in 1.5, but not as acknowledged;
  • purgedCount is the sum of the groups' total_purged.
• SiteUrl::parse() drops the scheme's default port (https://shop.example:443/a → host shop.example) and converts an IDN host to punycode, so purgeUrl()/purgeUrls() hit the browser's key. The IDN conversion needs ext-intl; without it a non-ASCII host is kept as written.
• Denoiser pin hosts are sent trimmed and lowercased, as the engine keys them.
• API URLs are scheme://host[:port][/base-path] only (Instances::parse, Instances::isHttpUrl). A query, fragment or credentials are refused: the client appends /admin/…, and a query string would carry that path to another service.
• ApiError clips answer bodies (message and engineMessage) to 300 characters without control characters. What answered is not necessarily Trident, and its body must never land on a screen whole.
• Per-kind overflow tags (TagSet, optional): pass $overflowFamilies (regex → overflow tag) and a dropped tag of a family adds THAT family's overflow tag instead of the general one; TagSet::overflowTagsFor() gives a purge only the overflow tags of the kinds it carries. An over-tagged listing is then refreshed by a product save, not by every unrelated save. Without the argument nothing changes.
• coverage() takes the method the engine checks (CacheCoverageRequest.method, default GET): coverage($paths, $host, $scheme, 'HEAD').

PSR-15 Middleware

Cache Tag Middleware

Cache Control Middleware

Environment Variables

Testing

Versioning

Versions follow Trident: qoliber/trident-php 1.8.x works with Trident 1.8. MAJOR.MINOR moves with the engine (every Trident X.Y.0 release is also a release of this package, changed or not); the PATCH number is this package's own. The admin screens warn when a connected Trident runs another release line.

License

MIT License - see LICENSE file for details.