alt-text-fill is a WordPress plugin that finds every image in the media library with no alt text, asks a vision model you choose to describe each one from the image and the post around it, and puts every suggestion on a review list. It is for site operators with a large backlog of undescribed images. Licence MIT. Version v0.1.0, released 19 November 2026.
It was written from scratch from an idea, as one of the utilities described on the engineering blog. It has not run on a live site, and the PRD quotes no measured result.
Alt text is what a screen reader says in place of a picture, and what a search engine or an assistant reads when it cannot see one. Most media libraries hold many images with none. Fixing them by hand is slow, so it does not happen. The shortcuts go wrong in predictable ways.
Scanner reads image attachments by ID range, 500 at a time, with a stored cursor that wraps. It reads post and meta rows only and never opens a file. Context\UsageFinder finds the posts that use an image by parent, featured image, image block ID, wp-image-<id> class and file URL. Context\ContextBuilder picks one post and builds the context: caption, description, post title, two paragraphs either side of the image and the nearest heading, with HTML, shortcodes and URLs removed. An image used by more posts than a threshold, or listed as a placeholder, gets no post context at all.
Image\ImagePreparer chooses the smallest intermediate size of at least 1,024 pixels, scales it in memory with GD or Imagick, reads the real type from the bytes and refuses anything over the byte limit. Runner makes the call through a VisionAdapter. The one bundled adapter speaks an OpenAI-compatible chat completions endpoint with image parts, as the README describes. The prompt carries the context in a delimited block marked as data.
Validator rejects empty or short text, refusals, links, file names, and copies of the post title or file name. Writer is the only code that changes alt text, and Undo restores absent as absent and a string byte for byte.
wp alt-text-fill run --dry-run
wp alt-text-fill run --user=<editor>
wp alt-text-fill undo --since=<datetime>
State lives in three tables for suggestions, entries and runs, plus a few options. Retention is 30 days for pending suggestions, 90 for decided ones and runs, and 365 for entries.
ALT_TEXT_FILL_DISABLED, wins over the setting and is checked before every call, including inside a run already going.An independent review of the build PR fixed these before the merge.
add_option() upserts, so two runs could both win. It now uses INSERT IGNORE plus a compare-and-swap update, tested with two MySQL connections.The review also fixed undo of an undo, which left the original entry marked undone, and approval of a “suggest decorative” row, which skipped the re-read and could mark an image decorative over an editor’s text.
No issues are open on the repo. Test status: 182 PHPUnit tests with 895 assertions pass on PHP 8.3, including seven integration tests against a throwaway MySQL 8.0, with PHPStan level 8 and phpcs clean. The unit suite runs on a WordPress stub layer and model calls are tested against a fake adapter. This is v0.1.0. The CI workflow has not run on GitHub, and there is no production mileage.
It needs WordPress 6.4 or later and PHP 8.1 or later. GD or Imagick is optional. Without Composer, copy the directory to wp-content/plugins/alt-text-fill/ and activate it. With Composer:
composer require indianopinion/alt-text-fill
The package is not on Packagist yet, so add a Composer vcs repository entry for https://github.com/IndianOpinion/alt-text-fill first.