# 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. |