register_handler( $id, $regex, $callback, $priority );
}
/**
* Unregisters a previously-registered embed handler.
*
* @since 2.9.0
*
* @global WP_Embed $wp_embed
*
* @param string $id The handler ID that should be removed.
* @param int $priority Optional. The priority of the handler to be removed. Default 10.
*/
function wp_embed_unregister_handler( $id, $priority = 10 ) {
global $wp_embed;
$wp_embed->unregister_handler( $id, $priority );
}
/**
* Creates default array of embed parameters.
*
* The width defaults to the content width as specified by the theme. If the
* theme does not specify a content width, then 500px is used.
*
* The default height is 1.5 times the width, or 1000px, whichever is smaller.
*
* The 'embed_defaults' filter can be used to adjust either of these values.
*
* @since 2.9.0
*
* @global int $content_width
*
* @param string $url Optional. The URL that should be embedded. Default empty.
*
* @return array Default embed parameters.
*/
function wp_embed_defaults( $url = '' ) {
if ( ! empty( $GLOBALS['content_width'] ) )
$width = (int) $GLOBALS['content_width'];
if ( empty( $width ) )
$width = 500;
$height = min( ceil( $width * 1.5 ), 1000 );
/**
* Filter the default array of embed dimensions.
*
* @since 2.9.0
*
* @param array $size An array of embed width and height values
* in pixels (in that order).
* @param string $url The URL that should be embedded.
*/
return apply_filters( 'embed_defaults', compact( 'width', 'height' ), $url );
}
/**
* Attempts to fetch the embed HTML for a provided URL using oEmbed.
*
* @since 2.9.0
*
* @see WP_oEmbed
*
* @param string $url The URL that should be embedded.
* @param array $args Optional. Additional arguments and parameters for retrieving embed HTML.
* Default empty.
* @return false|string False on failure or the embed HTML on success.
*/
function wp_oembed_get( $url, $args = '' ) {
require_once( ABSPATH . WPINC . '/class-oembed.php' );
$oembed = _wp_oembed_get_object();
return $oembed->get_html( $url, $args );
}
/**
* Adds a URL format and oEmbed provider URL pair.
*
* @since 2.9.0
*
* @see WP_oEmbed
*
* @param string $format The format of URL that this provider can handle. You can use asterisks
* as wildcards.
* @param string $provider The URL to the oEmbed provider.
* @param boolean $regex Optional. Whether the `$format` parameter is in a RegEx format. Default false.
*/
function wp_oembed_add_provider( $format, $provider, $regex = false ) {
require_once( ABSPATH . WPINC . '/class-oembed.php' );
if ( did_action( 'plugins_loaded' ) ) {
$oembed = _wp_oembed_get_object();
$oembed->providers[$format] = array( $provider, $regex );
} else {
WP_oEmbed::_add_provider_early( $format, $provider, $regex );
}
}
/**
* Removes an oEmbed provider.
*
* @since 3.5.0
*
* @see WP_oEmbed
*
* @param string $format The URL format for the oEmbed provider to remove.
* @return bool Was the provider removed successfully?
*/
function wp_oembed_remove_provider( $format ) {
require_once( ABSPATH . WPINC . '/class-oembed.php' );
if ( did_action( 'plugins_loaded' ) ) {
$oembed = _wp_oembed_get_object();
if ( isset( $oembed->providers[ $format ] ) ) {
unset( $oembed->providers[ $format ] );
return true;
}
} else {
WP_oEmbed::_remove_provider_early( $format );
}
return false;
}
/**
* Determines if default embed handlers should be loaded.
*
* Checks to make sure that the embeds library hasn't already been loaded. If
* it hasn't, then it will load the embeds library.
*
* @since 2.9.0
*
* @see wp_embed_register_handler()
*/
function wp_maybe_load_embeds() {
/**
* Filter whether to load the default embed handlers.
*
* Returning a falsey value will prevent loading the default embed handlers.
*
* @since 2.9.0
*
* @param bool $maybe_load_embeds Whether to load the embeds library. Default true.
*/
if ( ! apply_filters( 'load_default_embeds', true ) ) {
return;
}
wp_embed_register_handler( 'youtube_embed_url', '#https?://(www.)?youtube\.com/(?:v|embed)/([^/]+)#i', 'wp_embed_handler_youtube' );
wp_embed_register_handler( 'googlevideo', '#http://video\.google\.([A-Za-z.]{2,5})/videoplay\?docid=([\d-]+)(.*?)#i', 'wp_embed_handler_googlevideo' );
/**
* Filter the audio embed handler callback.
*
* @since 3.6.0
*
* @param callable $handler Audio embed handler callback function.
*/
wp_embed_register_handler( 'audio', '#^https?://.+?\.(' . join( '|', wp_get_audio_extensions() ) . ')$#i', apply_filters( 'wp_audio_embed_handler', 'wp_embed_handler_audio' ), 9999 );
/**
* Filter the video embed handler callback.
*
* @since 3.6.0
*
* @param callable $handler Video embed handler callback function.
*/
wp_embed_register_handler( 'video', '#^https?://.+?\.(' . join( '|', wp_get_video_extensions() ) . ')$#i', apply_filters( 'wp_video_embed_handler', 'wp_embed_handler_video' ), 9999 );
}
/**
* The Google Video embed handler callback.
*
* Google Video does not support oEmbed.
*
* @see WP_Embed::register_handler()
* @see WP_Embed::shortcode()
*
* @param array $matches The RegEx matches from the provided regex when calling wp_embed_register_handler().
* @param array $attr Embed attributes.
* @param string $url The original URL that was matched by the regex.
* @param array $rawattr The original unmodified attributes.
* @return string The embed HTML.
*/
function wp_embed_handler_googlevideo( $matches, $attr, $url, $rawattr ) {
// If the user supplied a fixed width AND height, use it
if ( !empty($rawattr['width']) && !empty($rawattr['height']) ) {
$width = (int) $rawattr['width'];
$height = (int) $rawattr['height'];
} else {
list( $width, $height ) = wp_expand_dimensions( 425, 344, $attr['width'], $attr['height'] );
}
/**
* Filter the Google Video embed output.
*
* @since 2.9.0
*
* @param string $html Google Video HTML embed markup.
* @param array $matches The RegEx matches from the provided regex.
* @param array $attr An array of embed attributes.
* @param string $url The original URL that was matched by the regex.
* @param array $rawattr The original unmodified attributes.
*/
return apply_filters( 'embed_googlevideo', '', $matches, $attr, $url, $rawattr );
}
/**
* YouTube iframe embed handler callback.
*
* Catches YouTube iframe embed URLs that are not parsable by oEmbed but can be translated into a URL that is.
*
* @since 4.0.0
*
* @global WP_Embed $wp_embed
*
* @param array $matches The RegEx matches from the provided regex when calling
* wp_embed_register_handler().
* @param array $attr Embed attributes.
* @param string $url The original URL that was matched by the regex.
* @param array $rawattr The original unmodified attributes.
* @return string The embed HTML.
*/
function wp_embed_handler_youtube( $matches, $attr, $url, $rawattr ) {
global $wp_embed;
$embed = $wp_embed->autoembed( "https://youtube.com/watch?v={$matches[2]}" );
/**
* Filter the YoutTube embed output.
*
* @since 4.0.0
*
* @see wp_embed_handler_youtube()
*
* @param string $embed YouTube embed output.
* @param array $attr An array of embed attributes.
* @param string $url The original URL that was matched by the regex.
* @param array $rawattr The original unmodified attributes.
*/
return apply_filters( 'wp_embed_handler_youtube', $embed, $attr, $url, $rawattr );
}
/**
* Audio embed handler callback.
*
* @since 3.6.0
*
* @param array $matches The RegEx matches from the provided regex when calling wp_embed_register_handler().
* @param array $attr Embed attributes.
* @param string $url The original URL that was matched by the regex.
* @param array $rawattr The original unmodified attributes.
* @return string The embed HTML.
*/
function wp_embed_handler_audio( $matches, $attr, $url, $rawattr ) {
$audio = sprintf( '[audio src="%s" /]', esc_url( $url ) );
/**
* Filter the audio embed output.
*
* @since 3.6.0
*
* @param string $audio Audio embed output.
* @param array $attr An array of embed attributes.
* @param string $url The original URL that was matched by the regex.
* @param array $rawattr The original unmodified attributes.
*/
return apply_filters( 'wp_embed_handler_audio', $audio, $attr, $url, $rawattr );
}
/**
* Video embed handler callback.
*
* @since 3.6.0
*
* @param array $matches The RegEx matches from the provided regex when calling wp_embed_register_handler().
* @param array $attr Embed attributes.
* @param string $url The original URL that was matched by the regex.
* @param array $rawattr The original unmodified attributes.
* @return string The embed HTML.
*/
function wp_embed_handler_video( $matches, $attr, $url, $rawattr ) {
$dimensions = '';
if ( ! empty( $rawattr['width'] ) && ! empty( $rawattr['height'] ) ) {
$dimensions .= sprintf( 'width="%d" ', (int) $rawattr['width'] );
$dimensions .= sprintf( 'height="%d" ', (int) $rawattr['height'] );
}
$video = sprintf( '[video %s src="%s" /]', $dimensions, esc_url( $url ) );
/**
* Filter the video embed output.
*
* @since 3.6.0
*
* @param string $video Video embed output.
* @param array $attr An array of embed attributes.
* @param string $url The original URL that was matched by the regex.
* @param array $rawattr The original unmodified attributes.
*/
return apply_filters( 'wp_embed_handler_video', $video, $attr, $url, $rawattr );
}
/**
* Registers the oEmbed REST API route.
*
* @since 4.4.0
*/
function wp_oembed_register_route() {
$controller = new WP_oEmbed_Controller();
$controller->register_routes();
}
/**
* Adds oEmbed discovery links in the website .
*
* @since 4.4.0
*/
function wp_oembed_add_discovery_links() {
$output = '';
if ( is_singular() && ! is_front_page() ) {
$output .= '' . "\n";
if ( class_exists( 'SimpleXMLElement' ) ) {
$output .= '' . "\n";
}
}
/**
* Filter the oEmbed discovery links HTML.
*
* @since 4.4.0
*
* @param string $output HTML of the discovery links.
*/
echo apply_filters( 'oembed_discovery_links', $output );
}
/**
* Adds the necessary JavaScript to communicate with the embedded iframes.
*
* @since 4.4.0
*/
function wp_oembed_add_host_js() {
wp_enqueue_script( 'wp-embed' );
}
/**
* Retrieves the URL to embed a specific post in an iframe.
*
* @since 4.4.0
*
* @param int|WP_Post $post Optional. Post ID or object. Defaults to the current post.
* @return string|false The post embed URL on success, false if the post doesn't exist.
*/
function get_post_embed_url( $post = null ) {
$post = get_post( $post );
if ( ! $post ) {
return false;
}
if ( get_option( 'permalink_structure' ) ) {
$embed_url = trailingslashit( get_permalink( $post ) ) . user_trailingslashit( 'embed' );
} else {
$embed_url = add_query_arg( array( 'embed' => 'true' ), get_permalink( $post ) );
}
/**
* Filter the URL to embed a specific post.
*
* @since 4.4.0
*
* @param string $embed_url The post embed URL.
* @param WP_Post $post The corresponding post object.
*/
return esc_url_raw( apply_filters( 'post_embed_url', $embed_url, $post ) );
}
/**
* Retrieves the oEmbed endpoint URL for a given permalink.
*
* Pass an empty string as the first argument to get the endpoint base URL.
*
* @since 4.4.0
*
* @param string $permalink Optional. The permalink used for the `url` query arg. Default empty.
* @param string $format Optional. The requested response format. Default 'json'.
* @return string The oEmbed endpoint URL.
*/
function get_oembed_endpoint_url( $permalink = '', $format = 'json' ) {
$url = rest_url( 'oembed/1.0/embed' );
if ( 'json' === $format ) {
$format = false;
}
if ( '' !== $permalink ) {
$url = add_query_arg( array(
'url' => urlencode( $permalink ),
'format' => $format,
), $url );
}
/**
* Filter the oEmbed endpoint URL.
*
* @since 4.4.0
*
* @param string $url The URL to the oEmbed endpoint.
* @param string $permalink The permalink used for the `url` query arg.
* @param string $format The requested response format.
*/
return apply_filters( 'oembed_endpoint_url', $url, $permalink, $format );
}
/**
* Retrieves the embed code for a specific post.
*
* @since 4.4.0
*
* @param int $width The width for the response.
* @param int $height The height for the response.
* @param int|WP_Post $post Optional. Post ID or object. Default is global `$post`.
* @return string|false Embed code on success, false if post doesn't exist.
*/
function get_post_embed_html( $width, $height, $post = null ) {
$post = get_post( $post );
if ( ! $post ) {
return false;
}
$embed_url = get_post_embed_url( $post );
$output = '
\n";
$output .= "";
$output .= sprintf(
'',
esc_url( $embed_url ),
absint( $width ),
absint( $height ),
esc_attr__( 'Embedded WordPress Post' )
);
/**
* Filter the embed HTML output for a given post.
*
* @since 4.4.0
*
* @param string $output The default HTML.
* @param WP_Post $post Current post object.
* @param int $width Width of the response.
* @param int $height Height of the response.
*/
return apply_filters( 'embed_html', $output, $post, $width, $height );
}
/**
* Retrieves the oEmbed response data for a given post.
*
* @since 4.4.0
*
* @param WP_Post|int $post Post object or ID.
* @param int $width The requested width.
* @return array|false Response data on success, false if post doesn't exist.
*/
function get_oembed_response_data( $post, $width ) {
$post = get_post( $post );
if ( ! $post ) {
return false;
}
if ( 'publish' !== get_post_status( $post ) ) {
return false;
}
/**
* Filter the allowed minimum and maximum widths for the oEmbed response.
*
* @since 4.4.0
*
* @param array $min_max_width {
* Minimum and maximum widths for the oEmbed response.
*
* @type int $min Minimum width. Default 200.
* @type int $max Maximum width. Default 600.
* }
*/
$min_max_width = apply_filters( 'oembed_min_max_width', array(
'min' => 200,
'max' => 600
) );
$width = min( max( $min_max_width['min'], $width ), $min_max_width['max'] );
$height = max( ceil( $width / 16 * 9 ), 200 );
$data = array(
'version' => '1.0',
'provider_name' => get_bloginfo( 'name' ),
'provider_url' => get_home_url(),
'author_name' => get_bloginfo( 'name' ),
'author_url' => get_home_url(),
'title' => $post->post_title,
'type' => 'link',
);
$author = get_userdata( $post->post_author );
if ( $author ) {
$data['author_name'] = $author->display_name;
$data['author_url'] = get_author_posts_url( $author->ID );
}
/**
* Filter the oEmbed response data.
*
* @since 4.4.0
*
* @param array $data The response data.
* @param WP_Post $post The post object.
* @param int $width The requested width.
* @param int $height The calculated height.
*/
return apply_filters( 'oembed_response_data', $data, $post, $width, $height );
}
/**
* Filters the oEmbed response data to return an iframe embed code.
*
* @since 4.4.0
*
* @param array $data The response data.
* @param WP_Post $post The post object.
* @param int $width The requested width.
* @param int $height The calculated height.
* @return array The modified response data.
*/
function get_oembed_response_data_rich( $data, $post, $width, $height ) {
$data['width'] = absint( $width );
$data['height'] = absint( $height );
$data['type'] = 'rich';
$data['html'] = get_post_embed_html( $width, $height, $post );
// Add post thumbnail to response if available.
$thumbnail_id = false;
if ( has_post_thumbnail( $post->ID ) ) {
$thumbnail_id = get_post_thumbnail_id( $post->ID );
}
if ( 'attachment' === get_post_type( $post ) ) {
if ( wp_attachment_is_image( $post ) ) {
$thumbnail_id = $post->ID;
} else if ( wp_attachment_is( 'video', $post ) ) {
$thumbnail_id = get_post_thumbnail_id( $post );
$data['type'] = 'video';
}
}
if ( $thumbnail_id ) {
list( $thumbnail_url, $thumbnail_width, $thumbnail_height ) = wp_get_attachment_image_src( $thumbnail_id, array( $width, 99999 ) );
$data['thumbnail_url'] = $thumbnail_url;
$data['thumbnail_width'] = $thumbnail_width;
$data['thumbnail_height'] = $thumbnail_height;
}
return $data;
}
/**
* Ensures that the specified format is either 'json' or 'xml'.
*
* @since 4.4.0
*
* @param string $format The oEmbed response format. Accepts 'json' or 'xml'.
* @return string The format, either 'xml' or 'json'. Default 'json'.
*/
function wp_oembed_ensure_format( $format ) {
if ( ! in_array( $format, array( 'json', 'xml' ), true ) ) {
return 'json';
}
return $format;
}
/**
* Hooks into the REST API output to print XML instead of JSON.
*
* This is only done for the oEmbed API endpoint,
* which supports both formats.
*
* @access private
* @since 4.4.0
*
* @param bool $served Whether the request has already been served.
* @param WP_HTTP_ResponseInterface $result Result to send to the client. Usually a WP_REST_Response.
* @param WP_REST_Request $request Request used to generate the response.
* @param WP_REST_Server $server Server instance.
* @return true
*/
function _oembed_rest_pre_serve_request( $served, $result, $request, $server ) {
$params = $request->get_params();
if ( '/oembed/1.0/embed' !== $request->get_route() || 'GET' !== $request->get_method() ) {
return $served;
}
if ( ! isset( $params['format'] ) || 'xml' !== $params['format'] ) {
return $served;
}
// Embed links inside the request.
$data = $server->response_to_data( $result, false );
if ( ! class_exists( 'SimpleXMLElement' ) ) {
status_header( 501 );
die( get_status_header_desc( 501 ) );
}
$result = _oembed_create_xml( $data );
// Bail if there's no XML.
if ( ! $result ) {
status_header( 501 );
return get_status_header_desc( 501 );
}
if ( ! headers_sent() ) {
$server->send_header( 'Content-Type', 'text/xml; charset=' . get_option( 'blog_charset' ) );
}
echo $result;
return true;
}
/**
* Creates an XML string from a given array.
*
* @since 4.4.0
* @access private
*
* @param array $data The original oEmbed response data.
* @param SimpleXMLElement $node Optional. XML node to append the result to recursively.
* @return string|false XML string on success, false on error.
*/
function _oembed_create_xml( $data, $node = null ) {
if ( ! is_array( $data ) || empty( $data ) ) {
return false;
}
if ( null === $node ) {
$node = new SimpleXMLElement( '' );
}
foreach ( $data as $key => $value ) {
if ( is_numeric( $key ) ) {
$key = 'oembed';
}
if ( is_array( $value ) ) {
$item = $node->addChild( $key );
_oembed_create_xml( $value, $item );
} else {
$node->addChild( $key, esc_html( $value ) );
}
}
return $node->asXML();
}
/**
* Filters the given oEmbed HTML.
*
* If the `$url` isn't on the trusted providers list,
* we need to filter the HTML heavily for security.
*
* Only filters 'rich' and 'html' response types.
*
* @since 4.4.0
*
* @param string $result The oEmbed HTML result.
* @param object $data A data object result from an oEmbed provider.
* @param string $url The URL of the content to be embedded.
* @return string The filtered and sanitized oEmbed result.
*/
function wp_filter_oembed_result( $result, $data, $url ) {
if ( false === $result || ! in_array( $data->type, array( 'rich', 'video' ) ) ) {
return $result;
}
require_once( ABSPATH . WPINC . '/class-oembed.php' );
$wp_oembed = _wp_oembed_get_object();
// Don't modify the HTML for trusted providers.
if ( false !== $wp_oembed->get_provider( $url, array( 'discover' => false ) ) ) {
return $result;
}
$allowed_html = array(
'a' => array(
'href' => true,
),
'blockquote' => array(),
'iframe' => array(
'src' => true,
'width' => true,
'height' => true,
'frameborder' => true,
'marginwidth' => true,
'marginheight' => true,
'scrolling' => true,
'title' => true,
),
);
$html = wp_kses( $result, $allowed_html );
preg_match( '|(
.*?
)?.*()|ms', $html, $content );
// We require at least the iframe to exist.
if ( empty( $content[2] ) ) {
return false;
}
$html = $content[1] . $content[2];
if ( ! empty( $content[1] ) ) {
// We have a blockquote to fall back on. Hide the iframe by default.
$html = str_replace( '%2$s',
esc_url( get_permalink() ),
/* translators: %s: Name of current post */
sprintf( __( 'Continue reading %s' ), '' . get_the_title() . '' )
);
return ' … ' . $link;
}
/**
* Displays the post excerpt for the embed template.
*
* Intended to be used in 'The Loop'.
*
* @since 4.4.0
*/
function the_excerpt_embed() {
$output = get_the_excerpt();
/**
* Filter the post excerpt for the embed template.
*
* @since 4.4.0
*
* @param string $output The current post excerpt.
*/
echo apply_filters( 'the_excerpt_embed', $output );
}
/**
* Filters the post excerpt for the embed template.
*
* Shows players for video and audio attachments.
*
* @since 4.4.0
*
* @param string $content The current post excerpt.
* @return string The modified post excerpt.
*/
function wp_embed_excerpt_attachment( $content ) {
if ( is_attachment() ) {
return prepend_attachment( '' );
}
return $content;
}
/**
* Enqueue embed iframe default CSS and JS & fire do_action('enqueue_embed_scripts')
*
* Enqueue PNG fallback CSS for embed iframe for legacy versions of IE.
*
* Allows plugins to queue scripts for the embed iframe end using wp_enqueue_script().
* Runs first in oembed_head().
*
* @since 4.4.0
*/
function enqueue_embed_scripts() {
wp_enqueue_style( 'open-sans' );
wp_enqueue_style( 'wp-embed-template-ie' );
/**
* Fires when scripts and styles are enqueued for the embed iframe.
*
* @since 4.4.0
*/
do_action( 'enqueue_embed_scripts' );
}
/**
* Prints the CSS in the embed iframe header.
*
* @since 4.4.0
*/
function print_embed_styles() {
?>