Make WordPress Core

Opened 5 years ago

Closed 4 years ago

Last modified 4 years ago

#47364 closed enhancement (fixed)

Docs: Standardise the description for image size parameters

Reported by: johnbillion's profile johnbillion Owned by: johnbillion's profile johnbillion
Milestone: 5.6 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 5 years ago.
Changed few functions description.

Download all attachments as: .zip

Change History (9)

5 years ago

Changed few functions description.

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

5 years ago

#2 @joemcgill
5 years 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
4 years 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.

#4 @johnbillion
4 years ago

In 49016:

Media: Correct some types in docblocks for filters related to thumbnails.

Props dilipbheda

See #47364, #50768

#5 @johnbillion
4 years ago

In 49017:

Media: Correct some types for attachment ID parameters passed to functions and filters.

See #47364, #50768

#6 @johnbillion
4 years ago

In 49020:

Docs: Inline documentation improvements for media related functions and hooks.

See #47364, #50768

#7 @johnbillion
4 years ago

  • Owner set to johnbillion
  • Resolution set to fixed
  • Status changed from new to closed

In 49021:

Media: Standardise the description for image size parameters.

This brings continuity to all the image related functions and filters which accept or pass a size parameter.

Props dilipbheda, johnbillion

Fixes #47364

#8 @johnbillion
4 years ago

  • Milestone changed from Future Release to 5.6
Note: See TracTickets for help on using tickets.