robotstxt-og/readme.txt

=== 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.1
Requires PHP: 8.0
Version: 1.2.1
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](https://www.robotstxt.software/plugins/robotstxt-og/), install it from your WordPress dashboard (Plugins > Add New > Upload), and activate it. To receive automatic updates, install and activate [Manager (by ROBOTSTXT)](https://www.robotstxt.software/plugins/robotstxt-manager/).

= 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)](https://www.robotstxt.software/plugins/robotstxt-manager/). 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.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).

= 1.1.0 =

_Release date: 2026-03-28_

* Fixed: Fatal `TypeError` in `handle_thumbnail_change()` when `deleted_post_meta` passes an array of meta IDs as the first argument.
* Security: Added SSRF protection — outbound HEAD requests now block private and reserved IP ranges.
* Security: Replaced deprecated `FILTER_SANITIZE_SPECIAL_CHARS` with `FILTER_SANITIZE_FULL_SPECIAL_CHARS`.
* Added: GDPR Privacy API — custom OG title and description are included in WordPress personal data export and erase.
* Changed: Settings page and REST API now require `edit_others_posts`, allowing editors to manage OG settings.
* Changed: Minimum supported WordPress version raised to 6.8.
* Changed: Added `Network: true` header confirming Multisite compatibility.
* Added: PHPUnit test suite (Brain\Monkey) covering SSRF protection, format detection, and cache clearing.

= Previous versions =

If you want to see the full changelog, visit the [changelog](https://www.robotstxt.software/plugins/robotstxt-og/) page.

== Compliance ==

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

* [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/)
* [WordPress Plugin Security](https://developer.wordpress.org/plugins/wordpress-org/plugin-security/)
* [WordPress APIs Security](https://developer.wordpress.org/apis/security/)
* [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards)
* [Plugin Check (PCP)](https://wordpress.org/plugins/plugin-check/)