image_constrain_size_for_editor() WordPress Function

The image_constrain_size_for_editor() function is used to constrain the dimensions of an image that is being edited in the WordPress editor. This function is used to keep images from being too small or too large when they are being edited. This function is also used to keep the aspect ratio of an image from being changed when it is being edited.

image_constrain_size_for_editor( int $width, int $height, string|int[] $size = 'medium', string $context = null ) #

Scale down the default size of an image.


Description

This is so that the image is a better fit for the editor and theme.

The $size parameter accepts either an array or a string. The supported string values are ‘thumb’ or ‘thumbnail’ for the given thumbnail size or defaults at 128 width and 96 height in pixels. Also supported for the string value is ‘medium’, ‘medium_large’ and ‘full’. The ‘full’ isn’t actually supported, but any value other than the supported will result in the content_width size or 500 if that is not set.

Finally, there is a filter named ‘editor_max_image_size’, that will be called on the calculated array for width and height, respectively.


Top ↑

Parameters

$width

(int)(Required)Width of the image in pixels.

$height

(int)(Required)Height of the image in pixels.

$size

(string|int[])(Optional) Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order).

Default value: 'medium'

$context

(string)(Optional) Could be 'display' (like in a theme) or 'edit' (like inserting into an editor).

Default value: null


Top ↑

Return

(int[]) An array of width and height values.

  • (int) The maximum width in pixels.
  • '1'
    (int) The maximum height in pixels.


Top ↑

Source

File: wp-includes/media.php

60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
function image_constrain_size_for_editor( $width, $height, $size = 'medium', $context = null ) {
    global $content_width;
 
    $_wp_additional_image_sizes = wp_get_additional_image_sizes();
 
    if ( ! $context ) {
        $context = is_admin() ? 'edit' : 'display';
    }
 
    if ( is_array( $size ) ) {
        $max_width  = $size[0];
        $max_height = $size[1];
    } elseif ( 'thumb' === $size || 'thumbnail' === $size ) {
        $max_width  = (int) get_option( 'thumbnail_size_w' );
        $max_height = (int) get_option( 'thumbnail_size_h' );
        // Last chance thumbnail size defaults.
        if ( ! $max_width && ! $max_height ) {
            $max_width  = 128;
            $max_height = 96;
        }
    } elseif ( 'medium' === $size ) {
        $max_width  = (int) get_option( 'medium_size_w' );
        $max_height = (int) get_option( 'medium_size_h' );
 
    } elseif ( 'medium_large' === $size ) {
        $max_width  = (int) get_option( 'medium_large_size_w' );
        $max_height = (int) get_option( 'medium_large_size_h' );
 
        if ( (int) $content_width > 0 ) {
            $max_width = min( (int) $content_width, $max_width );
        }
    } elseif ( 'large' === $size ) {
        /*
         * We're inserting a large size image into the editor. If it's a really
         * big image we'll scale it down to fit reasonably within the editor
         * itself, and within the theme's content width if it's known. The user
         * can resize it in the editor if they wish.
         */
        $max_width  = (int) get_option( 'large_size_w' );
        $max_height = (int) get_option( 'large_size_h' );
 
        if ( (int) $content_width > 0 ) {
            $max_width = min( (int) $content_width, $max_width );
        }
    } elseif ( ! empty( $_wp_additional_image_sizes ) && in_array( $size, array_keys( $_wp_additional_image_sizes ), true ) ) {
        $max_width  = (int) $_wp_additional_image_sizes[ $size ]['width'];
        $max_height = (int) $_wp_additional_image_sizes[ $size ]['height'];
        // Only in admin. Assume that theme authors know what they're doing.
        if ( (int) $content_width > 0 && 'edit' === $context ) {
            $max_width = min( (int) $content_width, $max_width );
        }
    } else { // $size === 'full' has no constraint.
        $max_width  = $width;
        $max_height = $height;
    }
 
    /**
     * Filters the maximum image size dimensions for the editor.
     *
     * @since 2.5.0
     *
     * @param int[]        $max_image_size {
     *     An array of width and height values.
     *
     *     @type int $0 The maximum width in pixels.
     *     @type int $1 The maximum height in pixels.
     * }
     * @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).
     */
    list( $max_width, $max_height ) = apply_filters( 'editor_max_image_size', array( $max_width, $max_height ), $size, $context );
 
    return wp_constrain_dimensions( $width, $height, $max_width, $max_height );
}


Top ↑

Changelog

Changelog
VersionDescription
2.5.0Introduced.

The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by the Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.

Show More
Show More