v1.0.0
This commit is contained in:
parent
ac2c7a8014
commit
f7702f2872
25 changed files with 6453 additions and 0 deletions
240
docs/FILTERS-HOOKS.md
Normal file
240
docs/FILTERS-HOOKS.md
Normal file
|
|
@ -0,0 +1,240 @@
|
|||
# Filters & Hooks Reference
|
||||
|
||||
Developer reference for all filters and actions provided by the **OpenGraph (by ROBOTSTXT)** plugin.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Filters](#filters)
|
||||
- [robotstxt_og_external_image_enabled](#robotstxt_og_external_image_enabled)
|
||||
- [robotstxt_og_external_image_timeout](#robotstxt_og_external_image_timeout)
|
||||
- [robotstxt_og_taxonomy_image](#robotstxt_og_taxonomy_image)
|
||||
- [robotstxt_og_enable_logging](#robotstxt_og_enable_logging)
|
||||
- [Actions](#actions)
|
||||
- [SEO Plugin Integrations](#seo-plugin-integrations)
|
||||
|
||||
---
|
||||
|
||||
## Filters
|
||||
|
||||
### `robotstxt_og_external_image_enabled`
|
||||
|
||||
Controls whether the plugin attempts to resolve fallback images for external URLs (images hosted on a different domain than the WordPress site).
|
||||
|
||||
**Default:** `true`
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `$enabled` | `bool` | Whether external image resolution is enabled. |
|
||||
| `$image_url` | `string` | The external image URL being evaluated. |
|
||||
|
||||
**Returns:** `bool`
|
||||
|
||||
**Example — disable external image resolution entirely:**
|
||||
|
||||
```php
|
||||
add_filter( 'robotstxt_og_external_image_enabled', '__return_false' );
|
||||
```
|
||||
|
||||
**Example — disable only for a specific CDN domain:**
|
||||
|
||||
```php
|
||||
add_filter( 'robotstxt_og_external_image_enabled', function ( bool $enabled, string $image_url ): bool {
|
||||
if ( str_contains( $image_url, 'cdn.example.com' ) ) {
|
||||
return false;
|
||||
}
|
||||
return $enabled;
|
||||
}, 10, 2 );
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `robotstxt_og_external_image_timeout`
|
||||
|
||||
Sets the HTTP request timeout (in seconds) used when verifying whether a fallback image URL exists via a HEAD request.
|
||||
|
||||
**Default:** `5` (seconds)
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `$timeout` | `int` | Timeout in seconds for the HEAD request. |
|
||||
| `$url` | `string` | The image URL being tested. |
|
||||
|
||||
**Returns:** `int`
|
||||
|
||||
**Example — increase timeout for slow external servers:**
|
||||
|
||||
```php
|
||||
add_filter( 'robotstxt_og_external_image_timeout', function ( int $timeout, string $url ): int {
|
||||
if ( str_contains( $url, 'slow-cdn.example.com' ) ) {
|
||||
return 15;
|
||||
}
|
||||
return $timeout;
|
||||
}, 10, 2 );
|
||||
```
|
||||
|
||||
**Example — set a global lower timeout for performance:**
|
||||
|
||||
```php
|
||||
add_filter( 'robotstxt_og_external_image_timeout', function (): int {
|
||||
return 3;
|
||||
} );
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `robotstxt_og_taxonomy_image`
|
||||
|
||||
Provides a fallback OG image URL for taxonomy archive pages (categories, tags, custom taxonomies). By default, taxonomy archives do not have a featured image, so this filter is the primary way to supply one.
|
||||
|
||||
**Default:** `''` (empty string — no image)
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `$image_url` | `string` | Image URL to use. Empty string by default. |
|
||||
| `$term_id` | `int` | The term ID of the current taxonomy archive. |
|
||||
|
||||
**Returns:** `string` A valid image URL, or empty string to skip.
|
||||
|
||||
**Example — use a custom field set on the term:**
|
||||
|
||||
```php
|
||||
add_filter( 'robotstxt_og_taxonomy_image', function ( string $image_url, int $term_id ): string {
|
||||
$custom_image_id = get_term_meta( $term_id, 'og_image_id', true );
|
||||
|
||||
if ( $custom_image_id ) {
|
||||
$url = wp_get_attachment_url( (int) $custom_image_id );
|
||||
return $url ? $url : $image_url;
|
||||
}
|
||||
|
||||
return $image_url;
|
||||
}, 10, 2 );
|
||||
```
|
||||
|
||||
**Example — use a WooCommerce category thumbnail:**
|
||||
|
||||
```php
|
||||
add_filter( 'robotstxt_og_taxonomy_image', function ( string $image_url, int $term_id ): string {
|
||||
$thumbnail_id = get_term_meta( $term_id, 'thumbnail_id', true );
|
||||
|
||||
if ( $thumbnail_id ) {
|
||||
$url = wp_get_attachment_url( (int) $thumbnail_id );
|
||||
return $url ? $url : $image_url;
|
||||
}
|
||||
|
||||
return $image_url;
|
||||
}, 10, 2 );
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `robotstxt_og_enable_logging`
|
||||
|
||||
Enables or disables debug logging to `wp-content/debug.log`. When enabled, resolution events (cache hits, cache misses, format detection, HEAD request results) are written to the error log.
|
||||
|
||||
**Default:** `false`
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `$enabled` | `bool` | Whether debug logging is active. |
|
||||
|
||||
**Returns:** `bool`
|
||||
|
||||
**Note:** Requires `WP_DEBUG` and `WP_DEBUG_LOG` to be enabled in `wp-config.php` for output to appear in `debug.log`.
|
||||
|
||||
**Example — enable logging (e.g. during development, in `wp-config.php`):**
|
||||
|
||||
```php
|
||||
// wp-config.php
|
||||
define( 'WP_DEBUG', true );
|
||||
define( 'WP_DEBUG_LOG', true );
|
||||
```
|
||||
|
||||
```php
|
||||
// functions.php or a mu-plugin
|
||||
add_filter( 'robotstxt_og_enable_logging', '__return_true' );
|
||||
```
|
||||
|
||||
**Example — enable logging only for specific users:**
|
||||
|
||||
```php
|
||||
add_filter( 'robotstxt_og_enable_logging', function ( bool $enabled ): bool {
|
||||
return current_user_can( 'manage_options' ) ? true : $enabled;
|
||||
} );
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Actions
|
||||
|
||||
The plugin does not currently expose custom action hooks. WordPress core hooks used internally include:
|
||||
|
||||
| Hook | Context | Purpose |
|
||||
|------|---------|---------|
|
||||
| `plugins_loaded` | Global | Loads text domain for translations. |
|
||||
| `wp_head` | Frontend | Injects `og:image` meta tags (only when no SEO plugin is active). |
|
||||
| `admin_menu` | Admin | Registers the Settings > OpenGraph settings page. |
|
||||
| `admin_init` | Admin | Registers settings, handles cache clear/resolve actions. |
|
||||
| `admin_enqueue_scripts` | Admin | Enqueues media uploader and admin CSS/JS. |
|
||||
| `rest_api_init` | REST API | Registers the `robotstxt-og/v1` REST endpoints. |
|
||||
| `updated_post_meta` | Global | Auto-clears fallback cache when `_thumbnail_id` changes. |
|
||||
| `deleted_post_meta` | Global | Auto-clears fallback cache when `_thumbnail_id` is removed. |
|
||||
|
||||
---
|
||||
|
||||
## SEO Plugin Integrations
|
||||
|
||||
When a supported SEO plugin is detected, the plugin switches from direct `og:image` tag injection to filtering the SEO plugin's output. This prevents duplicate meta tags.
|
||||
|
||||
### Yoast SEO
|
||||
|
||||
**Filter:** `wpseo_opengraph_image`
|
||||
|
||||
When Yoast SEO is active (`WPSEO_VERSION` is defined), the plugin hooks into this filter to provide the resolved fallback image. The plugin only overrides the value if a valid fallback URL is resolved; otherwise it returns the original Yoast value unchanged.
|
||||
|
||||
### RankMath
|
||||
|
||||
**Filter:** `rank_math/opengraph/facebook/og_image`
|
||||
|
||||
When RankMath is active (`RankMath` class exists), the plugin hooks into this filter with the same logic as the Yoast integration.
|
||||
|
||||
### Adding Support for Other SEO Plugins
|
||||
|
||||
To integrate with another SEO plugin, hook into the plugin's OG image filter and call the resolver manually:
|
||||
|
||||
```php
|
||||
add_filter( 'your_seo_plugin_og_image_filter', function ( string $image ) : string {
|
||||
if ( ! is_singular() ) {
|
||||
return $image;
|
||||
}
|
||||
|
||||
$post_id = get_queried_object_id();
|
||||
$resolver = Robotstxt_OG_Image_Fallback::get_instance()->get_resolver();
|
||||
$fallback = $resolver->get_fallback_image( $post_id );
|
||||
|
||||
return ! empty( $fallback ) ? $fallback : $image;
|
||||
} );
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Postmeta Keys (Internal Cache)
|
||||
|
||||
These postmeta keys are used internally for caching and should not be modified directly:
|
||||
|
||||
| Meta Key | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `_og_image_fallback_url` | `string` | Cached resolved fallback image URL for a post. |
|
||||
|
||||
These transient keys are used for negative caching (failed HEAD request results):
|
||||
|
||||
| Transient Key Pattern | TTL | Description |
|
||||
|-----------------------|-----|-------------|
|
||||
| `robotstxt_og_miss_{md5_of_url}` | 1 hour | Marks a URL as unreachable to prevent repeated requests. |
|
||||
Loading…
Reference in a new issue