Releases

wp-dodist-media 0.1.7 · Changelog · Download zip

DoD.ist Media

Contributors
dodist
Tags
images, media, cdn, webp, avif
Requires at least
7.0
Tested up to
7.1
Requires PHP
8.3
Stable tag
0.1.7
License
GPLv2 or later
License URI
https://www.gnu.org/licenses/gpl-2.0.html

Serve WordPress images through the img.dod.ist image transformer and warm its cache for media that already exists.

Description

DoD.ist Media rewrites WordPress image URLs to the img.dod.ist transformer and fills the transformer cache for a library that was uploaded before the switch. It never uploads, moves or deletes files, and it only writes its own options and queue table.

Two URL shapes are produced:

The image format is negotiated by the request Accept header (image/avif vs WebP). No format, timestamp or resize parameters are ever added to the URL, so page caches and CDNs keep working.

Delivery has three modes. Off leaves every URL local. Preview shows transform URLs to logged-in administrators only. On serves the front end and REST from the transformer while wp-admin screens stay local. Go-live requires 95 % of eligible images to have both required formats complete and the scan to be finished, unless an administrator explicitly overrides the gate.

Warm-up builds the lossless file plus one full-size WebP and one full-size AVIF per raster image, at the attachment's main-file width, with one quality per run. srcset widths are not warmed; the app generates them lazily on first view, which keeps the warm-up predictable.

Safety rules built in:

WP-CLI is the primary warm-up runner; the admin screen can also run it from the browser, and WP-Cron continues a started run in the background.

The companion transformer app, its tenant configuration and its cache are a separate project.

Installation

Two steps: get the plugin onto the site, then point it at a transformer tenant. Pick one way to get the files and stay with it - the plugin's own update checker and Composer would otherwise both manage wp-content/plugins/wp-dodist-media.

From wp.dod.ist

Every version is listed at https://wp.dod.ist, and the newest one is always at

https://wp.dod.ist/wp-dodist-media/download/

Add ?<version> to that URL - for example https://wp.dod.ist/wp-dodist-media/download/?0.1.7 - to pin a release, which is what you want if the same site must be reproducible later.

Installed this way the dashboard shows plugin updates. The plugin asks https://wp.dod.ist/wp-dodist-media/check every 12 hours and downloads a new version from the same host; the request carries the version it runs, nothing else.

With Composer

For a site that already installs plugins with Composer. The package is dodist/wp-dodist-media (type wordpress-plugin) in the repository at https://wp.dod.ist/packages/, and it is the same zip the dashboard downloads.

{
  "repositories": [
    { "type": "composer", "url": "https://wp.dod.ist/packages/" }
  ],
  "require": {
    "composer/installers": "^2.3",
    "dodist/wp-dodist-media": "^0.1"
  },
  "config": {
    "allow-plugins": { "composer/installers": true }
  },
  "extra": {
    "installer-paths": {
      "wp-content/plugins/{$name}/": ["type:wordpress-plugin"]
    }
  }
}

composer update dodist/wp-dodist-media

Configure

  1. Prepare the transformer app for this site: a tenant with a bucket root and the site hosts, pointing at this site's uploads. Note the tenant key and the uploads layout.
  2. Activate the plugin. Activation creates the queue table; nothing is rewritten and no warm-up starts until the plugin is configured.
  3. Open DoD.ist in wp-admin and fill in:
    • Base URL: the transform host, for example https://img.dod.ist. HTTPS only, except dod.ist.internal or localhost when DODIST_MEDIA_DEV is defined.
    • Tenant: the key in the app config. Never leave it empty to change the URL shape - use the checkbox below.
    • Append the tenant to the URL path: leave it on for img.dod.ist, and turn it off only when the Base URL is the site's own media subdomain, which the app must allow for the tenant. The plugin asks the app when you save and says so when the answer is no.
    • Source prefix: the path prepended to attachment paths. Bucket roots differ per site, so set this per site.
    • Quality: 1-100. Leave it at 75 until the app proves it keys its cache by quality by sending X-Dodist-Quality-Keyed: 1 (see the FAQ).
    • Formats: WebP and/or AVIF. Keep at least one checked.
  4. Use Test newest image on the same screen and fix the source prefix until the exact URL returns 200 / image/*. The test also reports whether the app keys its cache by quality.
  5. Click Build queue (or run wp dodist scan). This only fills the queue; it never starts a request by itself.
  6. Warm with WP-CLI, which is the fastest and safest option:
   wp dodist warm --max=100 --seconds=600

Or press Start in wp-admin for a slow, one-request-per-tick run. Watch the complete / WebP / AVIF counters until they reach the gate.

Warm-up respects the night window (default 01:00-06:00). The Warm-up section shows it with the server time and whether it is holding the run; change it under Delivery → Warm-up window, leave both fields empty to warm at any time, or run the CLI once with --force. logged-in administrator, and finally go live.

Optional constants in wp-config.php override the stored settings:

If the tenant is not set in the settings or by constant, the plugin falls back to the LAADA_DOD_IST_USER constant.

The transform host must be allowed by your Content Security Policy, for example img-src 'self' https://img.dod.ist data:.

WP-CLI

wp dodist status [--format=table|json]
wp dodist config [--base-url=<url>] [--tenant=<tenant>] [--tenant-in-url=<0|1>] [--source-prefix=<path>] [--quality=<1-100>] [--formats=webp,avif] [--delivery=off|preview|on]
wp dodist scan [--dry-run] [--force]
wp dodist warm [--formats=webp,avif] [--max=<requests>] [--seconds=<seconds>] [--rate=<requests/min>] [--force] [--yes]
wp dodist reset [--failures]
wp dodist test [--width=<px>] [--quality=<1-100>] [--format=webp|avif] [--referer]
wp dodist purge <id>... [--send]
wp dodist purge --status
wp dodist purge --orphans [--dry-run]
wp dodist limits [--format=table|json]
wp dodist subdomain <host> [--check|--verify]

wp dodist warm exits 0 when the queue is done, 1 on error, and 2 when it stopped because of a pause, the window, the daily budget or a lock.

Can I install it with Composer?

Yes, if the site already installs WordPress plugins that way: dodist/wp-dodist-media is published with the wordpress-plugin type, so composer/installers puts it in wp-content/plugins/wp-dodist-media/. The full composer.json block, the allow-plugins requirement and the update workflow are in Installation → With Composer. Mixing the two - a Composer install and the dashboard prompt - is what breaks, because both write to the same directory.

Why is q always 75 on sized URLs?

The transformer app has to include the quality in its cache key (in the derivative filename) before a variable q is safe: otherwise ?w=1200&q=60 and ?w=1200&q=90 share one cached file. Until the app answers a served image with X-Dodist-Quality-Keyed: 1, the plugin sends the app's default quality (75) on sized URLs and in warm-up, and says so on the DoD.ist screen. Varying q before that would mix cache entries.

A contract claiming quality_keyed is not enough. The claim is recorded separately and shown as quality_keyed_claimed; only the header proves it, and the header is only seen by the connection test and by a real warm request. Once proven, the configured quality is used and the proof survives settings saves and contract refreshes. It is lost only if the app stops sending the header — for example after an app rollback — which puts the plugin back on 75. The connection test reports the current app capability and is cached for an hour.

Can the plugin restore a missing original?

Not from its derivatives: the lossless WebP and the AVIF are re-encodings of the decoded pixels, so the original bytes, container and metadata are gone. The bucket is the archive, and wp dodist restore copies from it deliberately:

wp dodist restore            # where the originals are, and what is missing
wp dodist restore 123 --dry-run
wp dodist restore 123 --yes

Restoring one file at a time, it refuses to overwrite an existing file, and it verifies the downloaded bytes against the hash the app reported when the image was warmed (stored as _dodist_origin on the attachment). A mismatch aborts and keeps the download for inspection. Nothing is restored automatically, ever — not on a page load, not during a warm-up.

An image warmed before the app started reporting that hash has no record yet, so run the connection test on it once (wp dodist test <id>), which records it, or re-warm it. Without a record the plugin says "cannot verify" instead of writing unverified bytes.

Does the plugin touch my uploads or the database?

No uploads are moved or deleted, except by wp dodist restore, which only ever writes a file that is missing and verifies it first. The only table is {prefix}dodist_warmup, which holds one row per planned request; uninstalling removes it together with the plugin's options, log, transients, scheduled event and the per-user notice state.

My uploads live in a bucket, not on the server. Does that work?

Yes. Paths, widths and mime types come from the attachment records, and every request goes to the transformer, which fetches the original from the tenant's bucket. Scanning and warming a bucket-only library works unchanged.

What does not work on such a site is leaving Delivery on *Off*: nothing rewrites the URLs, so they point at local files that do not exist. Switch to Preview or On first, then remove the old offload plugin or theme code — never run both at once. The plugin warns in wp-admin when it sees a library with no local originals while delivery is off.

Why are srcset widths not warmed?

Warming every width would multiply the request count and the AVIF cost for little benefit. Warm-up builds the full-size file per format; the app renders narrower widths on first view and caches them.

I get 404 for the test URL.

The app cannot find the source object. Check the tenant's bucket root and the Source prefix for this site; the test shows the exact URL it requested.

I get 403 during a warm-up.

Something in front of the app is rejecting the request: a WAF rule, hotlink protection or a bot filter (the warm-up identifies itself with X-Dodist-Warm: 1). A 403 pauses the run instead of retrying; fix the rule, then press Resume.

I get 502.

The app or its upstream (object storage, image library) failed. The row is retried a bounded number of times, then marked failed; after repeated failures the run pauses. Check the app logs, then use Retry failures.

Another site is showing my images. How do I stop it?

The app refuses a request whose Referer names a host the tenant does not list, so an image embedded on another site's page - or served through a proxy in front of another name - answers 403 referer_refused instead of the image. Make sure every host your site serves pages from is in the tenant's hosts on the app (www as well as the bare domain if both serve), because a listing you are missing breaks your own pages, not someone else's.

The one hole left is a request with no Referer at all: a hotlinker can drop the header on purpose. Turning on the tenant's "refuse a request that carries no Referer" closes it, and also refuses direct links, visitors whose browser or extension strips the header, and the warm-up runner unless you also set a warm-up Referer (warmup_referer plus wp dodist warm --referer). It is off by default for that reason.

Can my media be served from my own subdomain?

Yes, and the app decides which hostname you may use. DoD.ist → Media subdomain walks the four steps: allow the hostname on the app, generate the file, point the subdomain at this host, then check it works.

wp dodist subdomain media.example.com            # the .htaccess
wp dodist subdomain media.example.com --check    # only: is the hostname allowed?
wp dodist subdomain media.example.com --verify   # only: does it actually serve?

Generating asks the app, and only when the app says the hostname is allowed for the tenant do you get the file. A hostname the app does not allow produces a refusal and nothing else: the file is setup help, not a permission. The DNS record, the certificate and the subdomain's hosting stay yours to set up.

Checking is the step that tells you it worked. The plugin fetches one image through the app, the same image through the subdomain - with this site's own Referer, so the tenant's hosts list is exercised too - and compares the bytes. You get a line per check: the app answered, the subdomain answered, it is an image, the app produced it (X-Dodist-* headers), and the bytes match. A subdomain that answers an HTML 404, or a proxy that re-encodes, fails the line that names it.

Serving the subdomain straight from the app instead of through that file needs no .htaccess at all - point the subdomain at the app and list it for the tenant; the same check proves it.

To get the short URL, three settings, and the tenant stays filled in:

base_url      https://media.example.com
tenant        example                (always required: it is the identity)
tenant_in_url off                    (the checkbox "Append the tenant to the URL path")

That is the only thing the checkbox changes. Emptying the Tenant field instead does not switch URL shapes, it turns the plugin off: every URL is unbuilt, delivery goes inert and the warm-up refuses, because the tenant is what names the contract, the cache key, the purge route and the warm-up request. Use the checkbox.

The plugin checks the host when you save: if the app does not allow it for the tenant, the screen says the URLs would answer 404 rather than letting a site fill up with broken images.

Which images are skipped?

Cropped sizes (a different aspect ratio), unsupported mime types, and files whose basename appears more than once in the library. Skipped files keep their local URLs; wp dodist scan --dry-run reports how many duplicate basenames it found.

Does switching delivery off again revert everything?

It stops new URLs from being rewritten, but HTML, browser and CDN caches that already contain transform URLs keep serving them until they are purged. Purge page caches after any delivery change.

How do I call the transformer from a theme or a headless API?

Use dodist_image_url( $id ) for the base URL, or dodist_image_url( $id, $width ) for a sized URL; pass $quality only when you deliberately want a value other than the default. It returns null when the plugin is not configured or the attachment is not eligible. If your theme builds its own srcset, build each candidate with dodist_image_url( $id, $width ) instead of appending ?w= to the base URL, otherwise those URLs lose the explicit q. Note that this helper deliberately ignores the Delivery setting: API authors who call it opt out of the delivery gate and are responsible for only returning transform URLs once the corresponding images are warm.

How do I stop everything?

Pause on the DoD.ist screen stops further requests and clears the scheduled event. wp dodist reset deletes the queued rows (wp dodist reset --failures only requeues failed ones), and deactivating the plugin also clears the event and releases the lock.

Why does the plugin warn about year/month folders?

The plugin compares the path layout your library actually uses with the one your tenant serves, because they can disagree:

When the library is nested but the tenant serves flat paths, every media URL returns 404 and warm-up is blocked with an error telling you so — that is the one case that has to be fixed before anything else. When the library is flat but the tenant is declared nested, media URLs still work, so you get a warning instead. A mixed library (some nested, some flat) usually means a migration or a second offload plugin is still running, and also warns, without blocking.

wp dodist status always shows all four values:

layout_wp_yearmonth  on | off
layout_detected      nested | flat | mixed | unknown
layout_tenant        nested | flat | unknown
layout_state         ok | info | warning | error

Use wp dodist status --refresh after changing the tenant in the app; that re-reads the contract (/<tenant>/contract) and re-samples the library. The plugin never rewrites a path or strips a prefix — flattening belongs to your own offload or mu-plugin.

Why was my upload rejected?

Uploads are checked before they are stored, against the ceilings the transformer app reports for your tenant:

SVG/PDF/DOC/DOCX/XLSX are passthrough: no pixels, no ceilings. The file is not written when it is rejected, and the reason appears in the media screen's own upload error. Check the numbers with wp dodist limits, and see which existing attachments would fail today (they are reported, never deleted).

Note what tightening a ceiling does to files you already have: the plugin never deletes them, but the transformer applies the same ceilings when it is asked for a derivative, so an over-limit original starts answering 413 instead of being processed. Loosen the ceiling or replace the file if it needs to keep serving.

The ceilings come from the app and are cached, so they keep working when it is unreachable; DODIST_MEDIA_MAX_MEGAPIXELS, DODIST_MEDIA_MAX_BYTES, DODIST_MEDIA_MAX_BYTES_PER_PIXEL and DODIST_MEDIA_MAX_LIBRARY_IMAGES pin them from wp-config.php when you need to.

Why is warm-up blocked with "library is larger than the tenant allows"?

Installing the plugin on a site that already has a big media library is a different proposition from warming a fresh one: the first run spends real CPU on somebody else's existing archive. So the app carries a threshold (max_library_images) and a per-tenant approval (late_install_approved). Above the threshold and unapproved, delivery stays off and warm-up refuses to start.

It is fail-closed on purpose: an unreachable app, or an app too old to report the setting, keeps the gate closed rather than assuming approval. To clear it, approve the tenant in the app and run wp dodist status --refresh. Purging, and URLs that already work, are unaffected.

How do I delete an image's cached files on img.dod.ist?

Deleting or replacing an image in WordPress queues a purge automatically once DODIST_MEDIA_PURGE_TOKEN is defined. Until then nothing is queued and everything else works as before; the DoD.ist screen says the token is missing.

A purge removes the cached files for one image — every width and both formats — and never the original in your uploads folder or bucket. It is queued, sent by the runner one image per request, retried with backoff, and it never blocks or fails the delete in WordPress. You can also purge by hand:

wp dodist purge 123
wp dodist purge 123 --send
wp dodist purge --status

There is deliberately no tenant-wide purge in the plugin: no --all, no --older-than. Orphan cache entries (an object whose attachment no longer exists) are handled one file at a time:

wp dodist purge --orphans --dry-run
wp dodist purge --orphans

Purging the origin does not help a CDN or a browser that already holds the old bytes with max-age=31536000; the cache for a replaced image only becomes correct for those clients once the edge is purged too.

Screenshots

  1. The DoD.ist screen: coverage counters, connection test and delivery gate.
  2. The warm-up section with progress, ETA and the WP-CLI hint.
  3. The failures table with the exact URL, HTTP code and error.

Changelog

See CHANGELOG.md in the plugin folder for the full list. 0.1.0 was published as a packaging test on 2026-11-18 and superseded by 0.1.1 the same day, before anything installed it.

0.1.7

0.1.6

0.1.5

0.1.4

0.1.3

0.1.2

0.1.1

0.1.0

Upgrade Notice

0.1.7

The subdomain check shows one URL when the Base URL is that subdomain.

0.1.6

wp dodist config --tenant-in-url works instead of being rejected as an unknown flag.

0.1.5

A checkbox decides the URL shape, so a short subdomain URL no longer needs the tenant to be emptied out of the settings.

0.1.4

A four-step media subdomain flow that ends by proving the subdomain serves the media.

0.1.3

Media subdomain setup help, asked of the app, plus a named hotlink refusal.

0.1.2

Documentation only: how to install from wp.dod.ist or with Composer.

0.1.1

First release, including origin restore and the editable warm-up window.

0.1.0

Packaging test, superseded the same day. Do not install.