Core functions for embedding content and managing oEmbed providers.

Source: wp-includes/embed.php

Handler Registration

wp_embed_register_handler()

Registers a custom embed handler for URLs that don’t support oEmbed.

wp_embed_register_handler( 
    string $id, 
    string $regex, 
    callable $callback, 
    int $priority = 10 
): void

Parameters:

• $id – Unique handler identifier
• $regex – Pattern to match URLs
• $callback – Function receiving ( $matches, $attr, $url, $rawattr )
• $priority – Lower runs first (default 10)

Example:

wp_embed_register_handler(
    'custom_video',
    '#https?://customvideo.com/v/([a-z0-9]+)#i',
    function( $matches, $attr, $url, $rawattr ) {
        return '<iframe src="https://customvideo.com/embed/' . 
               esc_attr( $matches[1] ) . '"></iframe>';
    }
);

wp_embed_unregister_handler()

Removes a previously registered embed handler.

wp_embed_unregister_handler( string $id, int $priority = 10 ): void

Provider Management

wp_oembed_add_provider()

Adds an oEmbed provider URL pattern.

wp_oembed_add_provider( 
    string $format, 
    string $provider, 
    bool $regex = false 
): void

Parameters:

• $format – URL pattern (wildcards * or regex if $regex is true)
• $provider – oEmbed endpoint URL
• $regex – Whether $format is a regex pattern

Examples:

// Wildcard format
wp_oembed_add_provider(
    'https://example.com/video/*',
    'https://example.com/oembed'
);

// Regex format
wp_oembed_add_provider(
    '#https?://example.com/(video|audio)/d+#i',
    'https://example.com/oembed',
    true
);

wp_oembed_remove_provider()

Removes an oEmbed provider.

wp_oembed_remove_provider( string $format ): bool

Returns: true if removed, false otherwise.

Fetching Embeds

wp_oembed_get()

Fetches embed HTML for a URL using oEmbed.

wp_oembed_get( string $url, array|string $args = '' ): string|false

Parameters:

• $url – URL to embed
• $args – Optional arguments:
  • width – Maximum width
  • height – Maximum height
  • discover – Whether to attempt discovery (default true)

Returns: HTML string or false on failure.

Example:

$html = wp_oembed_get( 
    'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
    [ 'width' => 600 ]
);

wp_embed_defaults()

Gets default embed dimensions based on theme content width.

wp_embed_defaults( string $url = '' ): array

Returns: [ 'width' => int, 'height' => int ]

Logic:

• width – Maximum width
• height – Maximum height
• discover – Whether to attempt discovery (default true)

Filterable via embed_defaults.

_wp_oembed_get_object()

Returns the singleton WP_oEmbed instance.

_wp_oembed_get_object(): WP_oEmbed

Note: Private function, use wp_oembed_get() instead.

Post Embed URLs

get_post_embed_url()

Gets the URL to view a post embedded in an iframe.

get_post_embed_url( int|WP_Post $post = null ): string|false

Returns: URL like https://example.com/post-slug/embed/

Example:

$embed_url = get_post_embed_url( 123 );
// https://example.com/my-post/embed/

get_oembed_endpoint_url()

Gets the oEmbed REST API endpoint URL.

get_oembed_endpoint_url( string $permalink = '', string $format = 'json' ): string

Parameters:

• width – Maximum width
• height – Maximum height
• discover – Whether to attempt discovery (default true)

Returns: REST endpoint URL with query params.

Example:

$endpoint = get_oembed_endpoint_url( get_permalink( 123 ) );
// https://example.com/wp-json/oembed/1.0/embed?url=...

get_post_embed_html()

Generates the full embed code (iframe + blockquote fallback).

get_post_embed_html( int $width, int $height, int|WP_Post $post = null ): string|false

Returns: Complete embed markup including:

• Width: $content_width global or 500px
• Height: min( width × 1.5, 1000 )

Example:

$embed_code = get_post_embed_html( 600, 400, $post );

oEmbed Response Data

get_oembed_response_data()

Builds oEmbed response array for a post.

get_oembed_response_data( WP_Post|int $post, int $width ): array|false

Returns: Array with oEmbed spec fields:

[
    'version'       => '1.0',
    'provider_name' => 'Site Name',
    'provider_url'  => 'https://example.com',
    'author_name'   => 'Display Name',
    'author_url'    => 'https://example.com/author/...',
    'title'         => 'Post Title',
    'type'          => 'link', // becomes 'rich' after filtering
]

Validation:

• $permalink – Post URL (empty for base endpoint)
• $format – ‘json’ or ‘xml’

get_oembed_response_data_rich()

Filter callback that adds rich embed data.

get_oembed_response_data_rich( 
    array $data, 
    WP_Post $post, 
    int $width, 
    int $height 
): array

Adds:

• <blockquote> fallback with link
• <iframe> with sandbox restrictions
• Inline JavaScript for communication

get_oembed_response_data_for_url()

Gets oEmbed data for a URL (handles multisite).

get_oembed_response_data_for_url( string $url, array $args ): object|false

Multisite handling:

• Returns false if post doesn’t exist
• Returns false if not publicly viewable
• Returns false if post type doesn’t support embeds

Format Handling

wp_oembed_ensure_format()

Validates format parameter.

wp_oembed_ensure_format( string $format ): string

Returns: ‘json’ or ‘xml’ (defaults to ‘json’).

Filtering & Security

wp_filter_oembed_result()

Sanitizes oEmbed HTML from untrusted providers.

wp_filter_oembed_result( 
    string|false $result, 
    object $data, 
    string $url 
): string|false

Security measures:

• width, height – Dimensions
• type – Changed to ‘rich’ (or ‘video’ for video attachments)
• html – Full embed markup
• thumbnail_url, thumbnail_width, thumbnail_height – If available

Note: Trusted providers (in built-in list) bypass this filter.

wp_filter_oembed_iframe_title_attribute()

Ensures iframes have title attributes for accessibility.

wp_filter_oembed_iframe_title_attribute( 
    string|false $result, 
    object $data, 
    string $url 
): string|false

wp_filter_pre_oembed_result()

Short-circuits oEmbed for local URLs.

wp_filter_pre_oembed_result( 
    null|string $result, 
    string $url, 
    array $args 
): null|string

If URL belongs to current site, fetches embed data directly instead of making HTTP request.

Embed Handlers

wp_embed_handler_youtube()

Handles YouTube embed/v URLs not parseable by standard oEmbed.

wp_embed_handler_youtube( 
    array $matches, 
    array $attr, 
    string $url, 
    array $rawattr 
): string

Converts youtube.com/embed/ID to youtube.com/watch?v=ID and processes.

wp_embed_handler_audio()