Changeset 49620

Timestamp:

11/16/2020 11:11:21 PM (4 years ago)

Author:

helen

Message:

Embeds: Document $args in wp_oembed_get().

Props hellofromTonya, audrasjb, SergeyBiryukov.
Fixes #51269.

File:

• trunk/src/wp-includes/class-wp-oembed.php (modified) (7 diffs)

trunk/src/wp-includes/class-wp-oembed.php

@@ -238 +238 @@
      *
      * @param string       $url  The URL to the content.
-     * @param string|array $args Optional provider arguments.
+     * @param string|array $args {
+     *     Optional. Additional arguments and parameters for retrieving embed HTML. Default empty.
+     *
+     *     @type bool $discover Optional. Determines whether to attempt to discover link tags at the given URL
+     *                          for an oEmbed provider when the oEmbed provider URL is not found in the
+     *                          built-in providers list.
+     * }
      * @return string|false The oEmbed provider URL on success, false on failure.
      */
@@ -329 +335 @@
      *
      * @param string       $url  The URL to the content that should be attempted to be embedded.
-     * @param array|string $args Optional. Arguments, usually passed from a shortcode. Default empty.
+     * @param string|array $args {
+     *     Optional. Additional arguments and parameters for retrieving embed HTML. Default empty.
+     *
+     *     @type int|string $width    Optional. The "maxwidth" value passed to the provider URL.
+     *     @type int|string $height   Optional. The "maxheight" value passed to the provider URL.
+     *     @type bool       $discover Optional. Determines whether to attempt to discover link tags
+     *                                at the given URL for an oEmbed provider when the oEmbed
+     *                                provider URL is not found in the built-in providers list.
+     * }
      * @return object|false The result in the form of an object on success, false on failure.
      */
@@ -359 +373 @@
      *
      * @param string       $url  The URL to the content that should be attempted to be embedded.
-     * @param array|string $args Optional. Arguments, usually passed from a shortcode. Default empty.
-     * @return string|false The UNSANITIZED (and potentially unsafe) HTML that should be used to embed on success,
-     *                      false on failure.
+     * @param string|array $args {
+     *     Optional. Additional arguments and parameters for retrieving embed HTML. Default empty.
+     *
+     *     @type int|string $width    Optional. The "maxwidth" value passed to the provider URL.
+     *     @type int|string $height   Optional. The "maxheight" value passed to the provider URL.
+     *     @type bool       $discover Optional. Determines whether to attempt to discover link tags
+     *                                at the given URL for an oEmbed provider when the oEmbed
+     *                                provider URL is not found in the built-in providers list.
+     * }
+     * @return string|false The UNSANITIZED (and potentially unsafe) HTML that should be used to embed
+     *                      on success, false on failure.
      */
     public function get_html( $url, $args = '' ) {
@@ -375 +397 @@
          * @since 4.5.3
          *
-         * @param null|string $result The UNSANITIZED (and potentially unsafe) HTML that should be used to embed.
-         *                            Default null to continue retrieving the result.
-         * @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.
+         * @param null|string  $result The UNSANITIZED (and potentially unsafe) HTML that should be used to embed.
+         *                             Default null to continue retrieving the result.
+         * @param string       $url    The URL to the content that should be attempted to be embedded.
+         * @param string|array $args   {
+         *     Optional. Additional arguments and parameters for retrieving embed HTML. Default empty.
+         *
+         *     @type int|string $width    Optional. The "maxwidth" value passed to the provider URL.
+         *     @type int|string $height   Optional. The "maxheight" value passed to the provider URL.
+         *     @type bool       $discover Optional. Determines whether to attempt to discover link tags
+         *                                at the given URL for an oEmbed provider when the oEmbed
+         *                                provider URL is not found in the built-in providers list.
+         * }
          */
         $pre = apply_filters( 'pre_oembed_result', null, $url, $args );
@@ -399 +429 @@
          * @param string|false $data The returned oEmbed HTML (false if unsafe).
          * @param string       $url  URL of the content to be embedded.
-         * @param array        $args Optional arguments, usually passed from a shortcode.
+         * @param string|array $args {
+         *     Optional. Additional arguments and parameters for retrieving embed HTML. Default empty.
+         *
+         *     @type int|string $width    Optional. The "maxwidth" value passed to the provider URL.
+         *     @type int|string $height   Optional. The "maxheight" value passed to the provider URL.
+         *     @type bool       $discover Optional. Determines whether to attempt to discover link tags
+         *                                at the given URL for an oEmbed provider when the oEmbed
+         *                                provider URL is not found in the built-in providers list.
+         * }
          */
         return apply_filters( 'oembed_result', $this->data2html( $data, $url ), $url, $args );
@@ -501 +539 @@
      * @param string       $provider The URL to the oEmbed provider.
      * @param string       $url      The URL to the content that is desired to be embedded.
-     * @param array|string $args     Optional. Arguments, usually passed from a shortcode. Default empty.
+     * @param string|array $args     {
+     *     Optional. Additional arguments and parameters for retrieving embed HTML. Default empty.
+     *
+     *     @type int|string $width    Optional. The "maxwidth" value passed to the provider URL.
+     *     @type int|string $height   Optional. The "maxheight" value passed to the provider URL.
+     *     @type bool       $discover Optional. Determines whether to attempt to discover link tags
+     *                                at the given URL for an oEmbed provider when the oEmbed
+     *                                provider URL is not found in the built-in providers list.
+     * }
      * @return object|false The result in the form of an object on success, false on failure.
      */
@@ -518 +564 @@
          * @since 4.9.0 The `dnt` (Do Not Track) query parameter was added to all oEmbed provider URLs.
          *
-         * @param string $provider URL of the oEmbed provider.
-         * @param string $url      URL of the content to be embedded.
-         * @param array  $args     Optional arguments, usually passed from a shortcode.
+         * @param string $provider       URL of the oEmbed provider.
+         * @param string $url            URL of the content to be embedded.
+         * @param string|array $args     {
+         *     Optional. Additional arguments and parameters for retrieving embed HTML. Default empty.
+         *
+         *     @type int|string $width    Optional. The "maxwidth" value passed to the provider URL.
+         *     @type int|string $height   Optional. The "maxheight" value passed to the provider URL.
+         *     @type bool       $discover Optional. Determines whether to attempt to discover link tags
+         *                                at the given URL for an oEmbed provider when the oEmbed
+         *                                provider URL is not found in the built-in providers list.
+         * }
          */
         $provider = apply_filters( 'oembed_fetch_url', $provider, $url, $args );