OpenGraph (by ROBOTSTXT) git.robotstxt.es

=== OpenGraph (by ROBOTSTXT) === Contributors: robotstxt, javiercasares Tags: opengraph, open graph, twitter card, social media, seo Requires at least: 4.9.8 Tested up to: 7.1 Stable tag: 1.2.2 Requires PHP: 8.0 Version: 1.2.2 License: GPL-3.0-or-later License URI: https://www.gnu.org/licenses/gpl-3.0.txt

Intelligent Open Graph meta tags with automatic image fallback from AVIF/WebP to JPEG/PNG for social media crawlers.

== Description ==

Social media crawlers — Facebook, Twitter/X, LinkedIn, WhatsApp — do not support modern image formats such as AVIF and WebP. When a post's featured image uses one of these formats, the platform shows a broken or missing image preview.

OpenGraph (by ROBOTSTXT) outputs a complete set of Open Graph and Twitter Card meta tags and solves the format incompatibility automatically. It detects whether each post's featured image is in a supported format and, when needed, resolves and caches a compatible JPEG or PNG alternative.

How it works:

1. A visitor (or social media crawler) requests a page.
2. The plugin checks whether the post's featured image is in AVIF, WebP, or another unsupported format.
3. If so, it locates a JPEG or PNG version of the same image using HTTP HEAD requests.
4. The result is cached in postmeta so subsequent requests are instant.
5. The resolved image is injected into og:image (and related) meta tags.

Key features:

• Full Open Graph meta tag output: og:title, og:type, og:url, og:description, og:site_name, og:locale, og:image, og:image:width, og:image:height, og:image:type, og:image:alt
• Article-specific tags: article:published_time, article:modified_time, article:section, article:tag
• Twitter Card tags: twitter:card, twitter:site, twitter:creator, twitter:url, twitter:image, twitter:image:alt
• Automatic format detection — AVIF, WebP, GIF, BMP, SVG, TIFF
• HTTP HEAD-based image verification (no file downloads)
• Per-post custom OG title and description override (post editor meta box)
• Per-term custom OG title, image, and description override for Categories and Tags (term edit page)
• Global fallback image URL and homepage-specific image URL
• Cached results in postmeta for performance, with automatic invalidation on featured image change
• Negative caching for failed resolutions (1-hour transient)
• Integration with Yoast SEO and RankMath (no duplicate tags)
• Taxonomy archive image support via developer filter
• Admin panel with Settings, Tools, and Diagnostics tabs
• WP-CLI commands for batch operations
• REST API endpoints for programmatic access
• Multisite compatible (per-site configuration)
• Full internationalization support (es_ES and ca included)

== Using the plugin ==

= WP-CLI =

List available commands:

wp og-fallback --help

Resolve the fallback image for a single post:

wp og-fallback resolve 123

Re-resolve all posts (clears cache first):

wp og-fallback resolve --all

Dry-run re-resolution without saving:

wp og-fallback resolve --all --dry-run

Re-resolve all posts of a specific type:

wp og-fallback resolve --all --post-type=page

Clear cache for a single post:

wp og-fallback clear-cache 123

Clear all cached fallback URLs:

wp og-fallback clear-cache --all

= REST API =

The plugin exposes two REST API endpoints under the robotstxt-og/v1 namespace. Both require the edit_others_posts capability (editor and above).

Force re-resolve a post's fallback image:

POST /wp-json/robotstxt-og/v1/resolve/{post_id}

Returns: { post_id, resolved_url, cached, success }

Get current cached status for a post:

GET /wp-json/robotstxt-og/v1/status/{post_id}

Returns: { post_id, cached_url, original_url, has_cache }

== Extra Configurations ==

Developer filters available in functions.php or a custom plugin:

Disable external image resolution:

add_filter( 'robotstxt_og_external_image_enabled', '__return_false' );

Adjust HEAD request timeout (seconds, default: 5):

add_filter( 'robotstxt_og_external_image_timeout', fn() => 10 );

Provide an OG image for taxonomy archives:

add_filter( 'robotstxt_og_taxonomy_image', fn( $url, $term_id ) => wp_get_attachment_url( get_term_meta( $term_id, 'my_image_id', true ) ), 10, 2 );

Enable debug logging to debug.log:

add_filter( 'robotstxt_og_enable_logging', '__return_true' );

== Installation ==

= Automatic download =

Download the plugin ZIP from robotstxt.software, install it from your WordPress dashboard (Plugins > Add New > Upload), and activate it. To receive automatic updates, install and activate Manager (by ROBOTSTXT).

= Manual download =

Extract the contents of the ZIP and upload the folder to the /wp-content/plugins/robotstxt-og/ directory. Once uploaded, it will appear in your plugin list and can be activated normally.

= After activation =

1. Go to Settings > OpenGraph.
2. Optionally set a Global Fallback Image (paste a direct JPEG or PNG URL) to use when no compatible alternative is found.
3. Optionally set a Homepage Image for the site front page.
4. Configure your Twitter/X site handle (e.g. @example) if you want twitter:site output.
5. Use the Tools tab to re-resolve all existing posts in one click.
6. Use the Diagnostics tab to view cached entries and test individual URLs.

== Frequently Asked Questions ==

= How do I get updates for this plugin? =

Updates are delivered by Manager (by ROBOTSTXT). When the Manager plugin is not installed and active, this plugin shows a dismissible notice on the Plugins page and a reminder on its settings page.

= Does this plugin duplicate og:image tags from Yoast SEO or RankMath? =

No. When Yoast SEO or RankMath is active, the plugin hooks into their existing filter (wpseo_opengraph_image or rank_math/opengraph/facebook/og_image) instead of injecting tags directly. The result is a single og:image tag, with the resolved fallback applied only when needed.

= Will it work if my images are stored on an external CDN? =

Yes. The plugin sends HTTP HEAD requests to verify alternative URLs, so it works with any URL-accessible image regardless of where it is hosted. You can disable external image resolution entirely with the robotstxt_og_external_image_enabled filter if needed.

= Why aren't AVIF/WebP images supported directly? =

AVIF and WebP are not supported by the Open Graph specification as implemented by major social media crawlers (Facebook, LinkedIn, WhatsApp, etc.). These platforms render a broken image or no image at all when an unsupported format is provided. This plugin works around that limitation by serving a JPEG/PNG fallback.

= What happens if no JPEG/PNG alternative is found? =

The plugin falls back to the Global Fallback Image configured in Settings > OpenGraph. If no fallback image is set, no og:image tag is injected for that post, leaving any existing tag from your SEO plugin in place.

= Is the cache refreshed automatically? =

Yes. When you change or remove a post's featured image, the cached fallback URL is cleared automatically. The new image will be resolved on the next page view, or can be forced immediately via WP-CLI (wp og-fallback resolve <id>) or the REST API.

= Does it work on WordPress Multisite? =

Yes. Each site in the network has its own independent configuration. There is no network-wide settings panel.

= Can I use this with classic themes and block themes? =

Yes. The plugin hooks into wp_head for direct tag injection and filters Yoast/RankMath when those plugins are active. It is compatible with both classic and block-based themes.

== Compatibility ==

• WordPress: 4.9.8 - 7.1
• PHP: 8.0 - 8.5
• WP-CLI: 2.x
• MariaDB: 10.6+

Compatible SEO plugins:

• Yoast SEO (integration via wpseo_opengraph_image filter)
• RankMath (integration via rank_math/opengraph/facebook/og_image filter)

== Changelog ==

= 1.2.2 =

Release date: 2026-08-24

• Changed: Manager (by ROBOTSTXT) detection now uses the ecosystem presence constant ROBOTSTXT_MANAGER_NOTICED (Manager 1.6.2+); for older Manager versions it falls back to the plugin-list scan.
• Changed: Tested up to WordPress 7.1 (requires 4.9.8, re-verified); PHP 8.0 – 8.5 (re-verified).
• Dev: Composer dev dependencies updated (PHPStan 2.2.9, Mockery 1.6.15, WordPress hook stubs 1.13.0).

= 1.2.1 =

Release date: 2026-08-17

• Added: Dismissible notice on the Plugins page recommending Manager (by ROBOTSTXT) when it is not installed and active, plus a persistent reminder on the plugin settings page.
• Changed: Plugin updates are now delivered by Manager (by ROBOTSTXT); the bundled Gitea self-updater (robotstxt-updater.php) and update.json were removed.
• Changed: Plugin home, update, and author URLs now point to https://www.robotstxt.software/plugins/robotstxt-og/.
• Changed: Tested up to WordPress 7.1.

= 1.2.0 =

Release date: 2026-08-10

• Added: Per-term Open Graph metadata for Categories and Tags on the term edit page — custom OG title, OG image URL, and OG description, exposed on term archives.
• Added: Manual og:image:alt override (per-post meta box and per-term), emitted as og:image:alt and twitter:image:alt.
• Added: Per-post og:type override (Default / website / article); article:* sub-tags now emit on the resolved article type.
• Added: Twitter/X twitter:url (canonical) and per-post twitter:creator (author handle); handles normalised with a leading @.
• Added: Platform integration tags (global settings) — Facebook fb:app_id/admins/pages, Pinterest p:domain_verify + disable-pinning toggle, Telegram telegram:channel, Slack slack-app-id.
• Added: Mobile / Web App tags (global settings) — theme-color, web-app name, PWA standalone toggle, iOS status bar style, format-detection; Open Graph namespace added to <html>.
• Added: Uninstall cleanup extended to remove the per-term OG meta and _og_image_alt / _og_type / _twitter_creator (opt-in only).
• Changed: Minimum supported WordPress lowered from 6.8 to 4.9.8 (verified by WP-Compat).
• Changed: Minimum supported PHP lowered from 8.2 to 8.0 (verified by the PHPCompatibility scan).

= Previous versions =

If you want to see the full changelog, visit the changelog page.

== Compliance ==

This plugin adheres to the following security measures and review protocols for each version:

• WordPress Plugin Handbook
• WordPress Plugin Security
• WordPress APIs Security
• WordPress Coding Standards
• Plugin Check (PCP)