[ 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: 1257 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.

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

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

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

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

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

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.

return: string The embed HTML.
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.

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

return: string The embed HTML.
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.

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

return: string The embed HTML.
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.

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.

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

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

return: string|false The post embed URL on success, false if the post doesn't exist.
param: int|WP_Post $post Optional. Post ID or object. Defaults to the current post.

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.

return: string The oEmbed endpoint 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'.

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

return: string|false Embed code on success, false if post doesn't exist.
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`.

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

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

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

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

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

return: array The modified response data.
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.

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

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

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

return: true
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.

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

return: string|false XML string on success, false on error.
param: array            $data The original oEmbed response data.
param: SimpleXMLElement $node Optional. XML node to append the result to recursively.

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

return: string The filtered oEmbed result.
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.

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.

return: string The filtered and sanitized oEmbed result.
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.

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.

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

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.

return: string The modified post excerpt.
param: string $content The current 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.

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

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.

return: null|string The UNSANITIZED (and potentially unsafe) HTML that should be used to embed.
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.



Generated : Tue Dec 3 08:20:01 2024 Cross-referenced by PHPXref