Wordpress 4.6
[autoinstalls/wordpress.git] / wp-includes / class-oembed.php
index 909524bc301bcf378a2b73abdb909c5f6f9f696b..9790d266f67b6532410ac24adcb16df80f3331a2 100644 (file)
@@ -38,7 +38,7 @@ class WP_oEmbed {
        public static $early_providers = array();
 
        /**
-        * A list of private/protected methods, used for backwards compatibility.
+        * A list of private/protected methods, used for backward compatibility.
         *
         * @since 4.2.0
         * @access private
@@ -115,7 +115,7 @@ class WP_oEmbed {
                self::$early_providers = array();
 
                /**
-                * Filter the list of whitelisted oEmbed providers.
+                * Filters the list of whitelisted oEmbed providers.
                 *
                 * Since WordPress 4.4, oEmbed discovery is enabled for all users and allows embedding of sanitized
                 * iframes. The providers in this list are whitelisted, meaning they are trusted and allowed to
@@ -192,7 +192,7 @@ class WP_oEmbed {
        }
 
        /**
-        * Exposes private/protected methods for backwards compatibility.
+        * Exposes private/protected methods for backward compatibility.
         *
         * @since 4.0.0
         * @access public
@@ -221,6 +221,7 @@ class WP_oEmbed {
         * @return false|string False on failure, otherwise the oEmbed provider URL.
         */
        public function get_provider( $url, $args = '' ) {
+               $args = wp_parse_args( $args );
 
                $provider = false;
 
@@ -315,13 +316,37 @@ class WP_oEmbed {
         * @return false|string False on failure, otherwise the UNSANITIZED (and potentially unsafe) HTML that should be used to embed.
         */
        public function get_html( $url, $args = '' ) {
+               $args = wp_parse_args( $args );
+
+               /**
+                * Filters the oEmbed result before any HTTP requests are made.
+                *
+                * This allows one to short-circuit the default logic, perhaps by
+                * replacing it with a routine that is more optimal for your setup.
+                *
+                * Passing a non-null value to the filter will effectively short-circuit retrieval,
+                * returning the passed value instead.
+                *
+                * @since 4.5.3
+                *
+                * @param null|string $result The UNSANITIZED (and potentially unsafe) HTML that should be used to embed. Default null.
+                * @param string      $url    The URL to the content that should be attempted to be embedded.
+                * @param array       $args   Optional. Arguments, usually passed from a shortcode. Default empty.
+                */
+               $pre = apply_filters( 'pre_oembed_result', null, $url, $args );
+
+               if ( null !== $pre ) {
+                       return $pre;
+               }
+
                $provider = $this->get_provider( $url, $args );
 
-               if ( !$provider || false === $data = $this->fetch( $provider, $url, $args ) )
+               if ( ! $provider || false === $data = $this->fetch( $provider, $url, $args ) ) {
                        return false;
+               }
 
                /**
-                * Filter the HTML returned by the oEmbed provider.
+                * Filters the HTML returned by the oEmbed provider.
                 *
                 * @since 2.9.0
                 *
@@ -348,7 +373,7 @@ class WP_oEmbed {
                );
 
                /**
-                * Filter oEmbed remote get arguments.
+                * Filters oEmbed remote get arguments.
                 *
                 * @since 4.0.0
                 *
@@ -364,7 +389,7 @@ class WP_oEmbed {
                if ( $html = wp_remote_retrieve_body( $request ) ) {
 
                        /**
-                        * Filter the link types that contain oEmbed provider URLs.
+                        * Filters the link types that contain oEmbed provider URLs.
                         *
                         * @since 2.9.0
                         *
@@ -435,7 +460,7 @@ class WP_oEmbed {
                $provider = add_query_arg( 'url', urlencode($url), $provider );
 
                /**
-                * Filter the oEmbed URL to be fetched.
+                * Filters the oEmbed URL to be fetched.
                 *
                 * @since 2.9.0
                 *
@@ -598,7 +623,7 @@ class WP_oEmbed {
                }
 
                /**
-                * Filter the returned oEmbed HTML.
+                * Filters the returned oEmbed HTML.
                 *
                 * Use this filter to add support for custom data types, or to filter the result.
                 *