WordPress.org

Make WordPress Core

Changeset 49021


Ignore:
Timestamp:
09/20/2020 04:21:42 PM (5 months ago)
Author:
johnbillion
Message:

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

Location:
trunk/src
Files:
6 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/image.php

    r49020 r49021  
    918918 * @since 2.9.0
    919919 *
    920  * @param int    $attachment_id Attachment ID.
    921  * @param string $mime_type     Image mime type.
    922  * @param string $size          Optional. Image size. Default 'full'.
     920 * @param int          $attachment_id Attachment ID.
     921 * @param string       $mime_type     Image mime type.
     922 * @param string|int[] $size          Optional. Image size. Accepts any registered image size name, or an array
     923 *                                    of width and height values in pixels (in that order). Default 'full'.
    923924 * @return resource|GdImage|false The resulting image resource or GdImage instance on success,
    924925 *                                false on failure.
     
    953954         * @param resource|GdImage $image         Current image.
    954955         * @param int              $attachment_id Attachment ID.
    955          * @param string           $size          Image size.
     956         * @param string|int[]     $size          Requested image size. Can be any registered image size name, or
     957         *                                        an array of width and height values in pixels (in that order).
    956958         */
    957959        $image = apply_filters( 'load_image_to_edit', $image, $attachment_id, $size );
     
    975977 * @access private
    976978 *
    977  * @param int    $attachment_id Attachment ID.
    978  * @param string $size          Optional. Image size. Default 'full'.
    979  * @return string|false File path or url on success, false on failure.
     979 * @param int          $attachment_id Attachment ID.
     980 * @param string|int[] $size          Optional. Image size. Accepts any registered image size name, or an array
     981 *                                    of width and height values in pixels (in that order). Default 'full'.
     982 * @return string|false File path or URL on success, false on failure.
    980983 */
    981984function _load_image_to_edit_path( $attachment_id, $size = 'full' ) {
     
    996999                 * @since 3.1.0
    9971000                 *
    998                  * @param string $path          Path to the current image.
    999                  * @param int    $attachment_id Attachment ID.
    1000                  * @param string $size          Size of the image.
     1001                 * @param string       $path          Path to the current image.
     1002                 * @param int          $attachment_id Attachment ID.
     1003                 * @param string|int[] $size          Requested image size. Can be any registered image size name, or
     1004                 *                                    an array of width and height values in pixels (in that order).
    10011005                 */
    10021006                $filepath = apply_filters( 'load_image_to_edit_filesystempath', $filepath, $attachment_id, $size );
     
    10111015         * @since 3.1.0
    10121016         *
    1013          * @param string $image_url     Current image URL.
    1014          * @param int    $attachment_id Attachment ID.
    1015          * @param string $size          Size of the image.
     1017         * @param string       $image_url     Current image URL.
     1018         * @param int          $attachment_id Attachment ID.
     1019         * @param string|int[] $size          Requested image size. Can be any registered image size name, or
     1020         *                                    an array of width and height values in pixels (in that order).
    10161021         */
    10171022        $filepath = apply_filters( 'load_image_to_edit_attachmenturl', wp_get_attachment_url( $attachment_id ), $attachment_id, $size );
     
    10231028     * @since 2.9.0
    10241029     *
    1025      * @param string|bool $filepath      File path or URL to current image, or false.
    1026      * @param int         $attachment_id Attachment ID.
    1027      * @param string      $size          Size of the image.
     1030     * @param string|bool  $filepath      File path or URL to current image, or false.
     1031     * @param int          $attachment_id Attachment ID.
     1032     * @param string|int[] $size          Requested image size. Can be any registered image size name, or
     1033     *                                    an array of width and height values in pixels (in that order).
    10281034     */
    10291035    return apply_filters( 'load_image_to_edit_path', $filepath, $attachment_id, $size );
  • trunk/src/wp-admin/includes/media.php

    r49020 r49021  
    126126 * @param string       $url     Optional. Image src URL. Default empty.
    127127 * @param bool|string  $rel     Optional. Value for rel attribute or whether to add a default value. Default false.
    128  * @param string|array $size    Optional. Image size. Accepts any valid image size, or an array of width
    129  *                              and height values in pixels (in that order). Default 'medium'.
     128 * @param string|int[] $size    Optional. Image size. Accepts any registered image size name, or an array of
     129 *                              width and height values in pixels (in that order). Default 'medium'.
    130130 * @param string       $alt     Optional. Image alt attribute. Default empty.
    131131 * @return string The HTML output to insert into the editor.
     
    161161     * @param string       $align   The image alignment.
    162162     * @param string       $url     The image source URL.
    163      * @param string|array $size    Size of image. Image size or array of width and height values
    164      *                              (in that order). Default 'medium'.
     163     * @param string|int[] $size    Requested image size. Can be any registered image size name, or
     164     *                              an array of width and height values in pixels (in that order).
    165165     * @param string       $alt     The image alternative, or alt, text.
    166166     * @param string       $rel     The image rel attribute.
  • trunk/src/wp-admin/includes/post.php

    r48782 r49021  
    15371537         * Note: When a theme adds 'post-thumbnail' support, a special 'post-thumbnail'
    15381538         * image size is registered, which differs from the 'thumbnail' image size
    1539          * managed via the Settings > Media screen. See the `$size` parameter description
    1540          * for more information on default values.
     1539         * managed via the Settings > Media screen.
    15411540         *
    15421541         * @since 4.4.0
    15431542         *
    1544          * @param string|array $size         Post thumbnail image size to display in the meta box. Accepts any valid
    1545          *                                   image size, or an array of width and height values in pixels (in that order).
    1546          *                                   If the 'post-thumbnail' size is set, default is 'post-thumbnail'. Otherwise,
    1547          *                                   default is an array with 266 as both the height and width values.
     1543         * @param string|int[] $size         Requested image size. Can be any registered image size name, or
     1544         *                                   an array of width and height values in pixels (in that order).
    15481545         * @param int          $thumbnail_id Post thumbnail attachment ID.
    15491546         * @param WP_Post      $post         The post object associated with the thumbnail.
  • trunk/src/wp-includes/media.php

    r49020 r49021  
    4747 * @param int          $width   Width of the image in pixels.
    4848 * @param int          $height  Height of the image in pixels.
    49  * @param string|array $size    Optional. Image size. Accepts any valid image size, or an array
    50  *                              of width and height values in pixels (in that order).
    51  *                              Default 'medium'.
     49 * @param string|int[] $size    Optional. Image size. Accepts any registered image size name, or an array
     50 *                              of width and height values in pixels (in that order). Default 'medium'.
    5251 * @param string       $context Optional. Could be 'display' (like in a theme) or 'edit'
    5352 *                              (like inserting into an editor). Default null.
     
    126125     *     @type int $1 The maximum height in pixels.
    127126     * }
    128      * @param string|array $size           Size of what the result image should be.
    129      * @param string       $context        The context the image is being resized for.
    130      *                                     Possible values are 'display' (like in a theme)
    131      *                                     or 'edit' (like inserting into an editor).
     127     * @param string|int[] $size     Requested image size. Can be any registered image size name, or
     128     *                               an array of width and height values in pixels (in that order).
     129     * @param string       $context  The context the image is being resized for.
     130     *                               Possible values are 'display' (like in a theme)
     131     *                               or 'edit' (like inserting into an editor).
    132132     */
    133133    list( $max_width, $max_height ) = apply_filters( 'editor_max_image_size', array( $max_width, $max_height ), $size, $context );
     
    178178 *
    179179 * @param int          $id   Attachment ID for image.
    180  * @param string|int[] $size Optional. Image size to scale to. Accepts any valid image size name,
    181  *                           or an array of width and height values in pixels (in that order).
    182  *                           Default 'medium'.
     180 * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
     181 *                           of width and height values in pixels (in that order). Default 'medium'.
    183182 * @return array|false {
    184183 *     Array of image data, or boolean false if no image is available.
     
    203202     * @param bool|array   $downsize Whether to short-circuit the image downsize.
    204203     * @param int          $id       Attachment ID for image.
    205      * @param array|string $size     Requested size of image. Image size name, or array of width
    206      *                               and height values (in that order).
     204     * @param string|int[] $size     Requested image size. Can be any registered image size name, or
     205     *                               an array of width and height values in pixels (in that order).
    207206     */
    208207    $out = apply_filters( 'image_downsize', false, $id, $size );
     
    368367 * @param string       $title Image description for the title attribute.
    369368 * @param string       $align Part of the class name for aligning the image.
    370  * @param string|array $size  Optional. Registered image size to retrieve a tag for. Accepts any
    371  *                            valid image size, or an array of width and height values in pixels
    372  *                            (in that order). Default 'medium'.
     369 * @param string|int[] $size  Optional. Image size. Accepts any registered image size name, or an array of
     370 *                           width and height values in pixels (in that order). Default 'medium'.
    373371 * @return string HTML IMG element for given image attachment
    374372 */
     
    390388     * @param int          $id    Attachment ID.
    391389     * @param string       $align Part of the class name for aligning the image.
    392      * @param string|array $size  Size of image. Image size or array of width and height values (in that order).
    393      *                            Default 'medium'.
     390     * @param string|int[] $size  Requested image size. Can be any registered image size name, or
     391     *                            an array of width and height values in pixels (in that order).
    394392     */
    395393    $class = apply_filters( 'get_image_tag_class', $class, $id, $align, $size );
     
    407405     * @param string       $title Image description for the title attribute.
    408406     * @param string       $align Part of the class name for aligning the image.
    409      * @param string|array $size  Size of image. Image size or array of width and height values (in that order).
    410      *                            Default 'medium'.
     407     * @param string|int[] $size  Requested image size. Can be any registered image size name, or
     408     *                            an array of width and height values in pixels (in that order).
    411409     */
    412410    return apply_filters( 'get_image_tag', $html, $id, $alt, $title, $align, $size );
     
    745743 *
    746744 * @param int          $post_id Attachment ID.
    747  * @param array|string $size    Optional. Image size. Accepts any valid image size, or an array
    748  *                              of width and height values in pixels (in that order).
    749  *                              Default 'thumbnail'.
     745 * @param string|int[] $size    Optional. Image size. Accepts any registered image size name, or an array
     746 *                              of width and height values in pixels (in that order). Default 'thumbnail'.
    750747 * @return array|false {
    751748 *     Array of file relative path, width, and height on success. Additionally includes absolute
     
    845842     * @param array        $data    Array of file relative path, width, and height on success. May also include
    846843     *                              file absolute path and URL.
    847      * @param int          $post_id The post_id of the image attachment
    848      * @param string|array $size    Registered image size or flat array of initially-requested height and width
    849      *                              dimensions (in that order).
     844     * @param int          $post_id The ID of the image attachment.
     845     * @param string|int[] $size    Requested image size. Can be any registered image size name, or
     846     *                              an array of width and height values in pixels (in that order).
    850847     */
    851848    return apply_filters( 'image_get_intermediate_size', $data, $post_id, $size );
     
    939936 *
    940937 * @param int          $attachment_id Image attachment ID.
    941  * @param string|int[] $size          Optional. Image size. Accepts any valid image size name, or an array of width
    942  *                                    and height values in pixels (in that order). Default 'thumbnail'.
     938 * @param string|int[] $size          Optional. Image size. Accepts any registered image size name, or an array of
     939 *                                    width and height values in pixels (in that order). Default 'thumbnail'.
    943940 * @param bool         $icon          Optional. Whether the image should fall back to a mime type icon. Default false.
    944941 * @return array|false {
     
    987984     * }
    988985     * @param int          $attachment_id Image attachment ID.
    989      * @param string|int[] $size          Requested size of image. Image size name, or array of width
    990      *                                    and height values (in that order).
     986     * @param string|int[] $size          Requested image size. Can be any registered image size name, or
     987     *                                    an array of width and height values in pixels (in that order).
    991988     * @param bool         $icon          Whether the image should be treated as an icon.
    992989     */
     
    10071004 *
    10081005 * @param int          $attachment_id Image attachment ID.
    1009  * @param string|array $size          Optional. Image size. Accepts any valid image size, or an array of width
    1010  *                                    and height values in pixels (in that order). Default 'thumbnail'.
     1006 * @param string|int[] $size          Optional. Image size. Accepts any registered image size name, or an array
     1007 *                                    of width and height values in pixels (in that order). Default 'thumbnail'.
    10111008 * @param bool         $icon          Optional. Whether the image should be treated as an icon. Default false.
    10121009 * @param string|array $attr {
     
    10871084         *                                 See wp_get_attachment_image().
    10881085         * @param WP_Post      $attachment Image attachment post.
    1089          * @param string|array $size       Requested size. Image size or array of width and height values
    1090          *                                 (in that order). Default 'thumbnail'.
     1086         * @param string|int[] $size       Requested image size. Can be any registered image size name, or
     1087         *                                 an array of width and height values in pixels (in that order).
    10911088         */
    10921089        $attr = apply_filters( 'wp_get_attachment_image_attributes', $attr, $attachment, $size );
     
    11111108 *
    11121109 * @param int          $attachment_id Image attachment ID.
    1113  * @param string|array $size          Optional. Image size to retrieve. Accepts any valid image size, or an array
    1114  *                                    of width and height values in pixels (in that order). Default 'thumbnail'.
     1110 * @param string|int[] $size          Optional. Image size. Accepts any registered image size name, or an array of
     1111 *                                    width and height values in pixels (in that order). Default 'thumbnail'.
    11151112 * @param bool         $icon          Optional. Whether the image should be treated as an icon. Default false.
    11161113 * @return string|false Attachment URL or false if no image is available.
     
    11871184 *
    11881185 * @param int          $attachment_id Image attachment ID.
    1189  * @param array|string $size          Optional. Image size. Accepts any valid image size, or an array of
     1186 * @param string|int[] $size          Optional. Image size. Accepts any registered image size name, or an array of
    11901187 *                                    width and height values in pixels (in that order). Default 'medium'.
    11911188 * @param array        $image_meta    Optional. The image meta data as returned by 'wp_get_attachment_metadata()'.
     
    14281425 *
    14291426 * @param int          $attachment_id Image attachment ID.
    1430  * @param array|string $size          Optional. Image size. Accepts any valid image size, or an array of width
    1431  *                                    and height values in pixels (in that order). Default 'medium'.
     1427 * @param string|int[] $size          Optional. Image size. Accepts any registered image size name, or an array of
     1428 *                                    width and height values in pixels (in that order). Default 'medium'.
    14321429 * @param array        $image_meta    Optional. The image meta data as returned by 'wp_get_attachment_metadata()'.
    14331430 *                                    Default null.
     
    14591456 * @since 4.4.0
    14601457 *
    1461  * @param array|string $size          Image size to retrieve. Accepts any valid image size, or an array
    1462  *                                    of width and height values in pixels (in that order). Default 'medium'.
     1458 * @param string|int[] $size          Image size. Accepts any registered image size name, or an array of
     1459 *                                    width and height values in pixels (in that order).
    14631460 * @param string       $image_src     Optional. The URL to the image file. Default null.
    14641461 * @param array        $image_meta    Optional. The image meta data as returned by 'wp_get_attachment_metadata()'.
     
    14991496     *
    15001497     * @param string       $sizes         A source size value for use in a 'sizes' attribute.
    1501      * @param array|string $size          Requested size. Image size or array of width and height values
    1502      *                                    in pixels (in that order).
     1498     * @param string|int[] $size          Requested image size. Can be any registered image size name, or
     1499     *                                    an array of width and height values in pixels (in that order).
    15031500     * @param string|null  $image_src     The URL to the image file or null.
    15041501     * @param array|null   $image_meta    The image meta data as returned by wp_get_attachment_metadata() or null.
     
    21552152 *                                    Default 'dd', or 'figcaption' when the theme registers HTML5 gallery support.
    21562153 *     @type int          $columns    Number of columns of images to display. Default 3.
    2157  *     @type string|array $size       Size of the images to display. Accepts any valid image size, or an array of width
    2158  *                                    and height values in pixels (in that order). Default 'thumbnail'.
     2154 *     @type string|int[] $size       Size of the images to display. Accepts any registered image size name, or an array
     2155 *                                    of width and height values in pixels (in that order). Default 'thumbnail'.
    21592156 *     @type string       $ids        A comma-separated list of IDs of attachments to display. Default empty.
    21602157 *     @type string       $include    A comma-separated list of IDs of attachments to include. Default empty.
     
    32833280 * @see adjacent_image_link()
    32843281 *
    3285  * @param string|array $size Optional. Image size. Accepts any valid image size, an array of width and
    3286  *                           height values in pixels (in that order), 0, or 'none'. 0 or 'none' will
    3287  *                           default to 'post_title' or `$text`. Default 'thumbnail'.
     3282 * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
     3283 *                           of width and height values in pixels (in that order). Default 'thumbnail'.
    32883284 * @param string       $text Optional. Link text. Default false.
    32893285 */
     
    32993295 * @see adjacent_image_link()
    33003296 *
    3301  * @param string|array $size Optional. Image size. Accepts any valid image size, an array of width and
    3302  *                           height values in pixels (in that order), 0, or 'none'. 0 or 'none' will
    3303  *                           default to 'post_title' or `$text`. Default 'thumbnail'.
     3297 * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
     3298 *                           of width and height values in pixels (in that order). Default 'thumbnail'.
    33043299 * @param string       $text Optional. Link text. Default false.
    33053300 */
     
    33163311 *
    33173312 * @param bool         $prev Optional. Whether to display the next (false) or previous (true) link. Default true.
    3318  * @param string|array $size Optional. Image size. Accepts any valid image size, or an array of width and height
    3319  *                           values in pixels (in that order). Default 'thumbnail'.
     3313 * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
     3314 *                           of width and height values in pixels (in that order). Default 'thumbnail'.
    33203315 * @param bool         $text Optional. Link text. Default false.
    33213316 */
     
    33653360     * @param string $output        Adjacent image HTML markup.
    33663361     * @param int    $attachment_id Attachment ID
    3367      * @param string $size          Image size.
     3362     * @param string|int[] $size    Requested image size. Can be any registered image size name, or
     3363     *                              an array of width and height values in pixels (in that order).
    33683364     * @param string $text          Link text.
    33693365     */
  • trunk/src/wp-includes/post-template.php

    r49020 r49021  
    15971597 *
    15981598 * @param int|WP_Post  $id        Optional. Post ID or post object.
    1599  * @param string|array $size      Optional. Image size. Accepts any valid image size, or an array
    1600  *                                of width and height values in pixels (in that order).
    1601  *                                Default 'thumbnail'.
     1599 * @param string|int[] $size      Optional. Image size. Accepts any registered image size name, or an array
     1600 *                                of width and height values in pixels (in that order). Default 'thumbnail'.
    16021601 * @param bool         $permalink Optional. Whether to add permalink to image. Default false.
    16031602 * @param bool         $icon      Optional. Whether the attachment is an icon. Default false.
     
    16431642     * @param string       $link_html The page link HTML output.
    16441643     * @param int          $id        Post ID.
    1645      * @param string|array $size      Size of the image. Image size or array of width and height values (in that order).
    1646      *                                Default 'thumbnail'.
     1644     * @param string|int[] $size      Requested image size. Can be any registered image size name, or
     1645     *                                an array of width and height values in pixels (in that order).
    16471646     * @param bool         $permalink Whether to add permalink to image. Default false.
    16481647     * @param bool         $icon      Whether to include an icon.
  • trunk/src/wp-includes/post-thumbnail-template.php

    r49016 r49021  
    7575 * @see get_the_post_thumbnail()
    7676 *
    77  * @param string|array $size Optional. Image size to use. Accepts any valid image size, or
    78  *                           an array of width and height values in pixels (in that order).
    79  *                           Default 'post-thumbnail'.
     77 * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
     78 *                           width and height values in pixels (in that order). Default 'post-thumbnail'.
    8079 * @param string|array $attr Optional. Query string or array of attributes. Default empty.
    8180 */
     
    132131 *
    133132 * @param int|WP_Post  $post Optional. Post ID or WP_Post object.  Default is global `$post`.
    134  * @param string|array $size Optional. Image size to use. Accepts any valid image size, or
    135  *                           an array of width and height values in pixels (in that order).
    136  *                           Default 'post-thumbnail'.
     133 * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
     134 *                           width and height values in pixels (in that order). Default 'post-thumbnail'.
    137135 * @param string|array $attr Optional. Query string or array of attributes. Default empty.
    138136 * @return string The post thumbnail image tag.
     
    153151     * @since 4.9.0 Added the `$post_id` parameter.
    154152     *
    155      * @param string|array $size    The post thumbnail size. Image size or array of width and height
    156      *                              values (in that order). Default 'post-thumbnail'.
     153     * @param string|int[] $size    Requested image size. Can be any registered image size name, or
     154     *                              an array of width and height values in pixels (in that order).
    157155     * @param int          $post_id The post ID.
    158156     */
     
    170168         * @param int          $post_id           The post ID.
    171169         * @param int          $post_thumbnail_id The post thumbnail ID.
    172          * @param string|array $size              The post thumbnail size. Image size or array of width
    173          *                                        and height values (in that order). Default 'post-thumbnail'.
     170         * @param string|int[] $size              Requested image size. Can be any registered image size name, or
     171         *                                        an array of width and height values in pixels (in that order).
    174172         */
    175173        do_action( 'begin_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
     
    188186         * @param int          $post_id           The post ID.
    189187         * @param int          $post_thumbnail_id The post thumbnail ID.
    190          * @param string|array $size              The post thumbnail size. Image size or array of width
    191          *                                        and height values (in that order). Default 'post-thumbnail'.
     188         * @param string|int[] $size              Requested image size. Can be any registered image size name, or
     189         *                                        an array of width and height values in pixels (in that order).
    192190         */
    193191        do_action( 'end_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
     
    205203     * @param int          $post_id           The post ID.
    206204     * @param int          $post_thumbnail_id The post thumbnail ID.
    207      * @param string|array $size              The post thumbnail size. Image size or array of width and height
    208      *                                        values (in that order). Default 'post-thumbnail'.
     205     * @param string|int[] $size              Requested image size. Can be any registered image size name, or
     206     *                                        an array of width and height values in pixels (in that order).
    209207     * @param string       $attr              Query string of attributes.
    210208     */
Note: See TracChangeset for help on using the changeset viewer.