OpenGraph (by ROBOTSTXT)

Intelligent Open Graph image fallback for social media crawlers.

Automatically detects when a post's featured image uses a modern format (AVIF, WebP) that social media crawlers cannot render, and resolves a compatible JPEG/PNG alternative to use in og:image meta tags.

Requirements

• WordPress: 6.7+
• PHP: 8.2–8.5
• WP-CLI: 2.x (optional, for CLI tools)

Installation

# From the plugin directory
composer install

Activate the plugin through the WordPress admin or WP-CLI:

wp plugin activate robotstxt-og --allow-root

Architecture

robotstxt-og/
├── robotstxt-og.php                          # Main plugin file, constants, bootstrap
├── includes/
│   ├── class-robotstxt-og-image-fallback.php # Singleton, orchestration
│   ├── class-robotstxt-og-image-resolver.php # Image detection, HEAD requests, caching
│   ├── class-robotstxt-og-tags.php           # OG tag injection, SEO plugin filters
│   ├── class-robotstxt-og-cli.php            # WP-CLI commands
│   └── class-robotstxt-og-rest-api.php       # REST API endpoints
├── admin/
│   ├── class-robotstxt-og-admin-settings.php # Admin page, settings, cache actions
│   └── views/settings-page.php               # Settings page template (tabbed)
├── assets/
│   ├── admin.js                              # Media uploader integration
│   └── admin.css                             # Admin styles
├── languages/
│   └── robotstxt-og.pot                      # Translation template
├── docs/
│   ├── FILTERS-HOOKS.md                      # Developer filter/hook reference
│   ├── WP-CLI.md                             # WP-CLI command reference
│   └── IDEA.md                               # Original concept document
├── bin/
│   └── deploy.sh                             # Build and ZIP packaging script
├── robotstxt-updater.php                     # Auto-updater (Gitea-based)
├── uninstall.php                             # Data cleanup on uninstall
├── readme.txt                                # WordPress.org plugin readme
└── changelog.txt                             # Full changelog (WordPress.org format)

Development

Code Standards

# Lint
vendor/bin/phpcs .

# Auto-fix
vendor/bin/phpcbf .

# PHP compatibility check (8.2–8.5)
vendor/bin/phpcs -p . --standard=PHPCompatibility --runtime-set testVersion 8.2-8.5

Regenerate translation template

wp i18n make-pot . languages/robotstxt-og.pot --domain=robotstxt-og --exclude=vendor,node_modules,tests --allow-root

Build release ZIP

bash bin/deploy.sh

The ZIP is created at ../robotstxt-og-{version}.zip (i.e. in wp-content/plugins/).

WP-CLI Commands

# Resolve fallback for a single post
wp og-fallback resolve 123

# Re-resolve all posts with featured images
wp og-fallback resolve --all

# Dry-run (no changes saved)
wp og-fallback resolve --all --dry-run

# Clear cache for a single post
wp og-fallback clear-cache 123

# Clear all caches
wp og-fallback clear-cache --all

REST API

All endpoints require the manage_options capability.

Method	Endpoint	Description
POST	/wp-json/robotstxt-og/v1/resolve/{post_id}	Force re-resolve fallback image
GET	/wp-json/robotstxt-og/v1/status/{post_id}	Get current cache status

Filters

Filter	Default	Description
robotstxt_og_external_image_enabled	true	Enable/disable external image resolution
robotstxt_og_external_image_timeout	5	HEAD request timeout (seconds)
robotstxt_og_taxonomy_image	''	Image URL for taxonomy archive pages
robotstxt_og_enable_logging	false	Enable debug logging to debug.log

Full documentation: docs/FILTERS-HOOKS.md

License

GPL-3.0-or-later — see LICENSE

Author

ROBOTSTXT — robotstxt.es Contributors: javiercasares, robotstxt