Make WordPress Core

Opened 15 months ago

Last modified 5 months 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:


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 14 months ago.
Changed few functions description.

Download all attachments as: .zip

Change History (4)

14 months ago

Changed few functions description.

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

11 months ago

#2 @joemcgill
11 months 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?

#3 @SergeyBiryukov
5 months ago

Crossposting a comment by @marekdedic from comment:71:ticket:48303:

Hi, I started by looking at the function get_the_post_thumbnail and its parameter $size, which is currently of the type string|array. I think this could be narrowed down to string|int[] by examining its source and all the functions and hooks it calls. As such, I think these functions and hooks could have their parameter $size narrowed in the same way. The ones I encountered:


  • get_the_post_thumbnail
  • wp_get_attachment_image
  • wp_get_attachment_image_src
  • image_downsize
  • image_get_intermediate_size
  • image_constrain_size_for_editor


  • begin_fetch_post_thumbnail_html
  • end_fetch_post_thumbnail_html
  • wp_get_attachment_image_src
  • image_downsize
  • image_get_intermediate_size
  • editor_max_image_size

However, I'm pretty sure there are more.

Note: See TracTickets for help on using tickets.