# 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

```bash
# From the plugin directory
composer install
```

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

```bash
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

```bash
# 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

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

### Build release ZIP

```bash
bash bin/deploy.sh
```

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

## WP-CLI Commands

```bash
# 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`](docs/FILTERS-HOOKS.md)

## License

GPL-3.0-or-later — see [LICENSE](https://www.gnu.org/licenses/gpl-3.0.txt)

## Author

**ROBOTSTXT** — [robotstxt.es](https://www.robotstxt.es/)
Contributors: javiercasares, robotstxt