Using WordPress ‘pre_oembed_result’ PHP filter

by

The ‘pre_oembed_result’ filter allows you to modify or short-circuit the oEmbed result before making any HTTP requests. This is useful for optimizing your setup or altering the default logic.

Usage

add_filter( 'pre_oembed_result', 'my_custom_oembed_function', 10, 3 );

function my_custom_oembed_function( $result, $url, $args ) {
  // Your custom logic here
  return $result;
}

Parameters

  • $result null|string
    • The UNSANITIZED (and potentially unsafe) HTML to be used for embedding
    • Default: null (continue retrieving the result)
  • $url string
    • The URL of the content to be embedded
  • $args string|array
    • Additional arguments for retrieving embed HTML
    • See wp_oembed_get() for accepted arguments
    • Default: empty

Examples

Using a Custom Video Player

Scenario: You want to use a custom video player for YouTube videos.

add_filter( 'pre_oembed_result', 'use_custom_youtube_player', 10, 3 );

function use_custom_youtube_player( $result, $url, $args ) {
  if ( strpos( $url, 'youtube.com' ) !== false ) {
    // Custom YouTube player code here
  }

  return $result;
}

This code checks if the $url is a YouTube video and, if so, applies a custom video player.

Blocking External Embeds

Scenario: You want to block any external content from being embedded.

add_filter( 'pre_oembed_result', 'block_external_embeds', 10, 3 );

function block_external_embeds( $result, $url, $args ) {
  return null;
}

This code blocks all external content from being embedded by returning null.

Limiting Width and Height of Embedded Content

Scenario: You want to limit the width and height of all embedded content.

add_filter( 'pre_oembed_result', 'limit_embed_size', 10, 3 );

function limit_embed_size( $result, $url, $args ) {
  $args['width'] = 600;
  $args['height'] = 400;
  return wp_oembed_get( $url, $args );
}

This code limits the width to 600px and height to 400px for all embedded content.

Replacing Vimeo with YouTube

Scenario: You want to replace all Vimeo video URLs with corresponding YouTube URLs.

add_filter( 'pre_oembed_result', 'replace_vimeo_with_youtube', 10, 3 );

function replace_vimeo_with_youtube( $result, $url, $args ) {
  if ( strpos( $url, 'vimeo.com' ) !== false ) {
    $youtube_url = str_replace( 'vimeo.com', 'youtube.com', $url );
    return wp_oembed_get( $youtube_url, $args );
  }
  return $result;
}

This code replaces all Vimeo video URLs with YouTube URLs before embedding.

Caching Embed Results

Scenario: You want to cache the oEmbed results to improve performance.

add_filter( 'pre_oembed_result', 'cache_oembed_results', 10, 3 );

function cache_oembed_results( $result, $url, $args ) {
$cache_key = 'oembed_cache_' . md5( $url ); $cached_result = get_transient( $cache_key );
if ( $cached_result ) {
return $cached_result;
} else {
$oembed_result = wp_oembed_get( $url, $args );
set_transient( $cache_key, $oembed_result, 2 * HOUR_IN_SECONDS );
return $oembed_result;
}
}

This code caches the oEmbed results for two hours, improving performance by reducing the number of HTTP requests made for the same content. When the cache expires, a new request will be made and the result will be cached again.