WP_Embed

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

Defined (1)

The class is defined in the following location(s).

/wp-includes/class-wp-embed.php  
  1. class WP_Embed { 
  2. public $handlers = array(); 
  3. public $post_ID; 
  4. public $usecache = true; 
  5. public $linkifunknown = true; 
  6. public $last_attr = array(); 
  7. public $last_url = ''; 
  8.  
  9. /** 
  10. * When a URL cannot be embedded, return false instead of returning a link 
  11. * or the URL. 
  12. * Bypasses the {@see 'embed_maybe_make_link'} filter. 
  13. * @access public 
  14. * @var bool 
  15. */ 
  16. public $return_false_on_fail = false; 
  17.  
  18. /** 
  19. * Constructor 
  20. */ 
  21. public function __construct() { 
  22. // Hack to get the [embed] shortcode to run before wpautop() 
  23. add_filter( 'the_content', array( $this, 'run_shortcode' ), 8 ); 
  24.  
  25. // Shortcode placeholder for strip_shortcodes() 
  26. add_shortcode( 'embed', '__return_false' ); 
  27.  
  28. // Attempts to embed all URLs in a post 
  29. add_filter( 'the_content', array( $this, 'autoembed' ), 8 ); 
  30.  
  31. // After a post is saved, cache oEmbed items via Ajax 
  32. add_action( 'edit_form_advanced', array( $this, 'maybe_run_ajax_cache' ) ); 
  33. add_action( 'edit_page_form', array( $this, 'maybe_run_ajax_cache' ) ); 
  34.  
  35. /** 
  36. * Process the [embed] shortcode. 
  37. * Since the [embed] shortcode needs to be run earlier than other shortcodes,  
  38. * this function removes all existing shortcodes, registers the [embed] shortcode,  
  39. * calls do_shortcode(), and then re-registers the old shortcodes. 
  40. * @global array $shortcode_tags 
  41. * @param string $content Content to parse 
  42. * @return string Content with shortcode parsed 
  43. */ 
  44. public function run_shortcode( $content ) { 
  45. global $shortcode_tags; 
  46.  
  47. // Back up current registered shortcodes and clear them all out 
  48. $orig_shortcode_tags = $shortcode_tags; 
  49. remove_all_shortcodes(); 
  50.  
  51. add_shortcode( 'embed', array( $this, 'shortcode' ) ); 
  52.  
  53. // Do the shortcode (only the [embed] one is registered) 
  54. $content = do_shortcode( $content, true ); 
  55.  
  56. // Put the original shortcodes back 
  57. $shortcode_tags = $orig_shortcode_tags; 
  58.  
  59. return $content; 
  60.  
  61. /** 
  62. * If a post/page was saved, then output JavaScript to make 
  63. * an Ajax request that will call WP_Embed::cache_oembed(). 
  64. */ 
  65. public function maybe_run_ajax_cache() { 
  66. $post = get_post(); 
  67.  
  68. if ( ! $post || empty( $_GET['message'] ) ) 
  69. return; 
  70.  
  71. ?> 
  72. <script type="text/javascript"> 
  73. jQuery(document).ready(function($) { 
  74. $.get("<?php echo admin_url( 'admin-ajax.php?action=oembed-cache&post=' . $post->ID, 'relative' ); ?>"); 
  75. }); 
  76. </script> 
  77. <?php 
  78.  
  79. /** 
  80. * Registers an embed handler. 
  81. * Do not use this function directly, use wp_embed_register_handler() instead. 
  82. * This function should probably also only be used for sites that do not support oEmbed. 
  83. * @param string $id An internal ID/name for the handler. Needs to be unique. 
  84. * @param string $regex The regex that will be used to see if this handler should be used for a URL. 
  85. * @param callable $callback The callback function that will be called if the regex is matched. 
  86. * @param int $priority 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. 
  87. */ 
  88. public function register_handler( $id, $regex, $callback, $priority = 10 ) { 
  89. $this->handlers[$priority][$id] = array( 
  90. 'regex' => $regex,  
  91. 'callback' => $callback,  
  92. ); 
  93.  
  94. /** 
  95. * Unregisters a previously-registered embed handler. 
  96. * Do not use this function directly, use wp_embed_unregister_handler() instead. 
  97. * @param string $id The handler ID that should be removed. 
  98. * @param int $priority Optional. The priority of the handler to be removed (default: 10). 
  99. */ 
  100. public function unregister_handler( $id, $priority = 10 ) { 
  101. unset( $this->handlers[ $priority ][ $id ] ); 
  102.  
  103. /** 
  104. * The do_shortcode() callback function. 
  105. * Attempts to convert a URL into embed HTML. Starts by checking the URL against the regex of 
  106. * the registered embed handlers. If none of the regex matches and it's enabled, then the URL 
  107. * will be given to the WP_oEmbed class. 
  108. * @param array $attr { 
  109. * Shortcode attributes. Optional. 
  110. * @type int $width Width of the embed in pixels. 
  111. * @type int $height Height of the embed in pixels. 
  112. * } 
  113. * @param string $url The URL attempting to be embedded. 
  114. * @return string|false The embed HTML on success, otherwise the original URL. 
  115. * `->maybe_make_link()` can return false on failure. 
  116. */ 
  117. public function shortcode( $attr, $url = '' ) { 
  118. $post = get_post(); 
  119.  
  120. if ( empty( $url ) && ! empty( $attr['src'] ) ) { 
  121. $url = $attr['src']; 
  122.  
  123. $this->last_url = $url; 
  124.  
  125. if ( empty( $url ) ) { 
  126. $this->last_attr = $attr; 
  127. return ''; 
  128.  
  129. $rawattr = $attr; 
  130. $attr = wp_parse_args( $attr, wp_embed_defaults( $url ) ); 
  131.  
  132. $this->last_attr = $attr; 
  133.  
  134. // kses converts & into & and we need to undo this 
  135. // See https://core.trac.wordpress.org/ticket/11311 
  136. $url = str_replace( '&', '&', $url ); 
  137.  
  138. // Look for known internal handlers 
  139. ksort( $this->handlers ); 
  140. foreach ( $this->handlers as $priority => $handlers ) { 
  141. foreach ( $handlers as $id => $handler ) { 
  142. if ( preg_match( $handler['regex'], $url, $matches ) && is_callable( $handler['callback'] ) ) { 
  143. if ( false !== $return = call_user_func( $handler['callback'], $matches, $attr, $url, $rawattr ) ) 
  144. /** 
  145. * Filters the returned embed handler. 
  146. * @since 2.9.0 
  147. * @see WP_Embed::shortcode() 
  148. * @param mixed $return The shortcode callback function to call. 
  149. * @param string $url The attempted embed URL. 
  150. * @param array $attr An array of shortcode attributes. 
  151. */ 
  152. return apply_filters( 'embed_handler_html', $return, $url, $attr ); 
  153.  
  154. $post_ID = ( ! empty( $post->ID ) ) ? $post->ID : null; 
  155. if ( ! empty( $this->post_ID ) ) // Potentially set by WP_Embed::cache_oembed() 
  156. $post_ID = $this->post_ID; 
  157.  
  158. // Unknown URL format. Let oEmbed have a go. 
  159. if ( $post_ID ) { 
  160.  
  161. // Check for a cached result (stored in the post meta) 
  162. $key_suffix = md5( $url . serialize( $attr ) ); 
  163. $cachekey = '_oembed_' . $key_suffix; 
  164. $cachekey_time = '_oembed_time_' . $key_suffix; 
  165.  
  166. /** 
  167. * Filters the oEmbed TTL value (time to live). 
  168. * @since 4.0.0 
  169. * @param int $time Time to live (in seconds). 
  170. * @param string $url The attempted embed URL. 
  171. * @param array $attr An array of shortcode attributes. 
  172. * @param int $post_ID Post ID. 
  173. */ 
  174. $ttl = apply_filters( 'oembed_ttl', DAY_IN_SECONDS, $url, $attr, $post_ID ); 
  175.  
  176. $cache = get_post_meta( $post_ID, $cachekey, true ); 
  177. $cache_time = get_post_meta( $post_ID, $cachekey_time, true ); 
  178.  
  179. if ( ! $cache_time ) { 
  180. $cache_time = 0; 
  181.  
  182. $cached_recently = ( time() - $cache_time ) < $ttl; 
  183.  
  184. if ( $this->usecache || $cached_recently ) { 
  185. // Failures are cached. Serve one if we're using the cache. 
  186. if ( '{{unknown}}' === $cache ) 
  187. return $this->maybe_make_link( $url ); 
  188.  
  189. if ( ! empty( $cache ) ) { 
  190. /** 
  191. * Filters the cached oEmbed HTML. 
  192. * @since 2.9.0 
  193. * @see WP_Embed::shortcode() 
  194. * @param mixed $cache The cached HTML result, stored in post meta. 
  195. * @param string $url The attempted embed URL. 
  196. * @param array $attr An array of shortcode attributes. 
  197. * @param int $post_ID Post ID. 
  198. */ 
  199. return apply_filters( 'embed_oembed_html', $cache, $url, $attr, $post_ID ); 
  200.  
  201. /** 
  202. * Filters whether to inspect the given URL for discoverable link tags. 
  203. * @since 2.9.0 
  204. * @since 4.4.0 The default value changed to true. 
  205. * @see WP_oEmbed::discover() 
  206. * @param bool $enable Whether to enable `<link>` tag discovery. Default true. 
  207. */ 
  208. $attr['discover'] = ( apply_filters( 'embed_oembed_discover', true ) ); 
  209.  
  210. // Use oEmbed to get the HTML 
  211. $html = wp_oembed_get( $url, $attr ); 
  212.  
  213. // Maybe cache the result 
  214. if ( $html ) { 
  215. update_post_meta( $post_ID, $cachekey, $html ); 
  216. update_post_meta( $post_ID, $cachekey_time, time() ); 
  217. } elseif ( ! $cache ) { 
  218. update_post_meta( $post_ID, $cachekey, '{{unknown}}' ); 
  219.  
  220. // If there was a result, return it 
  221. if ( $html ) { 
  222. /** This filter is documented in wp-includes/class-wp-embed.php */ 
  223. return apply_filters( 'embed_oembed_html', $html, $url, $attr, $post_ID ); 
  224.  
  225. // Still unknown 
  226. return $this->maybe_make_link( $url ); 
  227.  
  228. /** 
  229. * Delete all oEmbed caches. Unused by core as of 4.0.0. 
  230. * @param int $post_ID Post ID to delete the caches for. 
  231. */ 
  232. public function delete_oembed_caches( $post_ID ) { 
  233. $post_metas = get_post_custom_keys( $post_ID ); 
  234. if ( empty($post_metas) ) 
  235. return; 
  236.  
  237. foreach ( $post_metas as $post_meta_key ) { 
  238. if ( '_oembed_' == substr( $post_meta_key, 0, 8 ) ) 
  239. delete_post_meta( $post_ID, $post_meta_key ); 
  240.  
  241. /** 
  242. * Triggers a caching of all oEmbed results. 
  243. * @param int $post_ID Post ID to do the caching for. 
  244. */ 
  245. public function cache_oembed( $post_ID ) { 
  246. $post = get_post( $post_ID ); 
  247.  
  248. $post_types = get_post_types( array( 'show_ui' => true ) ); 
  249. /** 
  250. * Filters the array of post types to cache oEmbed results for. 
  251. * @since 2.9.0 
  252. * @param array $post_types Array of post types to cache oEmbed results for. Defaults to post types with `show_ui` set to true. 
  253. */ 
  254. if ( empty( $post->ID ) || ! in_array( $post->post_type, apply_filters( 'embed_cache_oembed_types', $post_types ) ) ) { 
  255. return; 
  256.  
  257. // Trigger a caching 
  258. if ( ! empty( $post->post_content ) ) { 
  259. $this->post_ID = $post->ID; 
  260. $this->usecache = false; 
  261.  
  262. $content = $this->run_shortcode( $post->post_content ); 
  263. $this->autoembed( $content ); 
  264.  
  265. $this->usecache = true; 
  266.  
  267. /** 
  268. * Passes any unlinked URLs that are on their own line to WP_Embed::shortcode() for potential embedding. 
  269. * @see WP_Embed::autoembed_callback() 
  270. * @param string $content The content to be searched. 
  271. * @return string Potentially modified $content. 
  272. */ 
  273. public function autoembed( $content ) { 
  274. // Replace line breaks from all HTML elements with placeholders. 
  275. $content = wp_replace_in_html_tags( $content, array( "\n" => '<!-- wp-line-break -->' ) ); 
  276.  
  277. if ( preg_match( '#(^|\s|>)https?://#i', $content ) ) { 
  278. // Find URLs on their own line. 
  279. $content = preg_replace_callback( '|^(\s*)(https?://[^\s<>"]+)(\s*)$|im', array( $this, 'autoembed_callback' ), $content ); 
  280. // Find URLs in their own paragraph. 
  281. $content = preg_replace_callback( '|(<p(?: [^>]*)?>\s*)(https?://[^\s<>"]+)(\s*<\/p>)|i', array( $this, 'autoembed_callback' ), $content ); 
  282.  
  283. // Put the line breaks back. 
  284. return str_replace( '<!-- wp-line-break -->', "\n", $content ); 
  285.  
  286. /** 
  287. * Callback function for WP_Embed::autoembed(). 
  288. * @param array $match A regex match array. 
  289. * @return string The embed HTML on success, otherwise the original URL. 
  290. */ 
  291. public function autoembed_callback( $match ) { 
  292. $oldval = $this->linkifunknown; 
  293. $this->linkifunknown = false; 
  294. $return = $this->shortcode( array(), $match[2] ); 
  295. $this->linkifunknown = $oldval; 
  296.  
  297. return $match[1] . $return . $match[3]; 
  298.  
  299. /** 
  300. * Conditionally makes a hyperlink based on an internal class variable. 
  301. * @param string $url URL to potentially be linked. 
  302. * @return false|string Linked URL or the original URL. False if 'return_false_on_fail' is true. 
  303. */ 
  304. public function maybe_make_link( $url ) { 
  305. if ( $this->return_false_on_fail ) { 
  306. return false; 
  307.  
  308. $output = ( $this->linkifunknown ) ? '<a href="' . esc_url($url) . '">' . esc_html($url) . '</a>' : $url; 
  309.  
  310. /** 
  311. * Filters the returned, maybe-linked embed URL. 
  312. * @since 2.9.0 
  313. * @param string $output The linked or original URL. 
  314. * @param string $url The original URL. 
  315. */ 
  316. return apply_filters( 'embed_maybe_make_link', $output, $url );