Direct answer
Filter WordPress's resolved post-thumbnail ID only when it is empty, the request is public, the content is published, and the configured fallback is a valid local image attachment. Return the real thumbnail unchanged whenever one exists. Never write _thumbnail_id to the post.
Default Featured Image follows this read-only model. Free handles posts and pages. Pro adds bounded post-type and post-category fallbacks plus one-post opt-out.
Fallback and assignment are different products
The difference determines rollback risk:
| Method | Database effect | What happens after deactivation |
|---|---|---|
| Read-only fallback | No post thumbnail is written | Empty native state returns immediately |
| Bulk assignment | Writes _thumbnail_id to many posts |
Assigned images remain until another mutation removes them |
| Template placeholder | Changes theme or builder output | Depends on that template implementation |
| CSS background | Changes presentation only | May not behave as a real post thumbnail |
A site owner who wants empty archive cards to look consistent usually needs the first method. Bulk assignment is a migration tool with a much larger backup and recovery obligation.
Use WordPress's native thumbnail boundary
WordPress documents get_post_thumbnail_id() as the function that returns a post's featured-image attachment ID. Its documented post_thumbnail_id filter provides a narrow read boundary after WordPress resolves that value.
A fail-passive fallback should apply only after these checks:
- The incoming thumbnail ID is empty.
- The request is public, not wp-admin, REST, feed, XML-RPC, or AJAX.
- The post object is exact, published, and an allowed public type.
- The selected attachment ID is local and still an image.
- Pro has not opted the post out.
If any check fails, return the incoming value unchanged.
A theme still decides whether there is an image location
The filter supplies an attachment ID. It does not edit a template or insert markup. A theme that calls the_post_thumbnail(), get_the_post_thumbnail(), or the equivalent native block can display the fallback. A template that never renders a featured image has no location to fill.
This boundary avoids brittle CSS selectors and page-builder adapters. It also explains a common support result: the fallback can work in an archive card but not on a singular template when only the archive asks WordPress for a post thumbnail.
Diagnose a missing fallback
| Symptom | Check first | Safe expected result |
|---|---|---|
| No image anywhere | Fallback enabled and attachment still valid | One local ID or native empty state |
| Archive works, post does not | Whether each template renders a native thumbnail | Works only where requested |
| Real image is replaced | Incoming thumbnail ID handling | Real ID always wins |
| Editor shows a fallback assignment | Admin/editor exclusion | No fallback in editor state |
| Image remains after uninstall | Check whether another tool bulk-assigned it | StoreFixKit never writes _thumbnail_id |
| Custom post type errors | Public type and object checks | Quiet native output on uncertainty |
Public reports illustrate the risk of mixing fallback and mutation. One topic describes attachment-page image problems after uninstall, another asks a plugin to stop attaching a featured image in the block editor, and another records a critical error involving a custom post type image. These reports support stricter boundaries; they do not prove every default-image plugin has those defects.
Validate the image before returning it
An integer in an option is not proof that an attachment is usable. Runtime should confirm the ID still represents a WordPress image. If it was deleted, trashed, replaced by non-image content, or malformed, return the original empty result.
Remote URLs are a different feature. They introduce availability, privacy, hotlinking, caching, content-type, size, and security questions. A small fallback plugin should use one local Media Library attachment and leave remote images out of scope.
Keep admin and machine-readable output native
A public visual fallback should not silently become stored editorial truth. Exclude:
- wp-admin lists and editors;
- REST responses and external clients;
- feeds and XML-RPC;
- drafts, private posts, trash, revisions, autosaves, and attachments;
- email, sitemap, Open Graph, schema, and SEO fields;
- media captions, alt text, dimensions, and generated sizes.
This makes the feature easier to explain: it affects only public theme thumbnail reads.
Give Pro a deterministic local order
Pro can add useful reuse without writing posts:
- Real featured image.
- One-post opt-out returns no fallback.
- Lowest matching configured post-category ID among at most 25 rules.
- Configured public post-type fallback.
- Free global post/page fallback.
- Native empty result.
Every candidate attachment is still local and validated. Pro does not scan content or assign images in bulk.
Test the invariants
- An authorized administrator can choose one local image and enable Free.
- A published post with no thumbnail receives one valid fallback ID.
- A real thumbnail ID is returned byte-for-byte unchanged.
- Draft, private, trash, revision, attachment, admin, REST, feed, AJAX, and XML-RPC contexts receive no fallback.
- A deleted or invalid configured attachment fails quiet.
- The theme displays the image on desktop and mobile without plugin CSS.
- The settings preview waits for the image to download and decode; an
<img>element with a broken source is not a passing screenshot. - Pro opt-out and rule precedence are deterministic and capped.
- Free continues with Pro removed and with the license API unavailable.
- Update, downgrade, rollback, deactivation, and uninstall do not change posts, attachments, or real thumbnail metadata.
Resource boundary
The plugin works inside a thumbnail lookup WordPress or the theme already requested. It does not run a post query, media query, background repair, custom table, cron event, queue, telemetry call, JavaScript, stylesheet, or StoreFixKit storefront request.
The release benchmark records no owned-state write and no public HTTP call. Resource numbers are environment-specific; the invariant is more important: a real thumbnail returns before fallback settings, unsupported contexts return early, and the plugin never scans content.
Common mistakes
Bulk assigning the fallback to every post
This turns a presentation fallback into a content migration and makes deactivation insufficient for rollback.
Overriding a real featured image
The incoming positive thumbnail ID must win before any fallback decision.
Promising support for every theme
A filter cannot fill a template that never asks WordPress for a featured image. State the native-function requirement clearly.
Using a remote image URL
This adds external availability and privacy dependencies to a local presentation feature.
Showing the fallback in editor or REST state
That can make authors and external systems believe an image was assigned when it was not.
Market boundary
WordPress.org has established default-featured-image and bulk-featured-image categories, and commercial products offer broader assignment and automation. That proves the problem category exists; it does not prove StoreFixKit demand, revenue, or superiority.
The narrower hypothesis is that nontechnical site owners value a fallback they can disable without repairing posts. Validate it with legitimate installs, successful image setup, visible archive and singular-template checks, trial starts, paid conversions, support volume, refunds, and renewals.
FAQ
How do I set a default featured image in WordPress?
Choose one local Media Library image and return its attachment ID only when WordPress resolves no real thumbnail on an allowed public post or page.
Does the fallback change each post?
No. A read-only design never writes the post's _thumbnail_id field.
Will an existing featured image be replaced?
No. Any positive real thumbnail ID returns before fallback logic.
Why does the image appear in an archive but not on the post page?
The archive template probably requests a native post thumbnail while the singular template does not. The plugin does not edit either template.
What happens after deactivation?
Native empty-thumbnail output returns immediately. No post or media repair is required.
Focused plugin
Use the one-job implementation.
Show one local Media Library image when a public post or page has no featured image, without assigning, copying, rewriting, or deleting any post thumbnail data.