Document the $args parameter of wp_oembed_get()

[SergeyBiryukov]

Reported by @vakho114 on ​support forums.

wp_oembed_get() has an $args parameter, but it's not clarified which arguments exactly can be accepted.

Looking at the code, the array is passed to a few WP_oEmbed methods:

• WP_oEmbed::get_html()
• WP_oEmbed::get_data()
• WP_oEmbed::get_provider()
• WP_oEmbed::fetch()

In WP_oEmbed::get_provider(), the value of $args['discover'] determines whether to call the ::discover() method if the oEmbed provider URL is not found in the built-in providers list.

In WP_oEmbed::fetch(), $args is merged with wp_embed_defaults(), then $args['width'] and $args['height'] are passed to the provider URL.

So it looks like while any custom parameters can be passed, only width, height, and discover are supported by default and should be documented as such.

[hellofromTonya]

Documents the optional $args array elements to include width, height, and discovery.

[hellofromTonya]

Documented the args per @SergeyBiryukov's notes for each method and filter.

[audrasjb]

patch refreshed against trunk

[audrasjb]

Hey there, 51269.3.diff refreshes the previous patch against trunk and adds few docblock fixes concerning whitespaces et al :)

Otherwise, the changes make sense to me and look good to go.

[hellofromTonya]

@SergeyBiryukov Can you do a code review of 51269.3.diff? Let us know if there are any other changes needed.

[helen]

In 49620:

Embeds: Document $args in wp_oembed_get().

Props hellofromTonya, audrasjb, SergeyBiryukov.
Fixes #51269.

[SergeyBiryukov]

In 49626:

Docs: Document the $args parameter of wp_oembed_get().

Link to wp_oembed_get() as the canonical source when documenting additional arguments in various WP_oEmbed methods.

Follow-up to [49620].

See #51269.