[wp-trac] [WordPress Trac] #24202: Self-explanatory argument values for new media functions

[WordPress Trac]

#24202: Self-explanatory argument values for new media functions
------------------------------------+--------------------
 Reporter:  SergeyBiryukov          |       Owner:
     Type:  enhancement             |      Status:  new
 Priority:  high                    |   Milestone:  3.6
Component:  Media                   |     Version:  trunk
 Severity:  major                   |  Resolution:
 Keywords:  dev-feedback has-patch  |
------------------------------------+--------------------

Comment (by nacin):

 I'm currently toying with [attachment:24202.6.diff]:

  * Removes *all* `limit` arguments. For functions that return all by
 default, these make it more difficult for us to modify these functions in
 the future, as the order in which we extract/gather matters. Easier to
 just return everything and let them splice up the array. For the functions
 that return only one thing, a simple `reset()` is sufficient. Note that
 `reset()` returns false when the array is empty, which is fine (but not
 fully documented in `@return` at this time).

  * Renames get_content_url() to get_url_in_content(). markjaquith,
 koopersmith, and I came up with `get_url_from_post_content()`
 [http://make.wordpress.org/core/2013/05/29/post-formats-ui-is-exiting-
 core-will-live-as-a-plugin/ originally], and we can still experiment. But,
 this is still a step forward.

  * Removes get_content_media(), get_content_audio(), get_content_video().
 Matching the [audio] and [video] shortcodes is not a priority, and it also
 misses things like the [embed] shortcode and oEmbed in general. Maybe
 these just needed better names, but it doesn't make sense to have these
 functions at this point.

  * get_embedded_media() becomes get_media_embedded_in_content(). While
 this also ignores oEmbed (not sure if oEmbed is more "content" media or
 "embedded" media — it's kind of both), the name helps make this more of a
 utility function for tag parsing — as does the reliance on a blob of
 content, and not a post ID. Support for a single line URL is removed
 (doesn't make sense to support this with the demise of PFUI, especially
 given that oEmbed — a similar concept — is unsupported). This function now
 searches for ''both'' audio and video, and get_content_audio() and
 get_content_video() is removed because they're not as useful anymore.
 get_embedded_media() could also return <iframe>, <embed>, and <object>,
 which could have been audio, video, or something else entirely. Let's keep
 the utility function, and go with something more generic.

  * get_attached_image_srcs() is also gone. Given get_attached_media(),
 there's not a huge need for this too.

  * get_content_images() is now get_images_in_content().
 get_image_in_content() is now get_image_in_content(). Again — these are
 kept to content blobs only, not a post, to make them as generic helpers as
 possible. If we want to add more functionality in the future, these won't
 constrain us.

  * get_content_galleries() is gone. Galleries are intrinsic to a post. It
 is now merged with get_post_galleries(), which now has a filter (see
 #24309). get_post_gallery() returns the first gallery from
 get_post_galleries().

  * get_post_galleries_images() and get_post_gallery_images() are still
 there. I actually think that get_post_galleries_images() should return a
 flat array... As in, all images in all galleries. If you wanted individual
 per-gallery stuff, you can just call get_post_galleries() yourself.

 By simplifying the function arguments — everything accepts $post or
 $content, and some also accept $html = true — I don't think we need to go
 with the array-style callback.

 If we'd like to be compatible in the future, we should just make the
 second argument an array. But since it is currently a boolean, we can
 convert the function prototype to be an array later on.

--
Ticket URL: <http://core.trac.wordpress.org/ticket/24202#comment:16>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software