Class: WP_Embed

API for easily embedding rich media such as videos and images into content.


Properties

Name Type(s) Default Value Summary
handlers
post_ID
usecache
linkifunknown
last_attr
last_url
return_false_on_fail boolean When a URL cannot be embedded, return false instead of returning a link or the URL.

Bypasses the \'embed_maybe_make_link' filter.


Methods

WP_Embed:: __construct( )

Constructor


WP_Embed:: autoembed( string $content )

Passes any unlinked URLs that are on their own line to WP_Embed::shortcode() for potential embedding.

Arguments

Name Type(s) Default Value Description
$content string

The content to be searched.

Returns

string

Potentially modified $content.


WP_Embed:: autoembed_callback( array $match )

Callback function for WP_Embed::autoembed().

Arguments

Name Type(s) Default Value Description
$match array

A regex match array.

Returns

string

The embed HTML on success, otherwise the original URL.


WP_Embed:: cache_oembed( integer $post_ID )

Triggers a caching of all oEmbed results.

Arguments

Name Type(s) Default Value Description
$post_ID integer

Post ID to do the caching for.


WP_Embed:: delete_oembed_caches( integer $post_ID )

Delete all oEmbed caches. Unused by core as of 4.0.0.

Arguments

Name Type(s) Default Value Description
$post_ID integer

Post ID to delete the caches for.


WP_Embed:: find_oembed_post_id( string $cache_key )

Find the oEmbed cache post ID for a given cache key. Since 4.9.0.

Arguments

Name Type(s) Default Value Description
$cache_key string

oEmbed cache key.

Returns

integer | null

Post ID on success, null on failure.


Conditionally makes a hyperlink based on an internal class variable.

Arguments

Name Type(s) Default Value Description
$url string

URL to potentially be linked.

Returns

false | string

Linked URL or the original URL. False if 'return_false_on_fail' is true.


WP_Embed:: maybe_run_ajax_cache( )

If a post/page was saved, then output JavaScript to make an Ajax request that will call WP_Embed::cache_oembed().


WP_Embed:: register_handler( string $id, string $regex, callable $callback, integer $priority = 10 )

Registers an embed handler.

Do not use this function directly, use wp_embed_register_handler() instead.

This function should probably also only be used for sites that do not support oEmbed.

Arguments

Name Type(s) Default Value Description
$id string

An internal ID/name for the handler. Needs to be unique.

$regex string

The regex that will be used to see if this handler should be used for a URL.

$callback callable

The callback function that will be called if the regex is matched.

$priority integer

Optional. Used to specify the order in which the registered handlers will be tested (default: 10). Lower numbers correspond with earlier testing, and handlers with the same priority are tested in the order in which they were added to the action.


WP_Embed:: run_shortcode( string $content )

Process the [embed] shortcode.

Since the [embed] shortcode needs to be run earlier than other shortcodes, this function removes all existing shortcodes, registers the [embed] shortcode, calls do_shortcode(), and then re-registers the old shortcodes.

Arguments

Name Type(s) Default Value Description
$content string

Content to parse

Returns

string

Content with shortcode parsed


WP_Embed:: shortcode( array $attr, string $url = '' )

The do_shortcode() callback function.

Attempts to convert a URL into embed HTML. Starts by checking the URL against the regex of the registered embed handlers. If none of the regex matches and it's enabled, then the URL will be given to the WP_oEmbed class.

Arguments

Name Type(s) Default Value Description
$attr array

{ Shortcode attributes. Optional.

@type int $width  Width of the embed in pixels.
@type int $height Height of the embed in pixels.

}

$url string

The URL attempting to be embedded.

Returns

string | false

The embed HTML on success, otherwise the original URL. ->maybe_make_link() can return false on failure.


WP_Embed:: unregister_handler( string $id, integer $priority = 10 )

Unregisters a previously-registered embed handler.

Do not use this function directly, use wp_embed_unregister_handler() instead.

Arguments

Name Type(s) Default Value Description
$id string

The handler ID that should be removed.

$priority integer

Optional. The priority of the handler to be removed (default: 10).


WordPress Developer Newsletter

Stay on top of the latest WordPress API changes, developer tool updates, security alerts and more.