srcset-truth: honest image sizes and WebP for WordPress

A WordPress plugin that replaces core's default sizes attribute with the real width of each image slot, serves WebP siblings through picture, and audits the before-and-after image weight of a page.

srcset-truth is a WordPress plugin for site operators whose pages send phones larger images than the layout needs. It corrects the sizes attribute, serves WebP copies next to the originals and reports the saving. It is MIT licensed, and v0.1.0 was released on 14 November 2026.

The problem

WordPress gives every attachment image a srcset with several widths. That part is fine. It then adds a sizes attribute that says, in effect, that the image is as wide as the viewport, up to its own width. For an image painted into a fixed slot, such as a card in a grid, that is false, and the browser trusts it.

The README’s worked case: a theme asks for the 1024 by 576 derivative and paints it into a 372 by 266 card. On a 412 px phone at a device pixel ratio of 2, the browser computes a need of 824 device pixels and downloads the 1024 px file. The 300 px and 768 px files already exist on disk, and one of them was the right answer. The srcset was correct and the sizes hint was wrong.

Two related faults ride along. Most uploads are JPEG, PNG or GIF, and WebP is much smaller. But converting a whole library is costly, and rewriting URLs by Accept header breaks on CDNs that do not vary on it. Themes also often set loading="lazy" on every image, including the largest one above the fold, which delays Largest Contentful Paint.

What it does

  • Replaces core’s default sizes value with a value from a width map the site supplies per template and per slot. Values a theme wrote itself are left alone unless you opt in.
  • Creates WebP siblings next to the originals at upload time and in a time-boxed background backfill, and serves them through <picture>.
  • Optionally fixes lazy loading and priority for the likely LCP image, and preloads it.
  • Adds an admin bar probe that logs each image’s rendered width, device pixel ratio and downloaded width.
  • Reports before-and-after image weight for one page and viewport with wp srcset-truth audit.

How it works

On a front-end HTML request every image passes one classifier, Corrector::correct(), whichever way it arrives: content filter, post thumbnail, attachment attributes or the page buffer. CoreDefault recognises core’s value. TemplateResolver and SlotResolver pick a template key and a slot. WidthMap looks the pair up, Compiler builds and validates the value, and the last length is capped at the image’s own width so a map written for big images never inflates small ones. If anything is unclear, core’s value stays.

You describe slots in the theme, or name them where you render:

add_filter('srcset_truth_width_map', function (array $map): array {
    $map['default']['card'] = [[767, '92vw'], [1024, '46vw'], [null, '380px']];
    return $map;
});

use function IndianOpinion\SrcsetTruth\with_slot;

echo with_slot('card', fn () => get_the_post_thumbnail(null, 'large'));

For WebP, SiblingCreator writes photo-768x432.jpg.webp next to photo-768x432.jpg for the main file and the medium, medium_large and large sizes. It uses Imagick or GD. File type comes from the signature, not the name, and writes are atomic. A sibling that is not smaller than its original is deleted. Backfill walks the library from the newest ID down on cron, with a stored cursor and a lock. Page requests never encode. They check whether a sibling exists, once per file per request.

Serving wraps the image in <picture> with a <source type="image/webp"> and leaves the <img> as it was, so a browser without WebP falls back. The source lists the same candidates in the same order, so the browser’s width choice does not change. The HTML is the same for every visitor, with no Vary: Accept, and each format has its own URL, so a CDN caches them separately. The plugin prints picture.srcset-truth{display:contents} so flex and grid layouts treat the image as a direct child.

The audit applies the specification’s pick rule: the smallest candidate whose density reaches the device pixel ratio. It reports the candidate under core’s sizes and the one under the emitted sizes, with bytes and flags such as unmapped and no-candidate-near-slot.

Guard rails

  • With no width map, nothing changes. A guess that is too small makes images blurry, so core’s value is kept.
  • Kill switch: the constant SRCSET_TRUTH_DISABLE set to true in wp-config.php hooks nothing.
  • Encoding has limits: 40 megapixels, 30 MB and 300 frames by default, filterable. Failures get reason codes such as too-large and colour-profile and are recorded in a capped skip ledger so they are not retried until the original changes.
  • The backfill budget is 45 seconds and never above 80 per cent of max_execution_time.
  • The audit fetches only this site. It refuses other hosts and redirects to them. It sends a short-lived HMAC-SHA256 header keyed from the site’s salts, compared in constant time, so a visitor cannot request annotated output. Annotated responses are private, no-store and define DONOTCACHEPAGE.
  • The probe needs manage_options and a nonce.

What review changed

  • The build rewrote src and srcset to .webp in place, so browsers without WebP got broken images. Wrapping in <picture> is now the default, and the in-place rewrite is opt-in.
  • Images printed with wp_get_attachment_image() would have lost WebP under the new default, so that output is wrapped through its own filter.
  • Block themes and shortcode output could nest one <picture> inside another. Each wrapped pair is now remembered for the request.
  • The skip ledger could overwrite records an upload added during a long backfill. Every write now re-reads the stored option first. The audit key is also derived under its own label so it can never equal a core nonce.

Limits and what is next

  • It does not create or regenerate sub-sizes. If the right width is missing, the audit says so.
  • There is no AVIF in 0.1.0.
  • In filter mode, images a theme prints with its own markup are not reached. Buffer mode reaches them.
  • Uploads offloaded to an object store fail the file check, so originals are served unless you answer srcset_truth_has_sibling yourself. Anything that syncs uploads to a media host must include the .webp files.
  • Child selectors such as .card > img stop matching once the image sits inside <picture>.
  • One open issue: the audit accepts any port on the site’s host and should match the port too.

This is v0.1.0. The review reports 150 PHPUnit tests, PHPStan level 8 and phpcs all clean on a local PHP 8.3, with the tests running against stubs and mocks of WordPress plus the real WordPress 6.4 tag processor. CI has not yet run on GitHub, and the plugin has not run on a live site. It was specified, built and reviewed in separate roles by language-model coding agents under the editor’s direction.

Install

It needs PHP 8.1 or later and WordPress 6.4 or later. WebP creation needs Imagick with WebP or GD with WebP. Without either, sizes correction still works.

The package is not on Packagist yet, so first add a Composer vcs repository entry for https://github.com/IndianOpinion/srcset-truth.

composer require indianopinion/srcset-truth

All 47 utilities · srcset-truth on GitHub

Search Trending
Loading

Signing-in 3 seconds...

Signing-up 3 seconds...

All fields are required.