641 lines
17 KiB
PHP
641 lines
17 KiB
PHP
<?php
|
|
/**
|
|
* Image Resolver Class
|
|
*
|
|
* Handles detection and resolution of compatible fallback images for Open Graph tags.
|
|
*
|
|
* @package ROBOTSTXT_OG
|
|
* @since 1.0.0
|
|
*/
|
|
|
|
if ( ! defined( 'ABSPATH' ) ) {
|
|
exit; // Exit if accessed directly.
|
|
}
|
|
|
|
/**
|
|
* Class Robotstxt_OG_Image_Resolver
|
|
*
|
|
* Resolves compatible image formats for social media crawlers.
|
|
*
|
|
* @since 1.0.0
|
|
*/
|
|
class Robotstxt_OG_Image_Resolver {
|
|
|
|
/**
|
|
* Transient prefix for negative cache entries.
|
|
*
|
|
* @since 1.0.0
|
|
* @var string
|
|
*/
|
|
const NEGATIVE_CACHE_PREFIX = 'robotstxt_og_miss_';
|
|
|
|
/**
|
|
* How long to cache negative results (URL not found), in seconds.
|
|
*
|
|
* @since 1.0.0
|
|
* @var int
|
|
*/
|
|
const NEGATIVE_CACHE_TTL = HOUR_IN_SECONDS;
|
|
|
|
/**
|
|
* Get fallback image URL for a post.
|
|
*
|
|
* Checks cache first, then resolves if needed.
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param int $post_id Post ID.
|
|
* @return string Image URL or empty string if not found.
|
|
*/
|
|
public function get_fallback_image( int $post_id ): string {
|
|
// Check postmeta cache first.
|
|
$cached_url = get_post_meta( $post_id, '_og_image_fallback_url', true );
|
|
|
|
if ( is_string( $cached_url ) && ! empty( $cached_url ) && $this->is_valid_url( $cached_url ) ) {
|
|
$this->log(
|
|
'cache_hit',
|
|
array(
|
|
'post_id' => $post_id,
|
|
'url' => $cached_url,
|
|
)
|
|
);
|
|
return esc_url_raw( $cached_url );
|
|
}
|
|
|
|
$this->log( 'cache_miss', array( 'post_id' => $post_id ) );
|
|
|
|
// No valid cache, resolve image.
|
|
return $this->resolve_image( $post_id );
|
|
}
|
|
|
|
/**
|
|
* Resolve fallback image for a post.
|
|
*
|
|
* Detects featured image format and finds compatible alternative if needed.
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param int $post_id Post ID.
|
|
* @return string Resolved image URL or empty string.
|
|
*/
|
|
public function resolve_image( int $post_id ): string {
|
|
// Get featured image ID.
|
|
$image_id = get_post_thumbnail_id( $post_id );
|
|
|
|
if ( empty( $image_id ) ) {
|
|
// No featured image, check for global fallback.
|
|
$this->log( 'no_featured_image', array( 'post_id' => $post_id ) );
|
|
return $this->get_global_fallback();
|
|
}
|
|
|
|
// Get image URL.
|
|
$image_url = wp_get_attachment_url( $image_id );
|
|
|
|
if ( empty( $image_url ) ) {
|
|
$this->log(
|
|
'no_attachment_url',
|
|
array(
|
|
'post_id' => $post_id,
|
|
'image_id' => $image_id,
|
|
)
|
|
);
|
|
return $this->get_global_fallback();
|
|
}
|
|
|
|
// Detect file extension.
|
|
$url_path = wp_parse_url( $image_url, PHP_URL_PATH );
|
|
$path_info = pathinfo( is_string( $url_path ) ? $url_path : '' );
|
|
$extension = isset( $path_info['extension'] ) ? strtolower( $path_info['extension'] ) : '';
|
|
|
|
// If already a compatible format, save and return.
|
|
if ( in_array( $extension, array( 'jpg', 'jpeg', 'png' ), true ) ) {
|
|
$this->log(
|
|
'compatible_format',
|
|
array(
|
|
'post_id' => $post_id,
|
|
'url' => $image_url,
|
|
)
|
|
);
|
|
$this->save_cache( $post_id, $image_url );
|
|
return esc_url_raw( $image_url );
|
|
}
|
|
|
|
// Modern format detected (webp, avif, etc.), find alternative.
|
|
if ( in_array( $extension, array( 'webp', 'avif', 'gif', 'bmp', 'svg', 'tiff', 'tif' ), true ) ) {
|
|
$this->log(
|
|
'modern_format_detected',
|
|
array(
|
|
'post_id' => $post_id,
|
|
'extension' => $extension,
|
|
'url' => $image_url,
|
|
)
|
|
);
|
|
|
|
$alternative = $this->find_compatible_alternative( $image_url );
|
|
|
|
if ( ! empty( $alternative ) ) {
|
|
$this->log(
|
|
'alternative_found',
|
|
array(
|
|
'post_id' => $post_id,
|
|
'original' => $image_url,
|
|
'alternative' => $alternative,
|
|
)
|
|
);
|
|
$this->save_cache( $post_id, $alternative );
|
|
return esc_url_raw( $alternative );
|
|
}
|
|
|
|
$this->log(
|
|
'no_alternative_found',
|
|
array(
|
|
'post_id' => $post_id,
|
|
'url' => $image_url,
|
|
)
|
|
);
|
|
}
|
|
|
|
// No alternative found, return original (don't cache to allow retry on next request).
|
|
return esc_url_raw( $image_url );
|
|
}
|
|
|
|
/**
|
|
* Find compatible image alternative by checking .jpg and .png versions.
|
|
*
|
|
* Uses HTTP HEAD requests to verify file existence.
|
|
* Respects the `robotstxt_og_external_image_enabled` filter for external images.
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param string $image_url Original image URL.
|
|
* @return string Compatible image URL or empty string if not found.
|
|
*/
|
|
public function find_compatible_alternative( string $image_url ): string {
|
|
// Check if external images are allowed.
|
|
if ( $this->is_external_url( $image_url ) ) {
|
|
/**
|
|
* Filter whether to attempt resolution for external images.
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param bool $enabled Whether external image resolution is enabled.
|
|
* @param string $image_url The external image URL being resolved.
|
|
*/
|
|
$enabled = apply_filters( 'robotstxt_og_external_image_enabled', true, $image_url );
|
|
|
|
if ( ! $enabled ) {
|
|
$this->log( 'external_image_skipped', array( 'url' => $image_url ) );
|
|
return '';
|
|
}
|
|
}
|
|
|
|
// Strip query string for URL manipulation.
|
|
$clean_url = strtok( $image_url, '?' );
|
|
|
|
if ( ! is_string( $clean_url ) ) {
|
|
return '';
|
|
}
|
|
|
|
// Parse URL and get base path without extension.
|
|
$url_path = wp_parse_url( $clean_url, PHP_URL_PATH );
|
|
$path_info = pathinfo( is_string( $url_path ) ? $url_path : '' );
|
|
$filename = $path_info['filename'];
|
|
$dir = $path_info['dirname'] ?? '';
|
|
|
|
if ( empty( $filename ) ) {
|
|
return '';
|
|
}
|
|
|
|
// Reconstruct base URL.
|
|
$parsed = wp_parse_url( $clean_url );
|
|
$base_url = ( $parsed['scheme'] ?? 'https' ) . '://' . ( $parsed['host'] ?? '' );
|
|
|
|
if ( ! empty( $parsed['port'] ) ) {
|
|
$base_url .= ':' . $parsed['port'];
|
|
}
|
|
|
|
$base_url .= trailingslashit( $dir ) . $filename;
|
|
|
|
// Try .jpg first, then .png.
|
|
$alternatives = array( '.jpg', '.png', '.jpeg' );
|
|
|
|
foreach ( $alternatives as $ext ) {
|
|
$test_url = $base_url . $ext;
|
|
|
|
if ( $this->url_exists( $test_url ) ) {
|
|
return $test_url;
|
|
}
|
|
}
|
|
|
|
return '';
|
|
}
|
|
|
|
/**
|
|
* Check whether a URL is safe to make server-side HTTP requests to.
|
|
*
|
|
* Rejects non-http(s) schemes and URLs that resolve to private or
|
|
* reserved IP ranges to prevent Server-Side Request Forgery (SSRF).
|
|
*
|
|
* @since 1.0.3
|
|
*
|
|
* @param string $url URL to validate.
|
|
* @return bool True if the URL is safe to request.
|
|
*/
|
|
private function is_safe_url( string $url ): bool {
|
|
$scheme = wp_parse_url( $url, PHP_URL_SCHEME );
|
|
if ( ! in_array( $scheme, array( 'http', 'https' ), true ) ) {
|
|
return false;
|
|
}
|
|
|
|
$host = wp_parse_url( $url, PHP_URL_HOST );
|
|
if ( ! is_string( $host ) || '' === $host ) {
|
|
return false;
|
|
}
|
|
|
|
// Strip IPv6 brackets for validation.
|
|
$host_bare = trim( $host, '[]' );
|
|
|
|
// If the host is already an IP address, validate it directly.
|
|
if ( filter_var( $host_bare, FILTER_VALIDATE_IP ) !== false ) {
|
|
return (bool) filter_var( $host_bare, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE );
|
|
}
|
|
|
|
// Resolve hostname to IP and validate it is not private/reserved.
|
|
$resolved = gethostbyname( $host_bare );
|
|
|
|
// gethostbyname() returns the original string on failure.
|
|
if ( $resolved === $host_bare ) {
|
|
return false;
|
|
}
|
|
|
|
return (bool) filter_var( $resolved, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE );
|
|
}
|
|
|
|
/**
|
|
* Check if a URL exists using HTTP HEAD request.
|
|
*
|
|
* Uses negative caching to avoid repeated requests for non-existent URLs.
|
|
* URLs resolving to private or reserved IP ranges are rejected (SSRF protection).
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param string $url URL to check.
|
|
* @return bool True if URL returns 200-299 status code.
|
|
*/
|
|
private function url_exists( string $url ): bool {
|
|
// Reject URLs that resolve to private/reserved IP ranges (SSRF protection).
|
|
if ( ! $this->is_safe_url( $url ) ) {
|
|
$this->log( 'ssrf_blocked', array( 'url' => $url ) );
|
|
return false;
|
|
}
|
|
|
|
// Check negative cache to avoid repeated failed requests.
|
|
$cache_key = self::NEGATIVE_CACHE_PREFIX . md5( $url );
|
|
|
|
if ( false !== get_transient( $cache_key ) ) {
|
|
$this->log( 'negative_cache_hit', array( 'url' => $url ) );
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* Filter the timeout in seconds for external image HEAD requests.
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param int $timeout The timeout in seconds.
|
|
* @param string $url The URL being checked.
|
|
*/
|
|
$timeout = (int) apply_filters( 'robotstxt_og_external_image_timeout', 5, $url );
|
|
|
|
// Use WordPress HTTP API.
|
|
$response = wp_remote_head(
|
|
$url,
|
|
array(
|
|
'timeout' => max( 1, $timeout ),
|
|
'redirection' => 5,
|
|
'user-agent' => 'WordPress/' . get_bloginfo( 'version' ) . '; ' . get_bloginfo( 'url' ),
|
|
)
|
|
);
|
|
|
|
// Handle WP_Error (network failure, timeout, etc.).
|
|
if ( is_wp_error( $response ) ) {
|
|
$this->log(
|
|
'head_request_error',
|
|
array(
|
|
'url' => $url,
|
|
'error' => $response->get_error_message(),
|
|
)
|
|
);
|
|
set_transient( $cache_key, '1', self::NEGATIVE_CACHE_TTL );
|
|
return false;
|
|
}
|
|
|
|
// Check response code.
|
|
$code = (int) wp_remote_retrieve_response_code( $response );
|
|
$exists = $code >= 200 && $code < 300;
|
|
|
|
if ( ! $exists ) {
|
|
$this->log(
|
|
'head_request_failed',
|
|
array(
|
|
'url' => $url,
|
|
'code' => $code,
|
|
)
|
|
);
|
|
set_transient( $cache_key, '1', self::NEGATIVE_CACHE_TTL );
|
|
} else {
|
|
$this->log(
|
|
'head_request_success',
|
|
array(
|
|
'url' => $url,
|
|
'code' => $code,
|
|
)
|
|
);
|
|
}
|
|
|
|
return $exists;
|
|
}
|
|
|
|
/**
|
|
* Check if a URL is external (hosted on a different domain).
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param string $url URL to check.
|
|
* @return bool True if the URL is external.
|
|
*/
|
|
private function is_external_url( string $url ): bool {
|
|
$site_host = wp_parse_url( get_bloginfo( 'url' ), PHP_URL_HOST );
|
|
$image_host = wp_parse_url( $url, PHP_URL_HOST );
|
|
|
|
if ( empty( $site_host ) || empty( $image_host ) ) {
|
|
return false;
|
|
}
|
|
|
|
return strtolower( $site_host ) !== strtolower( $image_host );
|
|
}
|
|
|
|
/**
|
|
* Get global fallback image URL from settings.
|
|
*
|
|
* If the stored image is in an incompatible format (AVIF, WebP, etc.),
|
|
* attempts to resolve a JPEG/PNG alternative. Returns empty string if
|
|
* no compatible image is found.
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @return string Compatible image URL or empty string.
|
|
*/
|
|
private function get_global_fallback(): string {
|
|
$option_value = get_option( 'robotstxt_og_fallback_image', '' );
|
|
$fallback_url = is_string( $option_value ) ? $option_value : '';
|
|
|
|
if ( empty( $fallback_url ) || ! $this->is_valid_url( $fallback_url ) ) {
|
|
return '';
|
|
}
|
|
|
|
return esc_url_raw( $fallback_url );
|
|
}
|
|
|
|
/**
|
|
* Get the configured homepage image URL.
|
|
*
|
|
* If the stored image is in an incompatible format (AVIF, WebP, etc.),
|
|
* attempts to resolve a JPEG/PNG alternative before falling back to
|
|
* the global fallback image.
|
|
*
|
|
* @since 1.1.0
|
|
*
|
|
* @return string Compatible image URL or empty string.
|
|
*/
|
|
public function get_homepage_image(): string {
|
|
$option_value = get_option( 'robotstxt_og_homepage_image', '' );
|
|
$image_url = is_string( $option_value ) ? $option_value : '';
|
|
|
|
if ( ! empty( $image_url ) && $this->is_valid_url( $image_url ) ) {
|
|
return esc_url_raw( $image_url );
|
|
}
|
|
|
|
// Fall back to global fallback image.
|
|
return $this->get_global_fallback();
|
|
}
|
|
|
|
/**
|
|
* Ensure an image URL is in a format compatible with social media crawlers.
|
|
*
|
|
* Returns the URL unchanged for JPEG/PNG. For incompatible formats
|
|
* (AVIF, WebP, GIF, SVG, BMP, TIFF), attempts to find a JPEG/PNG
|
|
* alternative via find_compatible_alternative(). Returns empty string
|
|
* if no compatible version can be found.
|
|
*
|
|
* @since 1.2.0
|
|
*
|
|
* @param string $image_url Image URL to check.
|
|
* @return string Compatible image URL or empty string.
|
|
*/
|
|
public function ensure_compatible_format( string $image_url ): string {
|
|
$url_path = wp_parse_url( $image_url, PHP_URL_PATH );
|
|
$path_info = pathinfo( is_string( $url_path ) ? $url_path : '' );
|
|
$extension = isset( $path_info['extension'] ) ? strtolower( $path_info['extension'] ) : '';
|
|
|
|
// Already a compatible format.
|
|
if ( in_array( $extension, array( 'jpg', 'jpeg', 'png' ), true ) ) {
|
|
return esc_url_raw( $image_url );
|
|
}
|
|
|
|
// Incompatible modern format — try to find a JPEG/PNG alternative.
|
|
if ( in_array( $extension, array( 'webp', 'avif', 'gif', 'bmp', 'svg', 'tiff', 'tif' ), true ) ) {
|
|
$this->log(
|
|
'fallback_image_incompatible_format',
|
|
array(
|
|
'url' => $image_url,
|
|
'extension' => $extension,
|
|
)
|
|
);
|
|
|
|
$alternative = $this->find_compatible_alternative( $image_url );
|
|
|
|
if ( ! empty( $alternative ) ) {
|
|
$this->log(
|
|
'fallback_image_alternative_found',
|
|
array(
|
|
'original' => $image_url,
|
|
'alternative' => $alternative,
|
|
)
|
|
);
|
|
return esc_url_raw( $alternative );
|
|
}
|
|
|
|
$this->log( 'fallback_image_no_alternative', array( 'url' => $image_url ) );
|
|
|
|
// No compatible alternative found — discard this image.
|
|
return '';
|
|
}
|
|
|
|
// Unknown extension — return as-is and let the caller decide.
|
|
return esc_url_raw( $image_url );
|
|
}
|
|
|
|
/**
|
|
* Save resolved URL to postmeta cache.
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param int $post_id Post ID.
|
|
* @param string $url Resolved image URL.
|
|
* @return void
|
|
*/
|
|
private function save_cache( int $post_id, string $url ): void {
|
|
update_post_meta( $post_id, '_og_image_fallback_url', esc_url_raw( $url ) );
|
|
}
|
|
|
|
/**
|
|
* Clear cached fallback URL for a post.
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param int $post_id Post ID.
|
|
* @return void
|
|
*/
|
|
public function clear_cache( int $post_id ): void {
|
|
delete_post_meta( $post_id, '_og_image_fallback_url' );
|
|
}
|
|
|
|
/**
|
|
* Get fallback image URL for a taxonomy term.
|
|
*
|
|
* Checks term meta cache first, then looks for a term image set by
|
|
* supported plugins (e.g., Yoast SEO term images, custom term meta).
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param int $term_id Term ID.
|
|
* @return string Image URL or empty string if not found.
|
|
*/
|
|
public function get_taxonomy_fallback_image( int $term_id ): string {
|
|
// Check term meta cache first.
|
|
$cached_url = get_term_meta( $term_id, '_og_image_fallback_url', true );
|
|
|
|
if ( is_string( $cached_url ) && ! empty( $cached_url ) && $this->is_valid_url( $cached_url ) ) {
|
|
$this->log(
|
|
'taxonomy_cache_hit',
|
|
array(
|
|
'term_id' => $term_id,
|
|
'url' => $cached_url,
|
|
)
|
|
);
|
|
return esc_url_raw( $cached_url );
|
|
}
|
|
|
|
$this->log( 'taxonomy_cache_miss', array( 'term_id' => $term_id ) );
|
|
|
|
return $this->resolve_taxonomy_image( $term_id );
|
|
}
|
|
|
|
/**
|
|
* Resolve fallback image for a taxonomy term.
|
|
*
|
|
* Checks for term images set by Yoast SEO or other plugins via a filter.
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param int $term_id Term ID.
|
|
* @return string Resolved image URL or empty string.
|
|
*/
|
|
public function resolve_taxonomy_image( int $term_id ): string {
|
|
/**
|
|
* Filter the image URL for a taxonomy term.
|
|
*
|
|
* Use this filter to integrate with plugins that assign images to
|
|
* taxonomy terms (e.g., custom term meta, theme functions).
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param string $image_url The image URL. Empty string if none.
|
|
* @param int $term_id The term ID being resolved.
|
|
*/
|
|
$image_url = (string) apply_filters( 'robotstxt_og_taxonomy_image', '', $term_id );
|
|
|
|
if ( empty( $image_url ) || ! $this->is_valid_url( $image_url ) ) {
|
|
return $this->get_global_fallback();
|
|
}
|
|
|
|
// Detect file extension and resolve if needed.
|
|
$url_path = wp_parse_url( $image_url, PHP_URL_PATH );
|
|
$path_info = pathinfo( is_string( $url_path ) ? $url_path : '' );
|
|
$extension = isset( $path_info['extension'] ) ? strtolower( $path_info['extension'] ) : '';
|
|
|
|
if ( in_array( $extension, array( 'jpg', 'jpeg', 'png' ), true ) ) {
|
|
update_term_meta( $term_id, '_og_image_fallback_url', esc_url_raw( $image_url ) );
|
|
return esc_url_raw( $image_url );
|
|
}
|
|
|
|
if ( in_array( $extension, array( 'webp', 'avif', 'gif', 'bmp', 'svg', 'tiff', 'tif' ), true ) ) {
|
|
$alternative = $this->find_compatible_alternative( $image_url );
|
|
|
|
if ( ! empty( $alternative ) ) {
|
|
update_term_meta( $term_id, '_og_image_fallback_url', esc_url_raw( $alternative ) );
|
|
return esc_url_raw( $alternative );
|
|
}
|
|
}
|
|
|
|
return esc_url_raw( $image_url );
|
|
}
|
|
|
|
/**
|
|
* Clear cached fallback URL for a taxonomy term.
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param int $term_id Term ID.
|
|
* @return void
|
|
*/
|
|
public function clear_taxonomy_cache( int $term_id ): void {
|
|
delete_term_meta( $term_id, '_og_image_fallback_url' );
|
|
}
|
|
|
|
/**
|
|
* Validate if a string is a valid URL.
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param string $url URL to validate.
|
|
* @return bool True if valid URL.
|
|
*/
|
|
private function is_valid_url( string $url ): bool {
|
|
return false !== filter_var( $url, FILTER_VALIDATE_URL );
|
|
}
|
|
|
|
/**
|
|
* Log a resolution event if logging is enabled.
|
|
*
|
|
* Uses the `robotstxt_og_enable_logging` filter to toggle logging.
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param string $event Event name (e.g., 'cache_hit', 'head_request_error').
|
|
* @param array<string, mixed> $context Additional context data.
|
|
* @return void
|
|
*/
|
|
private function log( string $event, array $context = array() ): void {
|
|
/**
|
|
* Filter whether to enable debug logging for image resolution.
|
|
*
|
|
* @since 1.0.0
|
|
*
|
|
* @param bool $enabled Whether logging is enabled. Default false.
|
|
*/
|
|
if ( ! apply_filters( 'robotstxt_og_enable_logging', false ) ) {
|
|
return;
|
|
}
|
|
|
|
$message = sprintf(
|
|
'[robotstxt-og] %s | %s',
|
|
$event,
|
|
wp_json_encode( $context )
|
|
);
|
|
|
|
// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
|
|
error_log( $message );
|
|
}
|
|
}
|