7.3 KiB
Filters & Hooks Reference
Developer reference for all filters and actions provided by the OpenGraph (by ROBOTSTXT) plugin.
Table of Contents
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:
add_filter( 'robotstxt_og_external_image_enabled', '__return_false' );
Example — disable only for a specific CDN domain:
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:
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:
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:
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:
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):
// wp-config.php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
// functions.php or a mu-plugin
add_filter( 'robotstxt_og_enable_logging', '__return_true' );
Example — enable logging only for specific users:
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:
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. |