featured-from-source: checked featured images from the source page

A WordPress plugin that finds a featured image on the page a post is based on, checks it, copies it into the media library with its credit and provenance, and never replaces an editor's choice.

featured-from-source is a WordPress plugin for sites that write about other pages: digests, link blogs, curated round-ups and imported drafts. For a post that stores the URL of the page it is based on and a credit line, it finds a picture on that page, checks it, copies it into the media library with the credit and provenance, and sets it as the featured image. The code is at https://github.com/IndianOpinion/featured-from-source, licensed MIT. Version v0.1.0 was released on 15 November 2026.

We wrote it from scratch from an idea, not from any third-party plugin. It has not run on a live site. The 47 utilities in this series were specified, built, reviewed and released between 11 and 19 November 2026 by language-model coding agents under the editor’s direction, in five roles: a spec writer, a spec reviewer, a builder that saw only the spec, an independent code reviewer and a releaser. The editor made the rulings on every open question.

The problem

A “take the first image” rule goes wrong in predictable ways. The PRD lists them:

  • The first image on a page is often a tracking pixel, a lazy-load spacer, a share button, a logo or an icon.
  • Lazy-loading pages keep a spacer in src and the real picture in a data attribute or srcset.
  • A page’s social image is sometimes a spacer, a site-wide default card, a logo slate or a library picture from another story.
  • A picture can be the right file and the wrong shape, such as a very wide, thin banner that passes a “wide enough” test and looks broken in every card.
  • Copying a picture without recording where it came from leaves the site unable to answer a rights query.

What it does

  • Tries candidates in a fixed order: og:image, then twitter:image, then images in the article body. The first candidate that passes every check wins. It does not download everything and pick the biggest.
  • Rejects spacers, trackers, logos, icons, avatars and a site’s default card before download where it can, and measures the real file after download.
  • Enforces a minimum size (600 by 315 by default) and an aspect window (1.2 to 2.1 by default).
  • Copies the file through media_handle_sideload() with the credit as caption, and writes provenance to the attachment.
  • Falls back to a configured placeholder, and replaces the placeholder later if a real picture turns up.
  • Gives every run one reason code, shown in an edit-screen box, so an editor can see why a picture was skipped.

How it works

Saving a post of an enabled type that has a source URL and a credit queues it. Nothing runs on save or on a front-end request. One recurring WP-Cron event works through the queue in batches. The main classes are Scheduler, Queue, Lock and Runner, with Http and AddressGuard for requests, CandidateFinder for the page, and ImageProbe and Sideloader for the file.

The page is parsed with a tolerant DOM parser. In the body it reads lazy-load attributes and srcset before src, and skips header, nav, footer, aside, share, related, promo, ad, sponsor, comments and author blocks. Name checks match whole tokens, so phone-pixel-10.jpg and logistics-hub.jpg pass. A social image that turns up on three or more pages of one domain is treated as that outlet’s default card.

After download, the Content-Type and the file’s magic bytes must agree, and SVG is never accepted. Dimensions are read from the file header without decoding the image, with a small WebP header reader.

An importer can hand a post over at insert time through meta:

wp_insert_post([
    'post_title'  => 'Harbour reopens after storm',
    'post_status' => 'draft',
    'meta_input'  => [
        '_ffs_source_url'    => 'https://news.example.com/2026/11/harbour-reopens',
        '_ffs_source_credit' => 'Example Daily',
    ],
]);

Guard rails

  • Nothing runs until the operator ticks a box taking responsibility for the licence of every image copied. Until then every run ends with rights_not_acknowledged.
  • The default host mode is an allow list, and the allow list starts empty. A deny list always wins. By default an image host must be the page’s own registrable domain or a mapped CDN. The plugin does not decide whether you may use a picture.
  • robots.txt is fetched once per host per day and honoured. A 5xx or network error means disallow for that host until the next check.
  • An editor’s own featured image is never replaced, not even with --force.
  • A post with no credit, or no source URL, fetches nothing.
  • Requests use ports 80 and 443 only, at most three redirects, hand-followed with a check per hop. Only the first 1 MiB of a page is read, and at most four candidates are downloaded per run.
  • The kill switch is a setting, the constant FEATURED_FROM_SOURCE_DISABLED, or the ffs_enabled filter. Queue entries are kept while it is off.
  • Provenance is written before the image is set as featured. If that fails, the copy is deleted.

What review changed

The independent code review changed these before the merge:

  • Server-side request forgery. WordPress’s safe-URL check refuses only some private IPv4 ranges, so a link to the cloud metadata address, shared address space, IPv6 unique-local addresses or IPv4-mapped IPv6 went through. A new AddressGuard resolves every hop’s host (A and AAAA), refuses any non-public address, and pins the cURL connection to the checked address so a rebinding DNS answer cannot move the request. On a non-cURL transport only the check applies.
  • The Imagick AVIF probe now names the avif: coder, so untrusted bytes cannot pick a decoder.
  • The robots.txt matcher collapses runs of * before building its pattern, to cut backtracking.

Limits and what is next

  • It does not judge whether a picture matches the story. That needs a person, and the edit-screen box has a “Find image now” button.
  • Files are stored as received. Camera metadata, including location, is not stripped.
  • It never fetches search engines, image search, stock libraries or third-party APIs, and it never fetches video watch pages on purpose.
  • The registrable-domain table is short and built in (136 suffixes). Extend it with ffs_public_suffixes.
  • AVIF needs PHP 8.2, or Imagick on PHP 8.1, and is off by default.
  • One open issue: the AVIF measurement path on PHP 8.1 through Imagick has no test with a real AVIF file.

Test status: this is v0.1.0. There are 104 PHPUnit tests, one per PRD case plus extras, run on a stub layer with a fake HTTP transport and a fake DNS resolver, so no test touches the network. Static analysis and code style checks passed. The GitHub CI workflow has not run: the commit adding it stayed local because the token lacked the workflow scope.

Install

It needs PHP 8.1 or later (tested on 8.1, 8.2 and 8.3), WordPress 6.4 or later and the PHP dom extension. intl, mbstring and, on PHP 8.1, imagick are used when present.

composer require indianopinion/featured-from-source

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

Or copy the folder to wp-content/plugins/featured-from-source/ and activate it. A must-use loader is in examples/.

All 47 utilities · featured-from-source on GitHub

Search Trending
Loading

Signing-in 3 seconds...

Signing-up 3 seconds...

All fields are required.