sergiotarxz/Wordpress
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Media: Standardise the description for image size parameters.

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

Props dilipbheda, johnbillion

Fixes #47364


git-svn-id: https://develop.svn.wordpress.org/trunk@49021 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
John Blackbourn 2020-09-20 16:21:42 +00:00
parent b620440519
commit dd076bb611
6 changed files with 94 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
src/wp-admin/includes/image.php
View File

@ -919,7 +919,8 @@ function file_is_displayable_image( $path ) {
*
* @param int $attachment_id Attachment ID.
* @param string $mime_type Image mime type.
* @param string $size Optional. Image size. Default 'full'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
* of width and height values in pixels (in that order). Default 'full'.
* @return resource|GdImage|false The resulting image resource or GdImage instance on success,
* false on failure.
*/
@ -952,7 +953,8 @@ function load_image_to_edit( $attachment_id, $mime_type, $size = 'full' ) {
*
* @param resource|GdImage $image Current image.
* @param int $attachment_id Attachment ID.
* @param string $size Image size.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
$image = apply_filters( 'load_image_to_edit', $image, $attachment_id, $size );
@ -975,8 +977,9 @@ function load_image_to_edit( $attachment_id, $mime_type, $size = 'full' ) {
* @access private
*
* @param int $attachment_id Attachment ID.
* @param string $size Optional. Image size. Default 'full'.
* @return string|false File path or url on success, false on failure.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
* of width and height values in pixels (in that order). Default 'full'.
* @return string|false File path or URL on success, false on failure.
*/
function _load_image_to_edit_path( $attachment_id, $size = 'full' ) {
$filepath = get_attached_file( $attachment_id );
@ -997,7 +1000,8 @@ function _load_image_to_edit_path( $attachment_id, $size = 'full' ) {
*
* @param string $path Path to the current image.
* @param int $attachment_id Attachment ID.
* @param string $size Size of the image.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
$filepath = apply_filters( 'load_image_to_edit_filesystempath', $filepath, $attachment_id, $size );
}
@ -1012,7 +1016,8 @@ function _load_image_to_edit_path( $attachment_id, $size = 'full' ) {
*
* @param string $image_url Current image URL.
* @param int $attachment_id Attachment ID.
* @param string $size Size of the image.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
$filepath = apply_filters( 'load_image_to_edit_attachmenturl', wp_get_attachment_url( $attachment_id ), $attachment_id, $size );
}
@ -1024,7 +1029,8 @@ function _load_image_to_edit_path( $attachment_id, $size = 'full' ) {
*
* @param string|bool $filepath File path or URL to current image, or false.
* @param int $attachment_id Attachment ID.
* @param string $size Size of the image.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
return apply_filters( 'load_image_to_edit_path', $filepath, $attachment_id, $size );
}

8
src/wp-admin/includes/media.php
View File

@ -125,8 +125,8 @@ function the_media_upload_tabs() {
* @param string $align Image CSS alignment property.
* @param string $url Optional. Image src URL. Default empty.
* @param bool|string $rel Optional. Value for rel attribute or whether to add a default value. Default false.
* @param string|array $size Optional. Image size. Accepts any valid image size, or an array of width
* and height values in pixels (in that order). Default 'medium'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
* width and height values in pixels (in that order). Default 'medium'.
* @param string $alt Optional. Image alt attribute. Default empty.
* @return string The HTML output to insert into the editor.
*/
@ -160,8 +160,8 @@ function get_image_send_to_editor( $id, $caption, $title, $align, $url = '', $re
* @param string $title The image title.
* @param string $align The image alignment.
* @param string $url The image source URL.
* @param string|array $size Size of image. Image size or array of width and height values
* (in that order). Default 'medium'.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
* @param string $alt The image alternative, or alt, text.
* @param string $rel The image rel attribute.
*/

9
src/wp-admin/includes/post.php
View File

@ -1536,15 +1536,12 @@ function _wp_post_thumbnail_html( $thumbnail_id = null, $post = null ) {
*
* Note: When a theme adds 'post-thumbnail' support, a special 'post-thumbnail'
* image size is registered, which differs from the 'thumbnail' image size
* managed via the Settings > Media screen. See the `$size` parameter description
* for more information on default values.
* managed via the Settings > Media screen.
*
* @since 4.4.0
*
* @param string|array $size Post thumbnail image size to display in the meta box. Accepts any valid
* image size, or an array of width and height values in pixels (in that order).
* If the 'post-thumbnail' size is set, default is 'post-thumbnail'. Otherwise,
* default is an array with 266 as both the height and width values.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
* @param int $thumbnail_id Post thumbnail attachment ID.
* @param WP_Post $post The post object associated with the thumbnail.
*/

96
src/wp-includes/media.php
View File

@ -46,9 +46,8 @@ function wp_get_additional_image_sizes() {
*
* @param int $width Width of the image in pixels.
* @param int $height Height of the image in pixels.
* @param string|array $size Optional. Image size. Accepts any valid image size, or an array
* of width and height values in pixels (in that order).
* Default 'medium'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
* of width and height values in pixels (in that order). Default 'medium'.
* @param string $context Optional. Could be 'display' (like in a theme) or 'edit'
* (like inserting into an editor). Default null.
* @return int[] {
@ -125,7 +124,8 @@ function image_constrain_size_for_editor( $width, $height, $size = 'medium', $co
* @type int $0 The maximum width in pixels.
* @type int $1 The maximum height in pixels.
* }
* @param string|array $size Size of what the result image should be.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
* @param string $context The context the image is being resized for.
* Possible values are 'display' (like in a theme)
* or 'edit' (like inserting into an editor).
@ -177,9 +177,8 @@ function image_hwstring( $width, $height ) {
* @since 2.5.0
*
* @param int $id Attachment ID for image.
* @param string|int[] $size Optional. Image size to scale to. Accepts any valid image size name,
* or an array of width and height values in pixels (in that order).
* Default 'medium'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
* of width and height values in pixels (in that order). Default 'medium'.
* @return array|false {
* Array of image data, or boolean false if no image is available.
*
@ -202,8 +201,8 @@ function image_downsize( $id, $size = 'medium' ) {
*
* @param bool|array $downsize Whether to short-circuit the image downsize.
* @param int $id Attachment ID for image.
* @param array|string $size Requested size of image. Image size name, or array of width
* and height values (in that order).
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
$out = apply_filters( 'image_downsize', false, $id, $size );
@ -367,9 +366,8 @@ function set_post_thumbnail_size( $width = 0, $height = 0, $crop = false ) {
* @param string $alt Image description for the alt attribute.
* @param string $title Image description for the title attribute.
* @param string $align Part of the class name for aligning the image.
* @param string|array $size Optional. Registered image size to retrieve a tag for. Accepts any
* valid image size, or an array of width and height values in pixels
* (in that order). Default 'medium'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
* width and height values in pixels (in that order). Default 'medium'.
* @return string HTML IMG element for given image attachment
*/
function get_image_tag( $id, $alt, $title, $align, $size = 'medium' ) {
@ -389,8 +387,8 @@ function get_image_tag( $id, $alt, $title, $align, $size = 'medium' ) {
* @param string $class CSS class name or space-separated list of classes.
* @param int $id Attachment ID.
* @param string $align Part of the class name for aligning the image.
* @param string|array $size Size of image. Image size or array of width and height values (in that order).
* Default 'medium'.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
$class = apply_filters( 'get_image_tag_class', $class, $id, $align, $size );
@ -406,8 +404,8 @@ function get_image_tag( $id, $alt, $title, $align, $size = 'medium' ) {
* @param string $alt Image description for the alt attribute.
* @param string $title Image description for the title attribute.
* @param string $align Part of the class name for aligning the image.
* @param string|array $size Size of image. Image size or array of width and height values (in that order).
* Default 'medium'.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
return apply_filters( 'get_image_tag', $html, $id, $alt, $title, $align, $size );
}
@ -744,9 +742,8 @@ function wp_image_matches_ratio( $source_width, $source_height, $target_width, $
* @since 2.5.0
*
* @param int $post_id Attachment ID.
* @param array|string $size Optional. Image size. Accepts any valid image size, or an array
* of width and height values in pixels (in that order).
* Default 'thumbnail'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
* of width and height values in pixels (in that order). Default 'thumbnail'.
* @return array|false {
* Array of file relative path, width, and height on success. Additionally includes absolute
* path and URL if registered size is passed to `$size` parameter. False on failure.
@ -844,9 +841,9 @@ function image_get_intermediate_size( $post_id, $size = 'thumbnail' ) {
*
* @param array $data Array of file relative path, width, and height on success. May also include
* file absolute path and URL.
* @param int $post_id The post_id of the image attachment
* @param string|array $size Registered image size or flat array of initially-requested height and width
* dimensions (in that order).
* @param int $post_id The ID of the image attachment.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
return apply_filters( 'image_get_intermediate_size', $data, $post_id, $size );
}
@ -938,8 +935,8 @@ function wp_get_registered_image_subsizes() {
* @since 2.5.0
*
* @param int $attachment_id Image attachment ID.
* @param string|int[] $size Optional. Image size. Accepts any valid image size name, or an array of width
* and height values in pixels (in that order). Default 'thumbnail'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
* width and height values in pixels (in that order). Default 'thumbnail'.
* @param bool $icon Optional. Whether the image should fall back to a mime type icon. Default false.
* @return array|false {
* Array of image data, or boolean false if no image is available.
@ -986,8 +983,8 @@ function wp_get_attachment_image_src( $attachment_id, $size = 'thumbnail', $icon
* @type bool $3 Whether the image is a resized image.
* }
* @param int $attachment_id Image attachment ID.
* @param string|int[] $size Requested size of image. Image size name, or array of width
* and height values (in that order).
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
* @param bool $icon Whether the image should be treated as an icon.
*/
return apply_filters( 'wp_get_attachment_image_src', $image, $attachment_id, $size, $icon );
@ -1006,8 +1003,8 @@ function wp_get_attachment_image_src( $attachment_id, $size = 'thumbnail', $icon
* @since 5.5.0 The `$loading` attribute was added.
*
* @param int $attachment_id Image attachment ID.
* @param string|array $size Optional. Image size. Accepts any valid image size, or an array of width
* and height values in pixels (in that order). Default 'thumbnail'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
* of width and height values in pixels (in that order). Default 'thumbnail'.
* @param bool $icon Optional. Whether the image should be treated as an icon. Default false.
* @param string|array $attr {
* Optional. Attributes for the image markup.
@ -1086,8 +1083,8 @@ function wp_get_attachment_image( $attachment_id, $size = 'thumbnail', $icon = f
* @param array $attr Array of attribute values for the image markup, keyed by attribute name.
* See wp_get_attachment_image().
* @param WP_Post $attachment Image attachment post.
* @param string|array $size Requested size. Image size or array of width and height values
* (in that order). Default 'thumbnail'.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
$attr = apply_filters( 'wp_get_attachment_image_attributes', $attr, $attachment, $size );
@ -1110,8 +1107,8 @@ function wp_get_attachment_image( $attachment_id, $size = 'thumbnail', $icon = f
* @since 4.4.0
*
* @param int $attachment_id Image attachment ID.
* @param string|array $size Optional. Image size to retrieve. Accepts any valid image size, or an array
* of width and height values in pixels (in that order). Default 'thumbnail'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
* width and height values in pixels (in that order). Default 'thumbnail'.
* @param bool $icon Optional. Whether the image should be treated as an icon. Default false.
* @return string|false Attachment URL or false if no image is available.
*/
@ -1186,7 +1183,7 @@ function _wp_get_image_size_from_meta( $size_name, $image_meta ) {
* @see wp_calculate_image_srcset()
*
* @param int $attachment_id Image attachment ID.
* @param array|string $size Optional. Image size. Accepts any valid image size, or an array of
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
* width and height values in pixels (in that order). Default 'medium'.
* @param array $image_meta Optional. The image meta data as returned by 'wp_get_attachment_metadata()'.
* Default null.
@ -1427,8 +1424,8 @@ function wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attac
* @see wp_calculate_image_sizes()
*
* @param int $attachment_id Image attachment ID.
* @param array|string $size Optional. Image size. Accepts any valid image size, or an array of width
* and height values in pixels (in that order). Default 'medium'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
* width and height values in pixels (in that order). Default 'medium'.
* @param array $image_meta Optional. The image meta data as returned by 'wp_get_attachment_metadata()'.
* Default null.
* @return string|bool A valid source size value for use in a 'sizes' attribute or false.
@ -1458,8 +1455,8 @@ function wp_get_attachment_image_sizes( $attachment_id, $size = 'medium', $image
*
* @since 4.4.0
*
* @param array|string $size Image size to retrieve. Accepts any valid image size, or an array
* of width and height values in pixels (in that order). Default 'medium'.
* @param string|int[] $size Image size. Accepts any registered image size name, or an array of
* width and height values in pixels (in that order).
* @param string $image_src Optional. The URL to the image file. Default null.
* @param array $image_meta Optional. The image meta data as returned by 'wp_get_attachment_metadata()'.
* Default null.
@ -1498,8 +1495,8 @@ function wp_calculate_image_sizes( $size, $image_src = null, $image_meta = null,
* @since 4.4.0
*
* @param string $sizes A source size value for use in a 'sizes' attribute.
* @param array|string $size Requested size. Image size or array of width and height values
* in pixels (in that order).
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
* @param string|null $image_src The URL to the image file or null.
* @param array|null $image_meta The image meta data as returned by wp_get_attachment_metadata() or null.
* @param int $attachment_id Image attachment ID of the original image or 0.
@ -2154,8 +2151,8 @@ add_shortcode( 'gallery', 'gallery_shortcode' );
* @type string $captiontag HTML tag to use for each image's caption.
* Default 'dd', or 'figcaption' when the theme registers HTML5 gallery support.
* @type int $columns Number of columns of images to display. Default 3.
* @type string|array $size Size of the images to display. Accepts any valid image size, or an array of width
* and height values in pixels (in that order). Default 'thumbnail'.
* @type string|int[] $size Size of the images to display. Accepts any registered image size name, or an array
* of width and height values in pixels (in that order). Default 'thumbnail'.
* @type string $ids A comma-separated list of IDs of attachments to display. Default empty.
* @type string $include A comma-separated list of IDs of attachments to include. Default empty.
* @type string $exclude A comma-separated list of IDs of attachments to exclude. Default empty.
@ -3282,9 +3279,8 @@ add_shortcode( 'video', 'wp_video_shortcode' );
*
* @see adjacent_image_link()
*
* @param string|array $size Optional. Image size. Accepts any valid image size, an array of width and
* height values in pixels (in that order), 0, or 'none'. 0 or 'none' will
* default to 'post_title' or `$text`. Default 'thumbnail'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
* of width and height values in pixels (in that order). Default 'thumbnail'.
* @param string $text Optional. Link text. Default false.
*/
function previous_image_link( $size = 'thumbnail', $text = false ) {
@ -3298,9 +3294,8 @@ function previous_image_link( $size = 'thumbnail', $text = false ) {
*
* @see adjacent_image_link()
*
* @param string|array $size Optional. Image size. Accepts any valid image size, an array of width and
* height values in pixels (in that order), 0, or 'none'. 0 or 'none' will
* default to 'post_title' or `$text`. Default 'thumbnail'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
* of width and height values in pixels (in that order). Default 'thumbnail'.
* @param string $text Optional. Link text. Default false.
*/
function next_image_link( $size = 'thumbnail', $text = false ) {
@ -3315,8 +3310,8 @@ function next_image_link( $size = 'thumbnail', $text = false ) {
* @since 2.5.0
*
* @param bool $prev Optional. Whether to display the next (false) or previous (true) link. Default true.
* @param string|array $size Optional. Image size. Accepts any valid image size, or an array of width and height
* values in pixels (in that order). Default 'thumbnail'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
* of width and height values in pixels (in that order). Default 'thumbnail'.
* @param bool $text Optional. Link text. Default false.
*/
function adjacent_image_link( $prev = true, $size = 'thumbnail', $text = false ) {
@ -3364,7 +3359,8 @@ function adjacent_image_link( $prev = true, $size = 'thumbnail', $text = false )
*
* @param string $output Adjacent image HTML markup.
* @param int $attachment_id Attachment ID
* @param string $size Image size.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
* @param string $text Link text.
*/
echo apply_filters( "{$adjacent}_image_link", $output, $attachment_id, $size, $text );

9
src/wp-includes/post-template.php
View File

@ -1596,9 +1596,8 @@ function the_attachment_link( $id = 0, $fullsize = false, $deprecated = false, $
* @since 4.4.0 The `$id` parameter can now accept either a post ID or `WP_Post` object.
*
* @param int|WP_Post $id Optional. Post ID or post object.
* @param string|array $size Optional. Image size. Accepts any valid image size, or an array
* of width and height values in pixels (in that order).
* Default 'thumbnail'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
* of width and height values in pixels (in that order). Default 'thumbnail'.
* @param bool $permalink Optional. Whether to add permalink to image. Default false.
* @param bool $icon Optional. Whether the attachment is an icon. Default false.
* @param string|false $text Optional. Link text to use. Activated by passing a string, false otherwise.
@ -1642,8 +1641,8 @@ function wp_get_attachment_link( $id = 0, $size = 'thumbnail', $permalink = fals
*
* @param string $link_html The page link HTML output.
* @param int $id Post ID.
* @param string|array $size Size of the image. Image size or array of width and height values (in that order).
* Default 'thumbnail'.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
* @param bool $permalink Whether to add permalink to image. Default false.
* @param bool $icon Whether to include an icon.
* @param string|bool $text If string, will be link text.

26
src/wp-includes/post-thumbnail-template.php
View File

@ -74,9 +74,8 @@ function get_post_thumbnail_id( $post = null ) {
*
* @see get_the_post_thumbnail()
*
* @param string|array $size Optional. Image size to use. Accepts any valid image size, or
* an array of width and height values in pixels (in that order).
* Default 'post-thumbnail'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
* width and height values in pixels (in that order). Default 'post-thumbnail'.
* @param string|array $attr Optional. Query string or array of attributes. Default empty.
*/
function the_post_thumbnail( $size = 'post-thumbnail', $attr = '' ) {
@ -131,9 +130,8 @@ function update_post_thumbnail_cache( $wp_query = null ) {
* @since 4.4.0 `$post` can be a post ID or WP_Post object.
*
* @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
* @param string|array $size Optional. Image size to use. Accepts any valid image size, or
* an array of width and height values in pixels (in that order).
* Default 'post-thumbnail'.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
* width and height values in pixels (in that order). Default 'post-thumbnail'.
* @param string|array $attr Optional. Query string or array of attributes. Default empty.
* @return string The post thumbnail image tag.
*/
@ -152,8 +150,8 @@ function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr =
* @since 2.9.0
* @since 4.9.0 Added the `$post_id` parameter.
*
* @param string|array $size The post thumbnail size. Image size or array of width and height
* values (in that order). Default 'post-thumbnail'.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
* @param int $post_id The post ID.
*/
$size = apply_filters( 'post_thumbnail_size', $size, $post->ID );
@ -169,8 +167,8 @@ function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr =
*
* @param int $post_id The post ID.
* @param int $post_thumbnail_id The post thumbnail ID.
* @param string|array $size The post thumbnail size. Image size or array of width
* and height values (in that order). Default 'post-thumbnail'.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
do_action( 'begin_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
@ -187,8 +185,8 @@ function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr =
*
* @param int $post_id The post ID.
* @param int $post_thumbnail_id The post thumbnail ID.
* @param string|array $size The post thumbnail size. Image size or array of width
* and height values (in that order). Default 'post-thumbnail'.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
do_action( 'end_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
@ -204,8 +202,8 @@ function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr =
* @param string $html The post thumbnail HTML.
* @param int $post_id The post ID.
* @param int $post_thumbnail_id The post thumbnail ID.
* @param string|array $size The post thumbnail size. Image size or array of width and height
* values (in that order). Default 'post-thumbnail'.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
* @param string $attr Query string of attributes.
*/
return apply_filters( 'post_thumbnail_html', $html, $post->ID, $post_thumbnail_id, $size, $attr );