API Documentation
Back to top  

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

package WordPress
subpackage Embed
since 2.9.0

 Methods

Constructor

__construct() 

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

autoembed(string $content) : string
see

Parameters

$content

string

The content to be searched.

Returns

stringPotentially modified $content.

Callback function for WP_Embed::autoembed().

autoembed_callback(array $match) : string

Parameters

$match

array

A regex match array.

Returns

stringThe embed HTML on success, otherwise the original URL.

Triggers a caching of all oEmbed results.

cache_oembed(integer $post_ID) 

Parameters

$post_ID

integer

Post ID to do the caching for.

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

delete_oembed_caches(integer $post_ID) 

Parameters

$post_ID

integer

Post ID to delete the caches for.

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

find_oembed_post_id(string $cache_key) : integer | null
since 4.9.0

Parameters

$cache_key

string

oEmbed cache key.

Returns

integernullPost ID on success, null on failure.

Conditionally makes a hyperlink based on an internal class variable.

maybe_make_link(string $url) : false | string

Parameters

$url

string

URL to potentially be linked.

Returns

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

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

maybe_run_ajax_cache() 

Registers an embed handler.

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

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.

Parameters

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

Process the [embed] shortcode.

run_shortcode(string $content) : string

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.

global array $shortcode_tags

Parameters

$content

string

Content to parse

Returns

stringContent with shortcode parsed

The do_shortcode() callback function.

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

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.

Parameters

$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

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

Unregisters a previously-registered embed handler.

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

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

Parameters

$id

string

The handler ID that should be removed.

$priority

integer

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

 Properties

 

$handlers

$handlers 

Default

array()
 

$last_attr

$last_attr 

Default

array()
 

$last_url

$last_url 

Default

''
 

$linkifunknown

$linkifunknown 

Default

true
 

$post_ID

$post_ID 

Default

 

When a URL cannot be embedded, return false instead of returning a link or the URL.

$return_false_on_fail : boolean

Default

false

Bypasses the \'embed_maybe_make_link' filter.

 

$usecache

$usecache 

Default

true