# featured-from-prompt: suggested featured images held for review

[featured-from-prompt](https://github.com/IndianOpinion/featured-from-prompt) is a WordPress plugin that suggests a featured image for a post. It builds a prompt from the post, asks an image API through a small adapter, checks the file that comes back, and holds it for an editor who accepts it with one click. It is for sites with many posts that have no picture of their own. Licence MIT. Version v0.1.0, released 18 November 2026.

It was written from scratch from an idea, as one of the utilities described on the [engineering blog](https://indianopinion.org/blog/). It has not run on a live site.

## The problem

Opinion pieces, explainers, short news items and round-ups often have no picture. Without a featured image they look broken in archive grids, share previews and feed readers. The usual answers each go wrong.

- A single site-wide placeholder makes every such post look the same, and every share preview becomes the same branded slab.

- A placeholder is a real file of a good size and shape, so code that asks whether a featured image is usable by size alone says yes, and the post is never offered anything better.

- Image generation called straight from a save hook spends money on every save, runs again on every retry, and sets pictures nobody has looked at.

- A generator can return another size than asked, a square instead of a wide picture, or an error page with a 200 status. Code that trusts the request instead of the file ends up with a broken hero.

- Two concurrent runs each read "one request left" and both spend it.

- A fallback path elsewhere calls the generator directly and skips the cap, the kill switch and the one-attempt rule.

## What it does

- Builds an editable prompt from the title, a short summary, the category and the tags.

- Calls an image API through one adapter interface. It ships a configurable generic-http JSON adapter, one-shot or submit-then-poll, and an offline fixture adapter for demos and tests.

- Checks the real bytes: type by magic number, decodability, pixel size, aspect ratio, byte size and pixel count, with optional centre crop and format conversion.

- Stores each result as a pending suggestion in a protected directory outside the uploads tree.

- Marks every generated image as generated, with its prompt and provider, at the moment it is stored, and labels it where readers see it.

- Applies a placeholder policy when generation fails, and treats placeholders as "no image" everywhere.

## How it works

A trigger, whether a button, a REST call, a save, a publish, a WP-CLI command or a backfill, calls Queue::request. That checks eligibility, auto mode and a one-attempt marker, builds the prompt and writes a queue row. Nothing is spent at that point. Worker::run, from WP-Cron, a real cron or gen-queue, then runs the guards: kill switch, provider, pause, eligibility, queue age and a post lock. It reserves cap units, asks spend-meter if present, calls the provider, downloads the result over safe HTTP, runs ImageChecker and stores the pending suggestion. Worker is the only caller of ImageProvider::generate().

The cap reservation is a single atomic UPDATE ... WHERE count < cap, per post and then per day. It is refunded only when no HTTP request was sent. On Accept, the file moves into uploads and sizes are built, but only when its name is one the plugin made and its bytes still sniff as the image type on record.

A generic-http adapter is configured with a body template like this:

{"prompt": "{prompt}", "size": "{width}x{height}", "n": 1}

The default prompt template is generic. It asks for an editorial illustration from the title, summary, category and style, with no text, letters, logos or watermarks, and no real, identifiable person. Auto mode has an off, log and on setting. In log mode the triggers run every guard, record what would have happened and call nothing.

## Guard rails

- Only a person makes a generated image featured: Accept in the panel, the REST route or WP-CLI, or a deliberate pick in the media modal. A write of a pending suggestion to the thumbnail meta outside Accept is refused.

- Generation runs in the background, never on a front-end request, and the plugin is off until a provider is saved. FFP_DISABLED stops every provider call at once.

- The per-day cap defaults to 20 and the per-post cap to 3. FFP_DAY_CAP can lower the cap but never raise it. There is one automatic attempt per post.

- Account errors pause the provider, not the post. A 401 pauses until an administrator resumes it. A quota error pauses for a set time.

- Downloads use HTTPS, a byte limit and at most three redirects, followed hop by hop with a public-address check on every hop, so private, loopback and link-local addresses are refused.

- The pending directory fails closed. The plugin refuses to store anything when the directory sits inside uploads, when its path contains .., or when deny files cannot be written. Pending files have random names and no public URL.

- Secrets are read from constants first, kept in non-autoloaded options and never logged. AVIF, GIF and SVG results are refused.

## What review changed

An independent review of the build PR fixed these before the merge.

- SSRF. WordPress safe mode lets link-local addresses, such as cloud metadata, through and applies the same check to redirects. Downloads now follow redirects hop by hop with a public-address check on each, and the poll job URL and endpoint get the same check.

- Submit and polls had no shared deadline, so a slow submit plus a full poll could outlive the post lock. They now share one deadline, and response size is capped.

- A .. in an attached-file value could make the preview route stream, or attachment deletion remove, a file elsewhere. Only plugin-made names directly in the private directory now count.

- A gen-queue row that the worker parked, for example with the switch off, was orphaned. It now returns to the plugin's own queue.

The review also tightened Accept so a file's name and sniffed type are re-checked before the move, and corrected the spend-meter, gen-queue and prompt-library integrations to the released contracts.

## Limits and what is next

- No provenance is written into the image file, such as IPTC, XMP or content credentials. The record lives in attachment meta. It is on the roadmap.

- generic-http speaks JSON only. Multipart uploads are not supported.

- No per-user caps. Use spend-meter for budgets by user or month.

- Only the featured image, not images in post content or galleries.

- No network-wide cap on multisite. Every site has its own caps and queue.

- The plugin sends no cache headers. Listen to ffp_accepted to purge a page cache.

No issues are open on the repo. Test status: this is v0.1.0. There are 121 PHPUnit tests with 909 assertions, and they pass against a throwaway MySQL 8, including a forked race for the last cap slot, with PHPStan and phpcs clean. Without the database, four tests skip. Provider calls are tested against the fixture adapter and stubs. The CI workflow has not run on GitHub, and there is no production mileage.

## Install

It needs PHP 8.1 or later and WordPress 6.4 or later. It has no runtime dependencies. GD or Imagick is optional, and needed only for crop and conversion.

composer require indianopinion/featured-from-prompt

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

On nginx, also block the pending directory:

location ^~ /wp-content/ffp-private/ { deny all; }

[All 47 utilities](https://indianopinion.org/blog/open-source/) · [featured-from-prompt on GitHub](https://github.com/IndianOpinion/featured-from-prompt)

Canonical: https://indianopinion.org/blog/open-source/featured-from-prompt/

AI disclosure: Every summary and comment here is written by AI and published automatically, without a person reviewing each article. We do no original reporting. How this works: https://indianopinion.org/ai-use-policy/
