1<?php
2/**
3 * oEmbed API: Top-level oEmbed functionality
4 *
5 * @package WordPress
6 * @subpackage oEmbed
7 * @since 4.4.0
8 */
9
10/**
11 * Registers an embed handler.
12 *
13 * Should probably only be used for sites that do not support oEmbed.
14 *
15 * @since 2.9.0
16 *
17 * @global WP_Embed $wp_embed WordPress Embed object.
18 *
19 * @param string $id An internal ID/name for the handler. Needs to be unique.
20 * @param string $regex The regex that will be used to see if this handler should be used for a URL.
21 * @param callable $callback The callback function that will be called if the regex is matched.
22 * @param int $priority Optional. Used to specify the order in which the registered handlers will
23 * be tested. Default 10.
24 */
25function wp_embed_register_handler( $id, $regex, $callback, $priority = 10 ) {
26 global $wp_embed;
27 $wp_embed->register_handler( $id, $regex, $callback, $priority );
28}
29
30/**
31 * Unregisters a previously-registered embed handler.
32 *
33 * @since 2.9.0
34 *
35 * @global WP_Embed $wp_embed WordPress Embed object.
36 *
37 * @param string $id The handler ID that should be removed.
38 * @param int $priority Optional. The priority of the handler to be removed. Default 10.
39 */
40function wp_embed_unregister_handler( $id, $priority = 10 ) {
41 global $wp_embed;
42 $wp_embed->unregister_handler( $id, $priority );
43}
44
45/**
46 * Creates default array of embed parameters.
47 *
48 * The width defaults to the content width as specified by the theme. If the
49 * theme does not specify a content width, then 500px is used.
50 *
51 * The default height is 1.5 times the width, or 1000px, whichever is smaller.
52 *
53 * The {@see 'embed_defaults'} filter can be used to adjust either of these values.
54 *
55 * @since 2.9.0
56 *
57 * @global int $content_width
58 *
59 * @param string $url Optional. The URL that should be embedded. Default empty.
60 * @return int[] {
61 * Indexed array of the embed width and height in pixels.
62 *
63 * @type int $0 The embed width.
64 * @type int $1 The embed height.
65 * }
66 */
67function wp_embed_defaults( $url = '' ) {
68 if ( ! empty( $GLOBALS['content_width'] ) ) {
69 $width = (int) $GLOBALS['content_width'];
70 }
71
72 if ( empty( $width ) ) {
73 $width = 500;
74 }
75
76 $height = min( (int) ceil( $width * 1.5 ), 1000 );
77
78 /**
79 * Filters the default array of embed dimensions.
80 *
81 * @since 2.9.0
82 *
83 * @param int[] $size {
84 * Indexed array of the embed width and height in pixels.
85 *
86 * @type int $0 The embed width.
87 * @type int $1 The embed height.
88 * }
89 * @param string $url The URL that should be embedded.
90 */
91 return apply_filters( 'embed_defaults', compact( 'width', 'height' ), $url );
92}
93
94/**
95 * Attempts to fetch the embed HTML for a provided URL using oEmbed.
96 *
97 * @since 2.9.0
98 *
99 * @see WP_oEmbed
100 *
101 * @param string $url The URL that should be embedded.
102 * @param array|string $args {
103 * Optional. Additional arguments for retrieving embed HTML. Default empty.
104 *
105 * @type int|string $width Optional. The `maxwidth` value passed to the provider URL.
106 * @type int|string $height Optional. The `maxheight` value passed to the provider URL.
107 * @type bool $discover Optional. Determines whether to attempt to discover link tags
108 * at the given URL for an oEmbed provider when the provider URL
109 * is not found in the built-in providers list. Default true.
110 * }
111 * @return string|false The embed HTML on success, false on failure.
112 */
113function wp_oembed_get( $url, $args = '' ) {
114 $oembed = _wp_oembed_get_object();
115 return $oembed->get_html( $url, $args );
116}
117
118/**
119 * Returns the initialized WP_oEmbed object.
120 *
121 * @since 2.9.0
122 * @access private
123 *
124 * @return WP_oEmbed object.
125 */
126function _wp_oembed_get_object() {
127 static $wp_oembed = null;
128
129 if ( is_null( $wp_oembed ) ) {
130 $wp_oembed = new WP_oEmbed();
131 }
132 return $wp_oembed;
133}
134
135/**
136 * Adds a URL format and oEmbed provider URL pair.
137 *
138 * @since 2.9.0
139 *
140 * @see WP_oEmbed
141 *
142 * @param string $format The format of URL that this provider can handle. You can use asterisks
143 * as wildcards.
144 * @param string $provider The URL to the oEmbed provider.
145 * @param bool $regex Optional. Whether the `$format` parameter is in a RegEx format. Default false.
146 */
147function wp_oembed_add_provider( $format, $provider, $regex = false ) {
148 if ( did_action( 'plugins_loaded' ) ) {
149 $oembed = _wp_oembed_get_object();
150 $oembed->providers[ $format ] = array( $provider, $regex );
151 } else {
152 WP_oEmbed::_add_provider_early( $format, $provider, $regex );
153 }
154}
155
156/**
157 * Removes an oEmbed provider.
158 *
159 * @since 3.5.0
160 *
161 * @see WP_oEmbed
162 *
163 * @param string $format The URL format for the oEmbed provider to remove.
164 * @return bool Was the provider removed successfully?
165 */
166function wp_oembed_remove_provider( $format ) {
167 if ( did_action( 'plugins_loaded' ) ) {
168 $oembed = _wp_oembed_get_object();
169
170 if ( isset( $oembed->providers[ $format ] ) ) {
171 unset( $oembed->providers[ $format ] );
172 return true;
173 }
174 } else {
175 WP_oEmbed::_remove_provider_early( $format );
176 }
177
178 return false;
179}
180
181/**
182 * Determines if default embed handlers should be loaded.
183 *
184 * Checks to make sure that the embeds library hasn't already been loaded. If
185 * it hasn't, then it will load the embeds library.
186 *
187 * @since 2.9.0
188 *
189 * @see wp_embed_register_handler()
190 */
191function wp_maybe_load_embeds() {
192 /**
193 * Filters whether to load the default embed handlers.
194 *
195 * Returning a falsey value will prevent loading the default embed handlers.
196 *
197 * @since 2.9.0
198 *
199 * @param bool $maybe_load_embeds Whether to load the embeds library. Default true.
200 */
201 if ( ! apply_filters( 'load_default_embeds', true ) ) {
202 return;
203 }
204
205 wp_embed_register_handler( 'youtube_embed_url', '#https?://(www\.)?youtube\.com/(?:v|embed)/([^/]+)#i', 'wp_embed_handler_youtube' );
206
207 /**
208 * Filters the audio embed handler callback.
209 *
210 * @since 3.6.0
211 *
212 * @param callable $handler Audio embed handler callback function.
213 */
214 wp_embed_register_handler( 'audio', '#^https?://.+?\.(' . implode( '|', wp_get_audio_extensions() ) . ')$#i', apply_filters( 'wp_audio_embed_handler', 'wp_embed_handler_audio' ), 9999 );
215
216 /**
217 * Filters the video embed handler callback.
218 *
219 * @since 3.6.0
220 *
221 * @param callable $handler Video embed handler callback function.
222 */
223 wp_embed_register_handler( 'video', '#^https?://.+?\.(' . implode( '|', wp_get_video_extensions() ) . ')$#i', apply_filters( 'wp_video_embed_handler', 'wp_embed_handler_video' ), 9999 );
224}
225
226/**
227 * YouTube iframe embed handler callback.
228 *
229 * Catches YouTube iframe embed URLs that are not parsable by oEmbed but can be translated into a URL that is.
230 *
231 * @since 4.0.0
232 *
233 * @global WP_Embed $wp_embed WordPress Embed object.
234 *
235 * @param array $matches The RegEx matches from the provided regex when calling
236 * wp_embed_register_handler().
237 * @param array $attr Embed attributes.
238 * @param string $url The original URL that was matched by the regex.
239 * @param array $rawattr The original unmodified attributes.
240 * @return string The embed HTML.
241 */
242function wp_embed_handler_youtube( $matches, $attr, $url, $rawattr ) {
243 global $wp_embed;
244 $embed = $wp_embed->autoembed( sprintf( 'https://youtube.com/watch?v=%s', urlencode( $matches[2] ) ) );
245
246 /**
247 * Filters the YouTube embed output.
248 *
249 * @since 4.0.0
250 *
251 * @see wp_embed_handler_youtube()
252 *
253 * @param string $embed YouTube embed output.
254 * @param array $attr An array of embed attributes.
255 * @param string $url The original URL that was matched by the regex.
256 * @param array $rawattr The original unmodified attributes.
257 */
258 return apply_filters( 'wp_embed_handler_youtube', $embed, $attr, $url, $rawattr );
259}
260
261/**
262 * Audio embed handler callback.
263 *
264 * @since 3.6.0
265 *
266 * @param array $matches The RegEx matches from the provided regex when calling wp_embed_register_handler().
267 * @param array $attr Embed attributes.
268 * @param string $url The original URL that was matched by the regex.
269 * @param array $rawattr The original unmodified attributes.
270 * @return string The embed HTML.
271 */
272function wp_embed_handler_audio( $matches, $attr, $url, $rawattr ) {
273 $audio = sprintf( '[audio src="%s" /]', esc_url( $url ) );
274
275 /**
276 * Filters the audio embed output.
277 *
278 * @since 3.6.0
279 *
280 * @param string $audio Audio embed output.
281 * @param array $attr An array of embed attributes.
282 * @param string $url The original URL that was matched by the regex.
283 * @param array $rawattr The original unmodified attributes.
284 */
285 return apply_filters( 'wp_embed_handler_audio', $audio, $attr, $url, $rawattr );
286}
287
288/**
289 * Video embed handler callback.
290 *
291 * @since 3.6.0
292 *
293 * @param array $matches The RegEx matches from the provided regex when calling wp_embed_register_handler().
294 * @param array $attr Embed attributes.
295 * @param string $url The original URL that was matched by the regex.
296 * @param array $rawattr The original unmodified attributes.
297 * @return string The embed HTML.
298 */
299function wp_embed_handler_video( $matches, $attr, $url, $rawattr ) {
300 $dimensions = '';
301 if ( ! empty( $rawattr['width'] ) && ! empty( $rawattr['height'] ) ) {
302 $dimensions .= sprintf( 'width="%d" ', (int) $rawattr['width'] );
303 $dimensions .= sprintf( 'height="%d" ', (int) $rawattr['height'] );
304 }
305 $video = sprintf( '[video %s src="%s" /]', $dimensions, esc_url( $url ) );
306
307 /**
308 * Filters the video embed output.
309 *
310 * @since 3.6.0
311 *
312 * @param string $video Video embed output.
313 * @param array $attr An array of embed attributes.
314 * @param string $url The original URL that was matched by the regex.
315 * @param array $rawattr The original unmodified attributes.
316 */
317 return apply_filters( 'wp_embed_handler_video', $video, $attr, $url, $rawattr );
318}
319
320/**
321 * Registers the oEmbed REST API route.
322 *
323 * @since 4.4.0
324 */
325function wp_oembed_register_route() {
326 $controller = new WP_oEmbed_Controller();
327 $controller->register_routes();
328}
329
330/**
331 * Adds oEmbed discovery links in the head element of the website.
332 *
333 * @since 4.4.0
334 * @since 6.8.0 Output was adjusted to only embed if the post supports it.
335 * @since 6.9.0 Now runs first at `wp_head` priority 4, with a fallback to priority 10. This helps ensure the discovery links appear within the first 150KB.
336 */
337function wp_oembed_add_discovery_links() {
338 if ( doing_action( 'wp_head' ) ) {
339 // For back-compat, short-circuit if a plugin has removed the action at the original priority.
340 if ( ! has_action( 'wp_head', 'wp_oembed_add_discovery_links', 10 ) ) {
341 return;
342 }
343
344 // Prevent running again at the original priority.
345 remove_action( 'wp_head', 'wp_oembed_add_discovery_links' );
346 }
347
348 $output = '';
349
350 if ( is_singular() && is_post_embeddable() ) {
351 $output .= '<link rel="alternate" title="' . _x( 'oEmbed (JSON)', 'oEmbed resource link name' ) . '" type="application/json+oembed" href="' . esc_url( get_oembed_endpoint_url( get_permalink() ) ) . '" />' . "\n";
352
353 if ( class_exists( 'SimpleXMLElement' ) ) {
354 $output .= '<link rel="alternate" title="' . _x( 'oEmbed (XML)', 'oEmbed resource link name' ) . '" type="text/xml+oembed" href="' . esc_url( get_oembed_endpoint_url( get_permalink(), 'xml' ) ) . '" />' . "\n";
355 }
356 }
357
358 /**
359 * Filters the oEmbed discovery links HTML.
360 *
361 * @since 4.4.0
362 *
363 * @param string $output HTML of the discovery links.
364 */
365 echo apply_filters( 'oembed_discovery_links', $output );
366}
367
368/**
369 * Adds the necessary JavaScript to communicate with the embedded iframes.
370 *
371 * This function is no longer used directly. For back-compat it exists exclusively as a way to indicate that the oEmbed
372 * host JS _should_ be added. In `default-filters.php` there remains this code:
373 *
374 * add_action( 'wp_head', 'wp_oembed_add_host_js' )
375 *
376 * Historically a site has been able to disable adding the oEmbed host script by doing:
377 *
378 * remove_action( 'wp_head', 'wp_oembed_add_host_js' )
379 *
380 * In order to ensure that such code still works as expected, this function remains. There is now a `has_action()` check
381 * in `wp_maybe_enqueue_oembed_host_js()` to see if `wp_oembed_add_host_js()` has not been unhooked from running at the
382 * `wp_head` action.
383 *
384 * @since 4.4.0
385 * @deprecated 5.9.0 Use {@see wp_maybe_enqueue_oembed_host_js()} instead.
386 */
387function wp_oembed_add_host_js() {}
388
389/**
390 * Enqueue the wp-embed script if the provided oEmbed HTML contains a post embed.
391 *
392 * In order to only enqueue the wp-embed script on pages that actually contain post embeds, this function checks if the
393 * provided HTML contains post embed markup and if so enqueues the script so that it will get printed in the footer.
394 *
395 * @since 5.9.0
396 *
397 * @param string $html Embed markup.
398 * @return string Embed markup (without modifications).
399 */
400function wp_maybe_enqueue_oembed_host_js( $html ) {
401 if (
402 has_action( 'wp_head', 'wp_oembed_add_host_js' )
403 &&
404 preg_match( '/<blockquote\s[^>]*?wp-embedded-content/', $html )
405 ) {
406 wp_enqueue_script( 'wp-embed' );
407 }
408 return $html;
409}
410
411/**
412 * Retrieves the URL to embed a specific post in an iframe.
413 *
414 * @since 4.4.0
415 *
416 * @param int|WP_Post $post Optional. Post ID or object. Defaults to the current post.
417 * @return string|false The post embed URL on success, false if the post doesn't exist.
418 */
419function get_post_embed_url( $post = null ) {
420 $post = get_post( $post );
421
422 if ( ! $post ) {
423 return false;
424 }
425
426 $embed_url = trailingslashit( get_permalink( $post ) ) . user_trailingslashit( 'embed' );
427 $path_conflict = get_page_by_path( str_replace( home_url(), '', $embed_url ), OBJECT, get_post_types( array( 'public' => true ) ) );
428
429 if ( ! get_option( 'permalink_structure' ) || $path_conflict ) {
430 $embed_url = add_query_arg( array( 'embed' => 'true' ), get_permalink( $post ) );
431 }
432
433 /**
434 * Filters the URL to embed a specific post.
435 *
436 * @since 4.4.0
437 *
438 * @param string $embed_url The post embed URL.
439 * @param WP_Post $post The corresponding post object.
440 */
441 return sanitize_url( apply_filters( 'post_embed_url', $embed_url, $post ) );
442}
443
444/**
445 * Retrieves the oEmbed endpoint URL for a given permalink.
446 *
447 * Pass an empty string as the first argument to get the endpoint base URL.
448 *
449 * @since 4.4.0
450 *
451 * @param string $permalink Optional. The permalink used for the `url` query arg. Default empty.
452 * @param string $format Optional. The requested response format. Default 'json'.
453 * @return string The oEmbed endpoint URL.
454 */
455function get_oembed_endpoint_url( $permalink = '', $format = 'json' ) {
456 $url = rest_url( 'oembed/1.0/embed' );
457
458 if ( '' !== $permalink ) {
459 $url = add_query_arg(
460 array(
461 'url' => urlencode( $permalink ),
462 'format' => ( 'json' !== $format ) ? $format : false,
463 ),
464 $url
465 );
466 }
467
468 /**
469 * Filters the oEmbed endpoint URL.
470 *
471 * @since 4.4.0
472 *
473 * @param string $url The URL to the oEmbed endpoint.
474 * @param string $permalink The permalink used for the `url` query arg.
475 * @param string $format The requested response format.
476 */
477 return apply_filters( 'oembed_endpoint_url', $url, $permalink, $format );
478}
479
480/**
481 * Retrieves the embed code for a specific post.
482 *
483 * @since 4.4.0
484 *
485 * @param int $width The width for the response.
486 * @param int $height The height for the response.
487 * @param int|WP_Post $post Optional. Post ID or object. Default is global `$post`.
488 * @return string|false Embed code on success, false if post doesn't exist.
489 */
490function get_post_embed_html( $width, $height, $post = null ) {
491 $post = get_post( $post );
492
493 if ( ! $post ) {
494 return false;
495 }
496
497 $embed_url = get_post_embed_url( $post );
498
499 $secret = wp_generate_password( 10, false );
500 $embed_url .= "#?secret={$secret}";
501
502 $output = sprintf(
503 '<blockquote class="wp-embedded-content" data-secret="%1$s"><a href="%2$s">%3$s</a></blockquote>',
504 esc_attr( $secret ),
505 esc_url( get_permalink( $post ) ),
506 get_the_title( $post )
507 );
508
509 $output .= sprintf(
510 '<iframe sandbox="allow-scripts" security="restricted" src="%1$s" width="%2$d" height="%3$d" title="%4$s" data-secret="%5$s" frameborder="0" marginwidth="0" marginheight="0" scrolling="no" class="wp-embedded-content"></iframe>',
511 esc_url( $embed_url ),
512 absint( $width ),
513 absint( $height ),
514 esc_attr(
515 sprintf(
516 /* translators: 1: Post title, 2: Site title. */
517 __( '“%1$s” — %2$s' ),
518 get_the_title( $post ),
519 get_bloginfo( 'name' )
520 )
521 ),
522 esc_attr( $secret )
523 );
524
525 /*
526 * Note that the script must be placed after the <blockquote> and <iframe> due to a regexp parsing issue in
527 * `wp_filter_oembed_result()`. Because of the regex pattern starts with `|(<blockquote>.*?</blockquote>)?.*|`
528 * wherein the <blockquote> is marked as being optional, if it is not at the beginning of the string then the group
529 * will fail to match and everything will be matched by `.*` and not included in the group. This regex issue goes
530 * back to WordPress 4.4, so in order to not break older installs this script must come at the end.
531 */
532 $js_path = '/js/wp-embed' . wp_scripts_get_suffix() . '.js';
533 $output .= wp_get_inline_script_tag(
534 trim( file_get_contents( ABSPATH . WPINC . $js_path ) ) . "\n//# sourceURL=" . esc_url_raw( includes_url( $js_path ) )
535 );
536
537 /**
538 * Filters the embed HTML output for a given post.
539 *
540 * @since 4.4.0
541 *
542 * @param string $output The default iframe tag to display embedded content.
543 * @param WP_Post $post Current post object.
544 * @param int $width Width of the response.
545 * @param int $height Height of the response.
546 */
547 return apply_filters( 'embed_html', $output, $post, $width, $height );
548}
549
550/**
551 * Retrieves the oEmbed response data for a given post.
552 *
553 * @since 4.4.0
554 * @since 6.8.0 Output was adjusted to only embed if the post type supports it.
555 *
556 * @param WP_Post|int $post Post ID or post object.
557 * @param int $width The requested width.
558 * @return array|false Response data on success, false if post doesn't exist,
559 * is not publicly viewable or post type is not embeddable.
560 */
561function get_oembed_response_data( $post, $width ) {
562 $post = get_post( $post );
563 $width = absint( $width );
564
565 if ( ! $post ) {
566 return false;
567 }
568
569 if ( ! is_post_publicly_viewable( $post ) ) {
570 return false;
571 }
572
573 if ( ! is_post_embeddable( $post ) ) {
574 return false;
575 }
576
577 /**
578 * Filters the allowed minimum and maximum widths for the oEmbed response.
579 *
580 * @since 4.4.0
581 *
582 * @param array $min_max_width {
583 * Minimum and maximum widths for the oEmbed response.
584 *
585 * @type int $min Minimum width. Default 200.
586 * @type int $max Maximum width. Default 600.
587 * }
588 */
589 $min_max_width = apply_filters(
590 'oembed_min_max_width',
591 array(
592 'min' => 200,
593 'max' => 600,
594 )
595 );
596
597 $width = min( max( $min_max_width['min'], $width ), $min_max_width['max'] );
598 $height = max( (int) ceil( $width / 16 * 9 ), 200 );
599
600 $data = array(
601 'version' => '1.0',
602 'provider_name' => get_bloginfo( 'name' ),
603 'provider_url' => get_home_url(),
604 'author_name' => get_bloginfo( 'name' ),
605 'author_url' => get_home_url(),
606 'title' => get_the_title( $post ),
607 'type' => 'link',
608 );
609
610 $author = get_userdata( $post->post_author );
611
612 if ( $author ) {
613 $data['author_name'] = $author->display_name;
614 $data['author_url'] = get_author_posts_url( $author->ID );
615 }
616
617 /**
618 * Filters the oEmbed response data.
619 *
620 * @since 4.4.0
621 *
622 * @param array $data The response data.
623 * @param WP_Post $post The post object.
624 * @param int $width The requested width.
625 * @param int $height The calculated height.
626 */
627 return apply_filters( 'oembed_response_data', $data, $post, $width, $height );
628}
629
630
631/**
632 * Retrieves the oEmbed response data for a given URL.
633 *
634 * @since 5.0.0
635 *
636 * @param string $url The URL that should be inspected for discovery `<link>` tags.
637 * @param array $args oEmbed remote get arguments.
638 * @return object|false oEmbed response data if the URL does belong to the current site. False otherwise.
639 */
640function get_oembed_response_data_for_url( $url, $args ) {
641 $switched_blog = false;
642
643 if ( is_multisite() ) {
644 $url_parts = wp_parse_args(
645 wp_parse_url( $url ),
646 array(
647 'host' => '',
648 'port' => null,
649 'path' => '/',
650 )
651 );
652
653 $qv = array(
654 'domain' => $url_parts['host'] . ( $url_parts['port'] ? ':' . $url_parts['port'] : '' ),
655 'path' => '/',
656 'update_site_meta_cache' => false,
657 );
658
659 // In case of subdirectory configs, set the path.
660 if ( ! is_subdomain_install() ) {
661 $path = explode( '/', ltrim( $url_parts['path'], '/' ) );
662 $path = reset( $path );
663
664 if ( $path ) {
665 $qv['path'] = get_network()->path . $path . '/';
666 }
667 }
668
669 $sites = get_sites( $qv );
670 $site = reset( $sites );
671
672 // Do not allow embeds for deleted/archived/spam sites.
673 if ( ! empty( $site->deleted ) || ! empty( $site->spam ) || ! empty( $site->archived ) ) {
674 return false;
675 }
676
677 if ( $site && get_current_blog_id() !== (int) $site->blog_id ) {
678 switch_to_blog( $site->blog_id );
679 $switched_blog = true;
680 }
681 }
682
683 $post_id = url_to_postid( $url );
684
685 /** This filter is documented in wp-includes/class-wp-oembed-controller.php */
686 $post_id = apply_filters( 'oembed_request_post_id', $post_id, $url );
687
688 if ( ! $post_id ) {
689 if ( $switched_blog ) {
690 restore_current_blog();
691 }
692
693 return false;
694 }
695
696 $width = isset( $args['width'] ) ? $args['width'] : 0;
697
698 $data = get_oembed_response_data( $post_id, $width );
699
700 if ( $switched_blog ) {
701 restore_current_blog();
702 }
703
704 return $data ? (object) $data : false;
705}
706
707
708/**
709 * Filters the oEmbed response data to return an iframe embed code.
710 *
711 * @since 4.4.0
712 *
713 * @param array $data The response data.
714 * @param WP_Post $post The post object.
715 * @param int $width The requested width.
716 * @param int $height The calculated height.
717 * @return array The modified response data.
718 */
719function get_oembed_response_data_rich( $data, $post, $width, $height ) {
720 $data['width'] = absint( $width );
721 $data['height'] = absint( $height );
722 $data['type'] = 'rich';
723 $data['html'] = get_post_embed_html( $width, $height, $post );
724
725 // Add post thumbnail to response if available.
726 $thumbnail_id = false;
727
728 if ( has_post_thumbnail( $post->ID ) ) {
729 $thumbnail_id = get_post_thumbnail_id( $post->ID );
730 }
731
732 if ( 'attachment' === get_post_type( $post ) ) {
733 if ( wp_attachment_is_image( $post ) ) {
734 $thumbnail_id = $post->ID;
735 } elseif ( wp_attachment_is( 'video', $post ) ) {
736 $thumbnail_id = get_post_thumbnail_id( $post );
737 $data['type'] = 'video';
738 }
739 }
740
741 if ( $thumbnail_id ) {
742 list( $thumbnail_url, $thumbnail_width, $thumbnail_height ) = wp_get_attachment_image_src( $thumbnail_id, array( $width, 0 ) );
743 $data['thumbnail_url'] = $thumbnail_url;
744 $data['thumbnail_width'] = $thumbnail_width;
745 $data['thumbnail_height'] = $thumbnail_height;
746 }
747
748 return $data;
749}
750
751/**
752 * Ensures that the specified format is either 'json' or 'xml'.
753 *
754 * @since 4.4.0
755 *
756 * @param string $format The oEmbed response format. Accepts 'json' or 'xml'.
757 * @return string The format, either 'xml' or 'json'. Default 'json'.
758 */
759function wp_oembed_ensure_format( $format ) {
760 if ( ! in_array( $format, array( 'json', 'xml' ), true ) ) {
761 return 'json';
762 }
763
764 return $format;
765}
766
767/**
768 * Hooks into the REST API output to print XML instead of JSON.
769 *
770 * This is only done for the oEmbed API endpoint,
771 * which supports both formats.
772 *
773 * @access private
774 * @since 4.4.0
775 *
776 * @param bool $served Whether the request has already been served.
777 * @param WP_HTTP_Response $result Result to send to the client. Usually a `WP_REST_Response`.
778 * @param WP_REST_Request $request Request used to generate the response.
779 * @param WP_REST_Server $server Server instance.
780 * @return bool True if the request was served, false otherwise.
781 */
782function _oembed_rest_pre_serve_request( $served, $result, $request, $server ) {
783 $params = $request->get_params();
784
785 if ( '/oembed/1.0/embed' !== $request->get_route() || 'GET' !== $request->get_method() ) {
786 return $served;
787 }
788
789 if ( ! isset( $params['format'] ) || 'xml' !== $params['format'] ) {
790 return $served;
791 }
792
793 // Embed links inside the request.
794 $data = $server->response_to_data( $result, false );
795
796 if ( ! class_exists( 'SimpleXMLElement' ) ) {
797 status_header( 501 );
798 die( get_status_header_desc( 501 ) );
799 }
800
801 $result = _oembed_create_xml( $data );
802
803 // Bail if there's no XML.
804 if ( ! $result ) {
805 status_header( 501 );
806 die( get_status_header_desc( 501 ) );
807 }
808
809 if ( ! headers_sent() ) {
810 $server->send_header( 'Content-Type', 'text/xml; charset=' . get_option( 'blog_charset' ) );
811 }
812
813 echo $result;
814
815 return true;
816}
817
818/**
819 * Creates an XML string from a given array.
820 *
821 * @since 4.4.0
822 * @access private
823 *
824 * @param array $data The original oEmbed response data.
825 * @param SimpleXMLElement $node Optional. XML node to append the result to recursively.
826 * @return string|false XML string on success, false on error.
827 */
828function _oembed_create_xml( $data, $node = null ) {
829 if ( ! is_array( $data ) || empty( $data ) ) {
830 return false;
831 }
832
833 if ( null === $node ) {
834 $node = new SimpleXMLElement( '<oembed></oembed>' );
835 }
836
837 foreach ( $data as $key => $value ) {
838 if ( is_numeric( $key ) ) {
839 $key = 'oembed';
840 }
841
842 if ( is_array( $value ) ) {
843 $item = $node->addChild( $key );
844 _oembed_create_xml( $value, $item );
845 } else {
846 $node->addChild( $key, esc_html( $value ) );
847 }
848 }
849
850 return $node->asXML();
851}
852
853/**
854 * Filters the given oEmbed HTML to make sure iframes have a title attribute.
855 *
856 * @since 5.2.0
857 *
858 * @param string|false $result The oEmbed HTML result.
859 * @param object $data A data object result from an oEmbed provider.
860 * @param string $url The URL of the content to be embedded.
861 * @return string|false The filtered oEmbed result.
862 */
863function wp_filter_oembed_iframe_title_attribute( $result, $data, $url ) {
864 if ( false === $result || ! in_array( $data->type, array( 'rich', 'video' ), true ) ) {
865 return $result;
866 }
867
868 $title = ! empty( $data->title ) ? $data->title : '';
869
870 $pattern = '`<iframe([^>]*)>`i';
871 if ( preg_match( $pattern, $result, $matches ) ) {
872 $attrs = wp_kses_hair( $matches[1], wp_allowed_protocols() );
873
874 foreach ( $attrs as $attr => $item ) {
875 $lower_attr = strtolower( $attr );
876 if ( $lower_attr === $attr ) {
877 continue;
878 }
879 if ( ! isset( $attrs[ $lower_attr ] ) ) {
880 $attrs[ $lower_attr ] = $item;
881 unset( $attrs[ $attr ] );
882 }
883 }
884 }
885
886 if ( ! empty( $attrs['title']['value'] ) ) {
887 $title = $attrs['title']['value'];
888 }
889
890 /**
891 * Filters the title attribute of the given oEmbed HTML iframe.
892 *
893 * @since 5.2.0
894 *
895 * @param string $title The title attribute.
896 * @param string $result The oEmbed HTML result.
897 * @param object $data A data object result from an oEmbed provider.
898 * @param string $url The URL of the content to be embedded.
899 */
900 $title = apply_filters( 'oembed_iframe_title_attribute', $title, $result, $data, $url );
901
902 if ( '' === $title ) {
903 return $result;
904 }
905
906 if ( isset( $attrs['title'] ) ) {
907 unset( $attrs['title'] );
908 $attr_string = implode( ' ', wp_list_pluck( $attrs, 'whole' ) );
909 $result = str_replace( $matches[0], '<iframe ' . trim( $attr_string ) . '>', $result );
910 }
911 return str_ireplace( '<iframe ', sprintf( '<iframe title="%s" ', esc_attr( $title ) ), $result );
912}
913
914
915/**
916 * Filters the given oEmbed HTML.
917 *
918 * If the `$url` isn't on the trusted providers list,
919 * we need to filter the HTML heavily for security.
920 *
921 * Only filters 'rich' and 'video' response types.
922 *
923 * @since 4.4.0
924 *
925 * @param string|false $result The oEmbed HTML result.
926 * @param object $data A data object result from an oEmbed provider.
927 * @param string $url The URL of the content to be embedded.
928 * @return string|false The filtered and sanitized oEmbed result.
929 */
930function wp_filter_oembed_result( $result, $data, $url ) {
931 if ( false === $result || ! in_array( $data->type, array( 'rich', 'video' ), true ) ) {
932 return $result;
933 }
934
935 $wp_oembed = _wp_oembed_get_object();
936
937 // Don't modify the HTML for trusted providers.
938 if ( false !== $wp_oembed->get_provider( $url, array( 'discover' => false ) ) ) {
939 return $result;
940 }
941
942 $allowed_html = array(
943 'a' => array(
944 'href' => true,
945 ),
946 'blockquote' => array(),
947 'iframe' => array(
948 'src' => true,
949 'width' => true,
950 'height' => true,
951 'frameborder' => true,
952 'marginwidth' => true,
953 'marginheight' => true,
954 'scrolling' => true,
955 'title' => true,
956 ),
957 );
958
959 $html = wp_kses( $result, $allowed_html );
960
961 preg_match( '|(<blockquote>.*?</blockquote>)?.*(<iframe.*?></iframe>)|ms', $html, $content );
962 // We require at least the iframe to exist.
963 if ( empty( $content[2] ) ) {
964 return false;
965 }
966 $html = $content[1] . $content[2];
967
968 preg_match( '/ src=([\'"])(.*?)\1/', $html, $results );
969
970 if ( ! empty( $results ) ) {
971 $secret = wp_generate_password( 10, false );
972
973 $url = esc_url( "{$results[2]}#?secret=$secret" );
974 $q = $results[1];
975
976 $html = str_replace( $results[0], ' src=' . $q . $url . $q . ' data-secret=' . $q . $secret . $q, $html );
977 $html = str_replace( '<blockquote', "<blockquote data-secret=\"$secret\"", $html );
978 }
979
980 $allowed_html['blockquote']['data-secret'] = true;
981 $allowed_html['iframe']['data-secret'] = true;
982
983 $html = wp_kses( $html, $allowed_html );
984
985 if ( ! empty( $content[1] ) ) {
986 // We have a blockquote to fall back on. Hide the iframe by default.
987 $html = str_replace( '<iframe', '<iframe style="position: absolute; visibility: hidden;"', $html );
988 $html = str_replace( '<blockquote', '<blockquote class="wp-embedded-content"', $html );
989 }
990
991 $html = str_ireplace( '<iframe', '<iframe class="wp-embedded-content" sandbox="allow-scripts" security="restricted"', $html );
992
993 return $html;
994}
995
996/**
997 * Filters the string in the 'more' link displayed after a trimmed excerpt.
998 *
999 * Replaces '[...]' (appended to automatically generated excerpts) with an
1000 * ellipsis and a "Continue reading" link in the embed template.
1001 *
1002 * @since 4.4.0
1003 *
1004 * @param string $more_string Default 'more' string.
1005 * @return string 'Continue reading' link prepended with an ellipsis.
1006 */
1007function wp_embed_excerpt_more( $more_string ) {
1008 if ( ! is_embed() ) {
1009 return $more_string;
1010 }
1011
1012 $link = sprintf(
1013 '<a href="%1$s" class="wp-embed-more" target="_top">%2$s</a>',
1014 esc_url( get_permalink() ),
1015 /* translators: %s: Post title. */
1016 sprintf( __( 'Continue reading %s' ), '<span class="screen-reader-text">' . get_the_title() . '</span>' )
1017 );
1018 return ' … ' . $link;
1019}
1020
1021/**
1022 * Displays the post excerpt for the embed template.
1023 *
1024 * Intended to be used in 'The Loop'.
1025 *
1026 * @since 4.4.0
1027 */
1028function the_excerpt_embed() {
1029 $output = get_the_excerpt();
1030
1031 /**
1032 * Filters the post excerpt for the embed template.
1033 *
1034 * @since 4.4.0
1035 *
1036 * @param string $output The current post excerpt.
1037 */
1038 echo apply_filters( 'the_excerpt_embed', $output );
1039}
1040
1041/**
1042 * Filters the post excerpt for the embed template.
1043 *
1044 * Shows players for video and audio attachments.
1045 *
1046 * @since 4.4.0
1047 *
1048 * @param string $content The current post excerpt.
1049 * @return string The modified post excerpt.
1050 */
1051function wp_embed_excerpt_attachment( $content ) {
1052 if ( is_attachment() ) {
1053 return prepend_attachment( '' );
1054 }
1055
1056 return $content;
1057}
1058
1059/**
1060 * Enqueues embed iframe default CSS and JS.
1061 *
1062 * Enqueue PNG fallback CSS for embed iframe for legacy versions of IE.
1063 *
1064 * Allows plugins to queue scripts for the embed iframe end using wp_enqueue_script().
1065 * Runs first in oembed_head().
1066 *
1067 * @since 4.4.0
1068 */
1069function enqueue_embed_scripts() {
1070
1071 /**
1072 * Fires when scripts and styles are enqueued for the embed iframe.
1073 *
1074 * @since 4.4.0
1075 */
1076 do_action( 'enqueue_embed_scripts' );
1077}
1078
1079/**
1080 * Enqueues the CSS in the embed iframe header.
1081 *
1082 * @since 6.4.0
1083 */
1084function wp_enqueue_embed_styles() {
1085 // Back-compat for plugins that disable functionality by unhooking this action.
1086 if ( ! has_action( 'embed_head', 'print_embed_styles' ) ) {
1087 return;
1088 }
1089 remove_action( 'embed_head', 'print_embed_styles' );
1090
1091 $suffix = wp_scripts_get_suffix();
1092 $handle = 'wp-embed-template';
1093 wp_register_style( $handle, false );
1094 wp_add_inline_style( $handle, file_get_contents( ABSPATH . WPINC . "/css/wp-embed-template$suffix.css" ) );
1095 wp_enqueue_style( $handle );
1096}
1097
1098/**
1099 * Prints the JavaScript in the embed iframe header.
1100 *
1101 * @since 4.4.0
1102 */
1103function print_embed_scripts() {
1104 $js_path = '/js/wp-embed-template' . wp_scripts_get_suffix() . '.js';
1105 wp_print_inline_script_tag(
1106 trim( file_get_contents( ABSPATH . WPINC . $js_path ) ) . "\n//# sourceURL=" . esc_url_raw( includes_url( $js_path ) )
1107 );
1108}
1109
1110/**
1111 * Prepare the oembed HTML to be displayed in an RSS feed.
1112 *
1113 * @since 4.4.0
1114 * @access private
1115 *
1116 * @param string $content The content to filter.
1117 * @return string The filtered content.
1118 */
1119function _oembed_filter_feed_content( $content ) {
1120 $p = new WP_HTML_Tag_Processor( $content );
1121 while ( $p->next_tag( array( 'tag_name' => 'iframe' ) ) ) {
1122 if ( $p->has_class( 'wp-embedded-content' ) ) {
1123 $p->remove_attribute( 'style' );
1124 }
1125 }
1126 return $p->get_updated_html();
1127}
1128
1129/**
1130 * Prints the necessary markup for the embed comments button.
1131 *
1132 * @since 4.4.0
1133 */
1134function print_embed_comments_button() {
1135 if ( is_404() || ! ( get_comments_number() || comments_open() ) ) {
1136 return;
1137 }
1138 ?>
1139 <div class="wp-embed-comments">
1140 <a href="<?php comments_link(); ?>" target="_top">
1141 <span class="dashicons dashicons-admin-comments"></span>
1142 <?php
1143 printf(
1144 /* translators: %s: Number of comments. */
1145 _n(
1146 '%s <span class="screen-reader-text">Comment</span>',
1147 '%s <span class="screen-reader-text">Comments</span>',
1148 get_comments_number()
1149 ),
1150 number_format_i18n( get_comments_number() )
1151 );
1152 ?>
1153 </a>
1154 </div>
1155 <?php
1156}
1157
1158/**
1159 * Prints the necessary markup for the embed sharing button.
1160 *
1161 * @since 4.4.0
1162 */
1163function print_embed_sharing_button() {
1164 if ( is_404() ) {
1165 return;
1166 }
1167 ?>
1168 <div class="wp-embed-share">
1169 <button type="button" class="wp-embed-share-dialog-open" aria-label="<?php esc_attr_e( 'Open sharing dialog' ); ?>">
1170 <span class="dashicons dashicons-share"></span>
1171 </button>
1172 </div>
1173 <?php
1174}
1175
1176/**
1177 * Prints the necessary markup for the embed sharing dialog.
1178 *
1179 * @since 4.4.0
1180 */
1181function print_embed_sharing_dialog() {
1182 if ( is_404() ) {
1183 return;
1184 }
1185
1186 $unique_suffix = get_the_ID() . '-' . wp_rand();
1187 $share_tab_wordpress_id = 'wp-embed-share-tab-wordpress-' . $unique_suffix;
1188 $share_tab_html_id = 'wp-embed-share-tab-html-' . $unique_suffix;
1189 $description_wordpress_id = 'wp-embed-share-description-wordpress-' . $unique_suffix;
1190 $description_html_id = 'wp-embed-share-description-html-' . $unique_suffix;
1191 ?>
1192 <div class="wp-embed-share-dialog hidden" role="dialog" aria-label="<?php esc_attr_e( 'Sharing options' ); ?>">
1193 <div class="wp-embed-share-dialog-content">
1194 <div class="wp-embed-share-dialog-text">
1195 <ul class="wp-embed-share-tabs" role="tablist">
1196 <li class="wp-embed-share-tab-button wp-embed-share-tab-button-wordpress" role="presentation">
1197 <button type="button" role="tab" aria-controls="<?php echo $share_tab_wordpress_id; ?>" aria-selected="true" tabindex="0"><?php esc_html_e( 'WordPress Embed' ); ?></button>
1198 </li>
1199 <li class="wp-embed-share-tab-button wp-embed-share-tab-button-html" role="presentation">
1200 <button type="button" role="tab" aria-controls="<?php echo $share_tab_html_id; ?>" aria-selected="false" tabindex="-1"><?php esc_html_e( 'HTML Embed' ); ?></button>
1201 </li>
1202 </ul>
1203 <div id="<?php echo $share_tab_wordpress_id; ?>" class="wp-embed-share-tab" role="tabpanel" aria-hidden="false">
1204 <input type="text" value="<?php the_permalink(); ?>" class="wp-embed-share-input" aria-label="<?php esc_attr_e( 'URL' ); ?>" aria-describedby="<?php echo $description_wordpress_id; ?>" tabindex="0" readonly/>
1205
1206 <p class="wp-embed-share-description" id="<?php echo $description_wordpress_id; ?>">
1207 <?php _e( 'Copy and paste this URL into your WordPress site to embed' ); ?>
1208 </p>
1209 </div>
1210 <div id="<?php echo $share_tab_html_id; ?>" class="wp-embed-share-tab" role="tabpanel" aria-hidden="true">
1211 <textarea class="wp-embed-share-input" aria-label="<?php esc_attr_e( 'HTML' ); ?>" aria-describedby="<?php echo $description_html_id; ?>" tabindex="0" readonly><?php echo esc_textarea( get_post_embed_html( 600, 400 ) ); ?></textarea>
1212
1213 <p class="wp-embed-share-description" id="<?php echo $description_html_id; ?>">
1214 <?php _e( 'Copy and paste this code into your site to embed' ); ?>
1215 </p>
1216 </div>
1217 </div>
1218
1219 <button type="button" class="wp-embed-share-dialog-close" aria-label="<?php esc_attr_e( 'Close sharing dialog' ); ?>">
1220 <span class="dashicons dashicons-no"></span>
1221 </button>
1222 </div>
1223 </div>
1224 <?php
1225}
1226
1227/**
1228 * Prints the necessary markup for the site title in an embed template.
1229 *
1230 * @since 4.5.0
1231 */
1232function the_embed_site_title() {
1233 $site_title = sprintf(
1234 '<a href="%s" target="_top"><img src="%s" srcset="%s 2x" width="32" height="32" alt="" class="wp-embed-site-icon" /><span>%s</span></a>',
1235 esc_url( home_url() ),
1236 esc_url( get_site_icon_url( 32, includes_url( 'images/w-logo-blue.png' ) ) ),
1237 esc_url( get_site_icon_url( 64, includes_url( 'images/w-logo-blue.png' ) ) ),
1238 esc_html( get_bloginfo( 'name' ) )
1239 );
1240
1241 $site_title = '<div class="wp-embed-site-title">' . $site_title . '</div>';
1242
1243 /**
1244 * Filters the site title HTML in the embed footer.
1245 *
1246 * @since 4.4.0
1247 *
1248 * @param string $site_title The site title HTML.
1249 */
1250 echo apply_filters( 'embed_site_title_html', $site_title );
1251}
1252
1253/**
1254 * Filters the oEmbed result before any HTTP requests are made.
1255 *
1256 * If the URL belongs to the current site, the result is fetched directly instead of
1257 * going through the oEmbed discovery process.
1258 *
1259 * @since 4.5.3
1260 *
1261 * @param null|string $result The UNSANITIZED (and potentially unsafe) HTML that should be used to embed. Default null.
1262 * @param string $url The URL that should be inspected for discovery `<link>` tags.
1263 * @param array $args oEmbed remote get arguments.
1264 * @return null|string The UNSANITIZED (and potentially unsafe) HTML that should be used to embed.
1265 * Null if the URL does not belong to the current site.
1266 */
1267function wp_filter_pre_oembed_result( $result, $url, $args ) {
1268 $data = get_oembed_response_data_for_url( $url, $args );
1269
1270 if ( $data ) {
1271 return _wp_oembed_get_object()->data2html( $data, $url );
1272 }
1273
1274 return $result;
1275}
1276