132 lines
4.1 KiB
Markdown
132 lines
4.1 KiB
Markdown
# 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
|