share-cards: social preview images rendered on first request

A WordPress plugin that draws a 1200 by 630 headline card for posts, categories and tags the first time a scraper asks, keeps it on disk, and uses featured images as they are when they already fit.

share-cards is a WordPress plugin that supplies the og:image and twitter:image for posts, categories, tags and custom pages. It is for news and publishing sites that want a proper preview image on every shared link. It is MIT licensed, and v0.1.0 was released on 14 November 2026.

The problem

Social platforms show a large preview image when a link is shared, taken from og:image and twitter:image. A news site without a card generator has three poor options. It can use the featured image as it is, but many featured images are too small or the wrong shape, and platforms crop them badly or fall back to a small thumbnail. It can use one placeholder for every archive and every image-less post, so every shared category and tag page looks the same. Or it can render a card for every post at publish time, which spends CPU and disk on images for posts nobody shares.

The plugin renders a card only when a scraper or browser first asks for it, stores it outside the media library, and serves the file after that.

What it does

  • Uses a featured image as it is when it is at least 1200 px wide and between 1.5 and 2.1 times as wide as high. Otherwise it draws a card.
  • Draws cards for category and tag archives, and for custom types a site registers.
  • Prints the eight image meta tags, or hands the image to Yoast SEO or Rank Math through their public filters.
  • Serves cards with year-long immutable cache headers, and can serve them straight from the web server with the nginx and Apache rules in examples/.
  • Provides WP-CLI commands warm, status, render, url, gc and flush.

How it works

The plugin decides what to advertise once per page view, without reading any image file. A card URL looks like /share-card/post-42-3f9a1c0b7e.jpg. The last part is the first 10 hex characters of a SHA-256 over everything drawn on the card: headline, kicker, footnote, backdrop file, settings, renderer and template version. Change any of those and the URL changes, which is why a CDN can cache cards for a year.

The endpoint runs on parse_request, before the main query and the theme. A current card is streamed with X-Share-Card: hit. A stale hash gets a 302 to the current URL. On a cold cache one process takes a file lock for the key and renders. Others wait up to lock_wait_ms, then get a 302 to the featured or default image. The card is written to a temporary name and renamed into place, so no reader sees half a file.

Layout (wrapping, the size ladder, ellipsis) is computed once in plain PHP. GD or Imagick only measures, draws and encodes. The backdrop is cover-cropped around a focal point, darkened, and covered with the background colour. Output is a progressive JPEG with no metadata. Fonts are not bundled: the plugin finds Noto Sans or DejaVu Sans, and scripts that need shaping are drawn only through Imagick with Pango.

Edits delete a post’s old card variants at once and fire share_cards_purged with their URLs. The plugin never calls a CDN itself. Themes can ask for the final image:

share_cards_image_for_request(): ?array   // url, width, height, type, alt, source (card, featured, default)

Files go in one cache directory, by default under the uploads folder. There are no attachment rows and no post meta.

Guard rails

  • At most max_concurrent renders run at once (default 2) and at most renders_per_minute start each minute (default 30). Past either limit the request gets the fallback image and the header says why.
  • Only the current hash is ever rendered. A guessed hash gets a 302 and costs nothing. Unknown, unpublished, private and malformed keys return the same empty 404. Drafts, private and password-protected posts never get a card URL.
  • Backdrops over 20 MiB or 25 million pixels are skipped, with the size checked from the header before any decode. SVG and CMYK sources are refused, and the source must sit inside the uploads directory.
  • A failed render leaves a marker that stops retries for failure_ttl seconds (default 600). The cache has a disk cap (default 512 MB) and a daily clean-up.
  • A script with no mapped font, or a shaping script without Pango, is left off the card. Boxes never appear.
  • The settings page, preview and save need manage_options and a nonce. There is no shell call and no eval.

What review changed

  • ImageMagick’s pango: coder runs text through its own property interpreter before Pango sees it. A headline containing %m was drawn as “PANGO” and %[fx:1+1] was evaluated. Every % and \ is now doubled before the read, with a test that fails without the change.
  • Multisite uninstall wrote the first site’s rewrite rules into every site. It now deletes the stored rules for each site so WordPress rebuilds them.
  • The hourly rewrite repair ran on admin_init, which also fires for admin-ajax.php, so a visitor could trigger it. It now needs manage_options.
  • PHPStan went from level 6 to 8, which also closed an edge case where an empty wrap left a gap in the fitted headline. New forked-process tests show eight simultaneous requests on one cold key give exactly one render, and 40 attempts against a budget of 10 start exactly 10.

Limits and what is next

  • One template, 1200 by 630, JPEG only. No square or portrait cards, no WebP, no per-post design.
  • GD never shapes text, so complex scripts need Imagick with Pango. The plugin does not read a font’s character map, so a mapped font with missing glyphs draws boxes for them.
  • Backdrops come from local files only. With media offloaded to object storage, supply a local path through share_cards_backdrop_path.
  • The file lock needs a local file system. Several web servers sharing one network file system need their own LockProvider.
  • With Rank Math, a page where Rank Math finds no image prints none unless you set a default image.
  • One open issue asks for the PRD’s section 1 measurement line to be reworded.

This is v0.1.0. The review reports 173 PHPUnit tests, PHPStan level 8 and phpcs clean on a local PHP 8.3, using stubs and mocks of WordPress. PHP 8.1 and 8.2 have been checked only statically, 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, 8.2 or 8.3 with ext-mbstring, WordPress 6.4 or later, and either ext-gd with JPEG and FreeType or ext-imagick that can write JPEG. You need at least one TrueType or OpenType font.

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

composer require indianopinion/share-cards

All 47 utilities · share-cards on GitHub

Search Trending
Loading

Signing-in 3 seconds...

Signing-up 3 seconds...

All fields are required.