[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/ -> embed.php (summary)

oEmbed API: Top-level oEmbed functionality

File Size: 1250 lines (38 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 38 functions

  wp_embed_register_handler()
  wp_embed_unregister_handler()
  wp_embed_defaults()
  wp_oembed_get()
  _wp_oembed_get_object()
  wp_oembed_add_provider()
  wp_oembed_remove_provider()
  wp_maybe_load_embeds()
  wp_embed_handler_youtube()
  wp_embed_handler_audio()
  wp_embed_handler_video()
  wp_oembed_register_route()
  wp_oembed_add_discovery_links()
  wp_oembed_add_host_js()
  wp_maybe_enqueue_oembed_host_js()
  get_post_embed_url()
  get_oembed_endpoint_url()
  get_post_embed_html()
  get_oembed_response_data()
  get_oembed_response_data_for_url()
  get_oembed_response_data_rich()
  wp_oembed_ensure_format()
  _oembed_rest_pre_serve_request()
  _oembed_create_xml()
  wp_filter_oembed_iframe_title_attribute()
  wp_filter_oembed_result()
  wp_embed_excerpt_more()
  the_excerpt_embed()
  wp_embed_excerpt_attachment()
  enqueue_embed_scripts()
  wp_enqueue_embed_styles()
  print_embed_scripts()
  _oembed_filter_feed_content()
  print_embed_comments_button()
  print_embed_sharing_button()
  print_embed_sharing_dialog()
  the_embed_site_title()
  wp_filter_pre_oembed_result()

Functions
Functions that are not part of a class:

wp_embed_register_handler( $id, $regex, $callback, $priority = 10 )   X-Ref
Registers an embed handler.

Should probably only be used for sites that do not support oEmbed.

param: string   $id       An internal ID/name for the handler. Needs to be unique.
param: string   $regex    The regex that will be used to see if this handler should be used for a URL.
param: callable $callback The callback function that will be called if the regex is matched.
param: int      $priority Optional. Used to specify the order in which the registered handlers will

wp_embed_unregister_handler( $id, $priority = 10 )   X-Ref
Unregisters a previously-registered embed handler.

param: string $id       The handler ID that should be removed.
param: int    $priority Optional. The priority of the handler to be removed. Default 10.

wp_embed_defaults( $url = '' )   X-Ref
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 {@see 'embed_defaults'} filter can be used to adjust either of these values.

param: string $url Optional. The URL that should be embedded. Default empty.
return: int[] {

wp_oembed_get( $url, $args = '' )   X-Ref
Attempts to fetch the embed HTML for a provided URL using oEmbed.

param: string $url  The URL that should be embedded.
param: array|string $args {
return: string|false The embed HTML on success, false on failure.

_wp_oembed_get_object()   X-Ref
Returns the initialized WP_oEmbed object.

return: WP_oEmbed object.

wp_oembed_add_provider( $format, $provider, $regex = false )   X-Ref
Adds a URL format and oEmbed provider URL pair.

param: string $format   The format of URL that this provider can handle. You can use asterisks
param: string $provider The URL to the oEmbed provider.
param: bool   $regex    Optional. Whether the `$format` parameter is in a RegEx format. Default false.

wp_oembed_remove_provider( $format )   X-Ref
Removes an oEmbed provider.

param: string $format The URL format for the oEmbed provider to remove.
return: bool Was the provider removed successfully?

wp_maybe_load_embeds()   X-Ref
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.


wp_embed_handler_youtube( $matches, $attr, $url, $rawattr )   X-Ref
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.

param: array  $matches The RegEx matches from the provided regex when calling
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.

wp_embed_handler_audio( $matches, $attr, $url, $rawattr )   X-Ref
Audio embed handler callback.

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.

wp_embed_handler_video( $matches, $attr, $url, $rawattr )   X-Ref
Video embed handler callback.

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.

wp_oembed_register_route()   X-Ref
Registers the oEmbed REST API route.


wp_oembed_add_discovery_links()   X-Ref
Adds oEmbed discovery links in the head element of the website.


wp_oembed_add_host_js()   X-Ref
Adds the necessary JavaScript to communicate with the embedded iframes.

This function is no longer used directly. For back-compat it exists exclusively as a way to indicate that the oEmbed
host JS _should_ be added. In `default-filters.php` there remains this code:

add_action( 'wp_head', 'wp_oembed_add_host_js' )

Historically a site has been able to disable adding the oEmbed host script by doing:

remove_action( 'wp_head', 'wp_oembed_add_host_js' )

In order to ensure that such code still works as expected, this function remains. There is now a `has_action()` check
in `wp_maybe_enqueue_oembed_host_js()` to see if `wp_oembed_add_host_js()` has not been unhooked from running at the
`wp_head` action.


wp_maybe_enqueue_oembed_host_js( $html )   X-Ref
Enqueue the wp-embed script if the provided oEmbed HTML contains a post embed.

In order to only enqueue the wp-embed script on pages that actually contain post embeds, this function checks if the
provided HTML contains post embed markup and if so enqueues the script so that it will get printed in the footer.

param: string $html Embed markup.
return: string Embed markup (without modifications).

get_post_embed_url( $post = null )   X-Ref
Retrieves the URL to embed a specific post in an iframe.

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.

get_oembed_endpoint_url( $permalink = '', $format = 'json' )   X-Ref
Retrieves the oEmbed endpoint URL for a given permalink.

Pass an empty string as the first argument to get the endpoint base URL.

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.

get_post_embed_html( $width, $height, $post = null )   X-Ref
Retrieves the embed code for a specific post.

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.

get_oembed_response_data( $post, $width )   X-Ref
Retrieves the oEmbed response data for a given post.

param: WP_Post|int $post  Post ID or post object.
param: int         $width The requested width.
return: array|false Response data on success, false if post doesn't exist

get_oembed_response_data_for_url( $url, $args )   X-Ref
Retrieves the oEmbed response data for a given URL.

param: string $url  The URL that should be inspected for discovery `<link>` tags.
param: array  $args oEmbed remote get arguments.
return: object|false oEmbed response data if the URL does belong to the current site. False otherwise.

get_oembed_response_data_rich( $data, $post, $width, $height )   X-Ref
Filters the oEmbed response data to return an iframe embed code.

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.

wp_oembed_ensure_format( $format )   X-Ref
Ensures that the specified format is either 'json' or 'xml'.

param: string $format The oEmbed response format. Accepts 'json' or 'xml'.
return: string The format, either 'xml' or 'json'. Default 'json'.

_oembed_rest_pre_serve_request( $served, $result, $request, $server )   X-Ref
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.

param: bool             $served  Whether the request has already been served.
param: WP_HTTP_Response $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

_oembed_create_xml( $data, $node = null )   X-Ref
Creates an XML string from a given array.

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.

wp_filter_oembed_iframe_title_attribute( $result, $data, $url )   X-Ref
Filters the given oEmbed HTML to make sure iframes have a title attribute.

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 oEmbed result.

wp_filter_oembed_result( $result, $data, $url )   X-Ref
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 'video' response types.

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.

wp_embed_excerpt_more( $more_string )   X-Ref
Filters the string in the 'more' link displayed after a trimmed excerpt.

Replaces '[...]' (appended to automatically generated excerpts) with an
ellipsis and a "Continue reading" link in the embed template.

param: string $more_string Default 'more' string.
return: string 'Continue reading' link prepended with an ellipsis.

the_excerpt_embed()   X-Ref
Displays the post excerpt for the embed template.

Intended to be used in 'The Loop'.


wp_embed_excerpt_attachment( $content )   X-Ref
Filters the post excerpt for the embed template.

Shows players for video and audio attachments.

param: string $content The current post excerpt.
return: string The modified post excerpt.

enqueue_embed_scripts()   X-Ref
Enqueues embed iframe default CSS and JS.

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().


wp_enqueue_embed_styles()   X-Ref
Enqueues the CSS in the embed iframe header.


print_embed_scripts()   X-Ref
Prints the JavaScript in the embed iframe header.


_oembed_filter_feed_content( $content )   X-Ref
Prepare the oembed HTML to be displayed in an RSS feed.

param: string $content The content to filter.
return: string The filtered content.

print_embed_comments_button()   X-Ref
Prints the necessary markup for the embed comments button.


print_embed_sharing_button()   X-Ref
Prints the necessary markup for the embed sharing button.


print_embed_sharing_dialog()   X-Ref
Prints the necessary markup for the embed sharing dialog.


the_embed_site_title()   X-Ref
Prints the necessary markup for the site title in an embed template.


wp_filter_pre_oembed_result( $result, $url, $args )   X-Ref
Filters the oEmbed result before any HTTP requests are made.

If the URL belongs to the current site, the result is fetched directly instead of
going through the oEmbed discovery process.

param: null|string $result The UNSANITIZED (and potentially unsafe) HTML that should be used to embed. Default null.
param: string      $url    The URL that should be inspected for discovery `<link>` tags.
param: array       $args   oEmbed remote get arguments.
return: null|string The UNSANITIZED (and potentially unsafe) HTML that should be used to embed.



Generated : Mon Mar 18 08:20:01 2024 Cross-referenced by PHPXref