[wp-trac] [WordPress Trac] #63220: Documentation for embed_oembed_html misleading

[WordPress Trac]

#63220: Documentation for embed_oembed_html misleading
--------------------------+-----------------------------
 Reporter:  apermo        |      Owner:  (none)
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  Embeds        |    Version:  2.9
 Severity:  normal        |   Keywords:
  Focuses:                |
--------------------------+-----------------------------
 {{{#!php
 <?php
 if ( ! empty( $cache ) ) {
         /**
          * Filters the cached oEmbed HTML.
          *
          * @since 2.9.0
          *
          * @see WP_Embed::shortcode()
          *
          * @param string|false $cache   The cached HTML result, stored in
 post meta.
          * @param string       $url     The attempted embed URL.
          * @param array        $attr    An array of shortcode attributes.
          * @param int          $post_id Post ID.
          */
         return apply_filters( 'embed_oembed_html', $cache, $url, $attr,
 $post_id );
 }
 }}}

 {{{#!php
 <?php
 if ( $html ) {
         /** This filter is documented in wp-includes/class-wp-embed.php */
         return apply_filters( 'embed_oembed_html', $html, $url, $attr,
 $post_id );
 }
 }}}

 While the documentation suggests that `$cache`/`$html` can be `false` or a
 `string`, it can't be `false` and even not an empty string.

 This is misleading, we wanted to create a filter for that and added type
 hints to our filter and were unsure about the type. After reading the code
 we found that it was misleading.

 I will open a PR for this.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/63220>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform