Make WordPress Core

Opened 5 months ago

Last modified 7 weeks ago

#47364 new enhancement

Docs: Standardise the description for image size parameters

Reported by: johnbillion Owned by:
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: Media Keywords: has-patch
Focuses: docs Cc:
PR Number:


Many functions and hooks in WordPress provide a parameter which accepts an image size value, which can almost always be a registered image size name or an array of width/height dimensions. The documentation for these parameters is inconsistent which makes the accepted values confusing to developers.

Let's standardise the description of any parameter which accepts an image size.

Relevant Functions

  • _load_image_to_edit_path()
  • _wp_get_image_size_from_meta()
  • adjacent_image_link()
  • get_the_post_thumbnail()
  • image_add_caption() (parameter isn't used)
  • image_constrain_size_for_editor()
  • image_downsize()
  • image_get_intermediate_size()
  • load_image_to_edit()
  • next_image_link()
  • previous_image_link()
  • the_post_thumbnail()
  • wp_calculate_image_sizes()
  • wp_get_attachment_image_sizes()
  • wp_get_attachment_image_src()
  • wp_get_attachment_image_srcset()
  • wp_get_attachment_image_url()
  • wp_get_attachment_image()
  • wp_get_attachment_link()

The following functions only accept a registered image size name, not an array of width/height dimensions:

  • _wp_get_image_size_from_meta()
  • gallery_shortcode() ($attr['size'] parameter) because the value gets passed to sanitize_html_class()
  • get_image_send_to_editor() because the value gets passed to get_image_tag()
  • get_image_tag() because the value gets directly used as an HTML attribute

Relevant Hooks

  • {$adjacent}_image_link
  • admin_post_thumbnail_size
  • begin_fetch_post_thumbnail_html
  • editor_max_image_size
  • end_fetch_post_thumbnail_html
  • get_the_post_thumbnail_url
  • image_downsize
  • image_get_intermediate_size
  • load_image_to_edit_attachmenturl
  • load_image_to_edit_filesystempath
  • load_image_to_edit_path
  • load_image_to_edit
  • post_thumbnail_html
  • post_thumbnail_size
  • the_post_thumbnail_url
  • wp_calculate_image_sizes
  • wp_get_attachment_image_attributes
  • wp_get_attachment_image_src
  • wp_get_attachment_link

The following hooks won't pass an array of width/height dimensions because the value comes from get_image_tag():

  • get_image_tag_class
  • get_image_tag
  • image_send_to_editor

Accepted Values

The following values are accepted by all parameters that accept an image size (except the exceptions noted above):

  • full
  • large
  • medium
  • medium_large
  • thumbnail
  • Any custom registered image size name
  • An array of width/height dimensions

In addition there is a post-thumbnail image size referenced in a few places but its source and usage is not clear, I haven't looked into it yet.

Attachments (1)

47364.patch (7.4 KB) - added by dilipbheda 4 months ago.
Changed few functions description.

Download all attachments as: .zip

Change History (3)

4 months ago

Changed few functions description.

This ticket was mentioned in Slack in #core-media by desrosj. View the logs.

7 weeks ago

#2 @joemcgill
7 weeks ago

  • Keywords has-patch added; needs-patch removed
  • Milestone changed from Awaiting Review to Future Release

Thanks for the suggestion @johnbillion and for going through all of these functions/hooks. For clarification, are you suggesting that only the docs need to be updated to be more accurate here, or that we need to adjust the actual function signatures in order to bring more consistency to these functions overall?

Note: See TracTickets for help on using tickets.