diff options
Diffstat (limited to 'srcs/wordpress/wp-includes/media.php')
| -rw-r--r-- | srcs/wordpress/wp-includes/media.php | 4388 |
1 files changed, 4388 insertions, 0 deletions
diff --git a/srcs/wordpress/wp-includes/media.php b/srcs/wordpress/wp-includes/media.php new file mode 100644 index 0000000..3783865 --- /dev/null +++ b/srcs/wordpress/wp-includes/media.php @@ -0,0 +1,4388 @@ +<?php +/** + * WordPress API for media display. + * + * @package WordPress + * @subpackage Media + */ + +/** + * Retrieve additional image sizes. + * + * @since 4.7.0 + * + * @global array $_wp_additional_image_sizes + * + * @return array Additional images size data. + */ +function wp_get_additional_image_sizes() { + global $_wp_additional_image_sizes; + + if ( ! $_wp_additional_image_sizes ) { + $_wp_additional_image_sizes = array(); + } + + return $_wp_additional_image_sizes; +} + +/** + * Scale down the default size of an image. + * + * 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 {@see 'editor_max_image_size'}, that will be + * called on the calculated array for width and height, respectively. The second + * parameter will be the value that was in the $size parameter. The returned + * type for the hook is an array with the width as the first element and the + * height as the second element. + * + * @since 2.5.0 + * + * @global int $content_width + * + * @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 $context Optional. Could be 'display' (like in a theme) or 'edit' + * (like inserting into an editor). Default null. + * @return array Width and height of what the result image should resize to. + */ +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 ( $size === 'thumb' || $size === 'thumbnail' ) { + $max_width = intval( get_option( 'thumbnail_size_w' ) ); + $max_height = intval( get_option( 'thumbnail_size_h' ) ); + // last chance thumbnail size defaults + if ( ! $max_width && ! $max_height ) { + $max_width = 128; + $max_height = 96; + } + } elseif ( $size === 'medium' ) { + $max_width = intval( get_option( 'medium_size_w' ) ); + $max_height = intval( get_option( 'medium_size_h' ) ); + + } elseif ( $size === 'medium_large' ) { + $max_width = intval( get_option( 'medium_large_size_w' ) ); + $max_height = intval( get_option( 'medium_large_size_h' ) ); + + if ( intval( $content_width ) > 0 ) { + $max_width = min( intval( $content_width ), $max_width ); + } + } elseif ( $size === 'large' ) { + /* + * 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 = intval( get_option( 'large_size_w' ) ); + $max_height = intval( get_option( 'large_size_h' ) ); + + if ( intval( $content_width ) > 0 ) { + $max_width = min( intval( $content_width ), $max_width ); + } + } elseif ( ! empty( $_wp_additional_image_sizes ) && in_array( $size, array_keys( $_wp_additional_image_sizes ), true ) ) { + $max_width = intval( $_wp_additional_image_sizes[ $size ]['width'] ); + $max_height = intval( $_wp_additional_image_sizes[ $size ]['height'] ); + // Only in admin. Assume that theme authors know what they're doing. + if ( intval( $content_width ) > 0 && 'edit' === $context ) { + $max_width = min( intval( $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 array $max_image_size An array with the width as the first element, + * and the height as the second element. + * @param string|array $size Size of what the result image should be. + * @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 ); +} + +/** + * Retrieve width and height attributes using given width and height values. + * + * Both attributes are required in the sense that both parameters must have a + * value, but are optional in that if you set them to false or null, then they + * will not be added to the returned string. + * + * You can set the value using a string, but it will only take numeric values. + * If you wish to put 'px' after the numbers, then it will be stripped out of + * the return. + * + * @since 2.5.0 + * + * @param int|string $width Image width in pixels. + * @param int|string $height Image height in pixels. + * @return string HTML attributes for width and, or height. + */ +function image_hwstring( $width, $height ) { + $out = ''; + if ( $width ) { + $out .= 'width="' . intval( $width ) . '" '; + } + if ( $height ) { + $out .= 'height="' . intval( $height ) . '" '; + } + return $out; +} + +/** + * Scale an image to fit a particular size (such as 'thumb' or 'medium'). + * + * Array with image url, width, height, and whether is intermediate size, in + * that order is returned on success is returned. $is_intermediate is true if + * $url is a resized image, false if it is the original. + * + * The URL might be the original image, or it might be a resized version. This + * function won't create a new resized copy, it will just return an already + * resized one if it exists. + * + * A plugin may use the {@see 'image_downsize'} filter to hook into and offer image + * resizing services for images. The hook must return an array with the same + * elements that are returned in the function. The first element being the URL + * to the new image that was resized. + * + * @since 2.5.0 + * + * @param int $id Attachment ID for image. + * @param array|string $size Optional. Image size to scale to. Accepts any valid image size, + * or an array of width and height values in pixels (in that order). + * Default 'medium'. + * @return false|array Array containing the image URL, width, height, and boolean for whether + * the image is an intermediate size. False on failure. + */ +function image_downsize( $id, $size = 'medium' ) { + $is_image = wp_attachment_is_image( $id ); + + /** + * Filters whether to preempt the output of image_downsize(). + * + * Passing a truthy value to the filter will effectively short-circuit + * down-sizing the image, returning that value as output instead. + * + * @since 2.5.0 + * + * @param bool $downsize Whether to short-circuit the image downsize. Default false. + * @param int $id Attachment ID for image. + * @param array|string $size Size of image. Image size or array of width and height values (in that order). + * Default 'medium'. + */ + $out = apply_filters( 'image_downsize', false, $id, $size ); + + if ( $out ) { + return $out; + } + + $img_url = wp_get_attachment_url( $id ); + $meta = wp_get_attachment_metadata( $id ); + $width = 0; + $height = 0; + $is_intermediate = false; + $img_url_basename = wp_basename( $img_url ); + + // If the file isn't an image, attempt to replace its URL with a rendered image from its meta. + // Otherwise, a non-image type could be returned. + if ( ! $is_image ) { + if ( ! empty( $meta['sizes']['full'] ) ) { + $img_url = str_replace( $img_url_basename, $meta['sizes']['full']['file'], $img_url ); + $img_url_basename = $meta['sizes']['full']['file']; + $width = $meta['sizes']['full']['width']; + $height = $meta['sizes']['full']['height']; + } else { + return false; + } + } + + // try for a new style intermediate size + $intermediate = image_get_intermediate_size( $id, $size ); + + if ( $intermediate ) { + $img_url = str_replace( $img_url_basename, $intermediate['file'], $img_url ); + $width = $intermediate['width']; + $height = $intermediate['height']; + $is_intermediate = true; + } elseif ( $size === 'thumbnail' ) { + // fall back to the old thumbnail + $thumb_file = wp_get_attachment_thumb_file( $id ); + $info = null; + + if ( $thumb_file ) { + $info = @getimagesize( $thumb_file ); + } + + if ( $thumb_file && $info ) { + $img_url = str_replace( $img_url_basename, wp_basename( $thumb_file ), $img_url ); + $width = $info[0]; + $height = $info[1]; + $is_intermediate = true; + } + } + + if ( ! $width && ! $height && isset( $meta['width'], $meta['height'] ) ) { + // any other type: use the real image + $width = $meta['width']; + $height = $meta['height']; + } + + if ( $img_url ) { + // we have the actual image size, but might need to further constrain it if content_width is narrower + list( $width, $height ) = image_constrain_size_for_editor( $width, $height, $size ); + + return array( $img_url, $width, $height, $is_intermediate ); + } + + return false; +} + +/** + * Register a new image size. + * + * @since 2.9.0 + * + * @global array $_wp_additional_image_sizes Associative array of additional image sizes. + * + * @param string $name Image size identifier. + * @param int $width Optional. Image width in pixels. Default 0. + * @param int $height Optional. Image height in pixels. Default 0. + * @param bool|array $crop Optional. Image cropping behavior. If false, the image will be scaled (default), + * If true, image will be cropped to the specified dimensions using center positions. + * If an array, the image will be cropped using the array to specify the crop location. + * Array values must be in the format: array( x_crop_position, y_crop_position ) where: + * - x_crop_position accepts: 'left', 'center', or 'right'. + * - y_crop_position accepts: 'top', 'center', or 'bottom'. + */ +function add_image_size( $name, $width = 0, $height = 0, $crop = false ) { + global $_wp_additional_image_sizes; + + $_wp_additional_image_sizes[ $name ] = array( + 'width' => absint( $width ), + 'height' => absint( $height ), + 'crop' => $crop, + ); +} + +/** + * Check if an image size exists. + * + * @since 3.9.0 + * + * @param string $name The image size to check. + * @return bool True if the image size exists, false if not. + */ +function has_image_size( $name ) { + $sizes = wp_get_additional_image_sizes(); + return isset( $sizes[ $name ] ); +} + +/** + * Remove a new image size. + * + * @since 3.9.0 + * + * @global array $_wp_additional_image_sizes + * + * @param string $name The image size to remove. + * @return bool True if the image size was successfully removed, false on failure. + */ +function remove_image_size( $name ) { + global $_wp_additional_image_sizes; + + if ( isset( $_wp_additional_image_sizes[ $name ] ) ) { + unset( $_wp_additional_image_sizes[ $name ] ); + return true; + } + + return false; +} + +/** + * Registers an image size for the post thumbnail. + * + * @since 2.9.0 + * + * @see add_image_size() for details on cropping behavior. + * + * @param int $width Image width in pixels. + * @param int $height Image height in pixels. + * @param bool|array $crop Optional. Whether to crop images to specified width and height or resize. + * An array can specify positioning of the crop area. Default false. + */ +function set_post_thumbnail_size( $width = 0, $height = 0, $crop = false ) { + add_image_size( 'post-thumbnail', $width, $height, $crop ); +} + +/** + * Gets an img tag for an image attachment, scaling it down if requested. + * + * The {@see 'get_image_tag_class'} filter allows for changing the class name for the + * image without having to use regular expressions on the HTML content. The + * parameters are: what WordPress will use for the class, the Attachment ID, + * image align value, and the size the image should be. + * + * The second filter, {@see 'get_image_tag'}, has the HTML content, which can then be + * further manipulated by a plugin to change all attribute values and even HTML + * content. + * + * @since 2.5.0 + * + * @param int $id Attachment ID. + * @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'. + * @return string HTML IMG element for given image attachment + */ +function get_image_tag( $id, $alt, $title, $align, $size = 'medium' ) { + + list( $img_src, $width, $height ) = image_downsize( $id, $size ); + $hwstring = image_hwstring( $width, $height ); + + $title = $title ? 'title="' . esc_attr( $title ) . '" ' : ''; + + $class = 'align' . esc_attr( $align ) . ' size-' . esc_attr( $size ) . ' wp-image-' . $id; + + /** + * Filters the value of the attachment's image tag class attribute. + * + * @since 2.6.0 + * + * @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'. + */ + $class = apply_filters( 'get_image_tag_class', $class, $id, $align, $size ); + + $html = '<img src="' . esc_attr( $img_src ) . '" alt="' . esc_attr( $alt ) . '" ' . $title . $hwstring . 'class="' . $class . '" />'; + + /** + * Filters the HTML content for the image tag. + * + * @since 2.6.0 + * + * @param string $html HTML content for the image. + * @param int $id Attachment ID. + * @param string $alt Alternate text. + * @param string $title Attachment title. + * @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'. + */ + return apply_filters( 'get_image_tag', $html, $id, $alt, $title, $align, $size ); +} + +/** + * Calculates the new dimensions for a down-sampled image. + * + * If either width or height are empty, no constraint is applied on + * that dimension. + * + * @since 2.5.0 + * + * @param int $current_width Current width of the image. + * @param int $current_height Current height of the image. + * @param int $max_width Optional. Max width in pixels to constrain to. Default 0. + * @param int $max_height Optional. Max height in pixels to constrain to. Default 0. + * @return array First item is the width, the second item is the height. + */ +function wp_constrain_dimensions( $current_width, $current_height, $max_width = 0, $max_height = 0 ) { + if ( ! $max_width && ! $max_height ) { + return array( $current_width, $current_height ); + } + + $width_ratio = 1.0; + $height_ratio = 1.0; + $did_width = false; + $did_height = false; + + if ( $max_width > 0 && $current_width > 0 && $current_width > $max_width ) { + $width_ratio = $max_width / $current_width; + $did_width = true; + } + + if ( $max_height > 0 && $current_height > 0 && $current_height > $max_height ) { + $height_ratio = $max_height / $current_height; + $did_height = true; + } + + // Calculate the larger/smaller ratios + $smaller_ratio = min( $width_ratio, $height_ratio ); + $larger_ratio = max( $width_ratio, $height_ratio ); + + if ( (int) round( $current_width * $larger_ratio ) > $max_width || (int) round( $current_height * $larger_ratio ) > $max_height ) { + // The larger ratio is too big. It would result in an overflow. + $ratio = $smaller_ratio; + } else { + // The larger ratio fits, and is likely to be a more "snug" fit. + $ratio = $larger_ratio; + } + + // Very small dimensions may result in 0, 1 should be the minimum. + $w = max( 1, (int) round( $current_width * $ratio ) ); + $h = max( 1, (int) round( $current_height * $ratio ) ); + + // Sometimes, due to rounding, we'll end up with a result like this: 465x700 in a 177x177 box is 117x176... a pixel short + // We also have issues with recursive calls resulting in an ever-changing result. Constraining to the result of a constraint should yield the original result. + // Thus we look for dimensions that are one pixel shy of the max value and bump them up + + // Note: $did_width means it is possible $smaller_ratio == $width_ratio. + if ( $did_width && $w === $max_width - 1 ) { + $w = $max_width; // Round it up + } + + // Note: $did_height means it is possible $smaller_ratio == $height_ratio. + if ( $did_height && $h === $max_height - 1 ) { + $h = $max_height; // Round it up + } + + /** + * Filters dimensions to constrain down-sampled images to. + * + * @since 4.1.0 + * + * @param array $dimensions The image width and height. + * @param int $current_width The current width of the image. + * @param int $current_height The current height of the image. + * @param int $max_width The maximum width permitted. + * @param int $max_height The maximum height permitted. + */ + return apply_filters( 'wp_constrain_dimensions', array( $w, $h ), $current_width, $current_height, $max_width, $max_height ); +} + +/** + * Retrieves calculated resize dimensions for use in WP_Image_Editor. + * + * Calculates dimensions and coordinates for a resized image that fits + * within a specified width and height. + * + * Cropping behavior is dependent on the value of $crop: + * 1. If false (default), images will not be cropped. + * 2. If an array in the form of array( x_crop_position, y_crop_position ): + * - x_crop_position accepts 'left' 'center', or 'right'. + * - y_crop_position accepts 'top', 'center', or 'bottom'. + * Images will be cropped to the specified dimensions within the defined crop area. + * 3. If true, images will be cropped to the specified dimensions using center positions. + * + * @since 2.5.0 + * + * @param int $orig_w Original width in pixels. + * @param int $orig_h Original height in pixels. + * @param int $dest_w New width in pixels. + * @param int $dest_h New height in pixels. + * @param bool|array $crop Optional. Whether to crop image to specified width and height or resize. + * An array can specify positioning of the crop area. Default false. + * @return false|array False on failure. Returned array matches parameters for `imagecopyresampled()`. + */ +function image_resize_dimensions( $orig_w, $orig_h, $dest_w, $dest_h, $crop = false ) { + + if ( $orig_w <= 0 || $orig_h <= 0 ) { + return false; + } + // at least one of dest_w or dest_h must be specific + if ( $dest_w <= 0 && $dest_h <= 0 ) { + return false; + } + + /** + * Filters whether to preempt calculating the image resize dimensions. + * + * Passing a non-null value to the filter will effectively short-circuit + * image_resize_dimensions(), returning that value instead. + * + * @since 3.4.0 + * + * @param null|mixed $null Whether to preempt output of the resize dimensions. + * @param int $orig_w Original width in pixels. + * @param int $orig_h Original height in pixels. + * @param int $dest_w New width in pixels. + * @param int $dest_h New height in pixels. + * @param bool|array $crop Whether to crop image to specified width and height or resize. + * An array can specify positioning of the crop area. Default false. + */ + $output = apply_filters( 'image_resize_dimensions', null, $orig_w, $orig_h, $dest_w, $dest_h, $crop ); + + if ( null !== $output ) { + return $output; + } + + // Stop if the destination size is larger than the original image dimensions. + if ( empty( $dest_h ) ) { + if ( $orig_w < $dest_w ) { + return false; + } + } elseif ( empty( $dest_w ) ) { + if ( $orig_h < $dest_h ) { + return false; + } + } else { + if ( $orig_w < $dest_w && $orig_h < $dest_h ) { + return false; + } + } + + if ( $crop ) { + // Crop the largest possible portion of the original image that we can size to $dest_w x $dest_h. + // Note that the requested crop dimensions are used as a maximum bounding box for the original image. + // If the original image's width or height is less than the requested width or height + // only the greater one will be cropped. + // For example when the original image is 600x300, and the requested crop dimensions are 400x400, + // the resulting image will be 400x300. + $aspect_ratio = $orig_w / $orig_h; + $new_w = min( $dest_w, $orig_w ); + $new_h = min( $dest_h, $orig_h ); + + if ( ! $new_w ) { + $new_w = (int) round( $new_h * $aspect_ratio ); + } + + if ( ! $new_h ) { + $new_h = (int) round( $new_w / $aspect_ratio ); + } + + $size_ratio = max( $new_w / $orig_w, $new_h / $orig_h ); + + $crop_w = round( $new_w / $size_ratio ); + $crop_h = round( $new_h / $size_ratio ); + + if ( ! is_array( $crop ) || count( $crop ) !== 2 ) { + $crop = array( 'center', 'center' ); + } + + list( $x, $y ) = $crop; + + if ( 'left' === $x ) { + $s_x = 0; + } elseif ( 'right' === $x ) { + $s_x = $orig_w - $crop_w; + } else { + $s_x = floor( ( $orig_w - $crop_w ) / 2 ); + } + + if ( 'top' === $y ) { + $s_y = 0; + } elseif ( 'bottom' === $y ) { + $s_y = $orig_h - $crop_h; + } else { + $s_y = floor( ( $orig_h - $crop_h ) / 2 ); + } + } else { + // Resize using $dest_w x $dest_h as a maximum bounding box. + $crop_w = $orig_w; + $crop_h = $orig_h; + + $s_x = 0; + $s_y = 0; + + list( $new_w, $new_h ) = wp_constrain_dimensions( $orig_w, $orig_h, $dest_w, $dest_h ); + } + + if ( wp_fuzzy_number_match( $new_w, $orig_w ) && wp_fuzzy_number_match( $new_h, $orig_h ) ) { + // The new size has virtually the same dimensions as the original image. + + /** + * Filters whether to proceed with making an image sub-size with identical dimensions + * with the original/source image. Differences of 1px may be due to rounding and are ignored. + * + * @since 5.3.0 + * + * @param bool The filtered value. + * @param int Original image width. + * @param int Original image height. + */ + $proceed = (bool) apply_filters( 'wp_image_resize_identical_dimensions', false, $orig_w, $orig_h ); + + if ( ! $proceed ) { + return false; + } + } + + // The return array matches the parameters to imagecopyresampled(). + // int dst_x, int dst_y, int src_x, int src_y, int dst_w, int dst_h, int src_w, int src_h + return array( 0, 0, (int) $s_x, (int) $s_y, (int) $new_w, (int) $new_h, (int) $crop_w, (int) $crop_h ); +} + +/** + * Resizes an image to make a thumbnail or intermediate size. + * + * The returned array has the file size, the image width, and image height. The + * {@see 'image_make_intermediate_size'} filter can be used to hook in and change the + * values of the returned array. The only parameter is the resized file path. + * + * @since 2.5.0 + * + * @param string $file File path. + * @param int $width Image width. + * @param int $height Image height. + * @param bool $crop Optional. Whether to crop image to specified width and height or resize. + * Default false. + * @return false|array False, if no image was created. Metadata array on success. + */ +function image_make_intermediate_size( $file, $width, $height, $crop = false ) { + if ( $width || $height ) { + $editor = wp_get_image_editor( $file ); + + if ( is_wp_error( $editor ) || is_wp_error( $editor->resize( $width, $height, $crop ) ) ) { + return false; + } + + $resized_file = $editor->save(); + + if ( ! is_wp_error( $resized_file ) && $resized_file ) { + unset( $resized_file['path'] ); + return $resized_file; + } + } + return false; +} + +/** + * Helper function to test if aspect ratios for two images match. + * + * @since 4.6.0 + * + * @param int $source_width Width of the first image in pixels. + * @param int $source_height Height of the first image in pixels. + * @param int $target_width Width of the second image in pixels. + * @param int $target_height Height of the second image in pixels. + * @return bool True if aspect ratios match within 1px. False if not. + */ +function wp_image_matches_ratio( $source_width, $source_height, $target_width, $target_height ) { + /* + * To test for varying crops, we constrain the dimensions of the larger image + * to the dimensions of the smaller image and see if they match. + */ + if ( $source_width > $target_width ) { + $constrained_size = wp_constrain_dimensions( $source_width, $source_height, $target_width ); + $expected_size = array( $target_width, $target_height ); + } else { + $constrained_size = wp_constrain_dimensions( $target_width, $target_height, $source_width ); + $expected_size = array( $source_width, $source_height ); + } + + // If the image dimensions are within 1px of the expected size, we consider it a match. + $matched = ( wp_fuzzy_number_match( $constrained_size[0], $expected_size[0] ) && wp_fuzzy_number_match( $constrained_size[1], $expected_size[1] ) ); + + return $matched; +} + +/** + * Retrieves the image's intermediate size (resized) path, width, and height. + * + * The $size parameter can be an array with the width and height respectively. + * If the size matches the 'sizes' metadata array for width and height, then it + * will be used. If there is no direct match, then the nearest image size larger + * than the specified size will be used. If nothing is found, then the function + * will break out and return false. + * + * The metadata 'sizes' is used for compatible sizes that can be used for the + * parameter $size value. + * + * The url path will be given, when the $size parameter is a string. + * + * If you are passing an array for the $size, you should consider using + * add_image_size() so that a cropped version is generated. It's much more + * efficient than having to find the closest-sized image and then having the + * browser scale down the image. + * + * @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'. + * @return false|array $data { + * 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. + * + * @type string $file Image's path relative to uploads directory + * @type int $width Width of image + * @type int $height Height of image + * @type string $path Image's absolute filesystem path. + * @type string $url Image's URL. + * } + */ +function image_get_intermediate_size( $post_id, $size = 'thumbnail' ) { + $imagedata = wp_get_attachment_metadata( $post_id ); + + if ( ! $size || ! is_array( $imagedata ) || empty( $imagedata['sizes'] ) ) { + return false; + } + + $data = array(); + + // Find the best match when '$size' is an array. + if ( is_array( $size ) ) { + $candidates = array(); + + if ( ! isset( $imagedata['file'] ) && isset( $imagedata['sizes']['full'] ) ) { + $imagedata['height'] = $imagedata['sizes']['full']['height']; + $imagedata['width'] = $imagedata['sizes']['full']['width']; + } + + foreach ( $imagedata['sizes'] as $_size => $data ) { + // If there's an exact match to an existing image size, short circuit. + if ( intval( $data['width'] ) === intval( $size[0] ) && intval( $data['height'] ) === intval( $size[1] ) ) { + $candidates[ $data['width'] * $data['height'] ] = $data; + break; + } + + // If it's not an exact match, consider larger sizes with the same aspect ratio. + if ( $data['width'] >= $size[0] && $data['height'] >= $size[1] ) { + // If '0' is passed to either size, we test ratios against the original file. + if ( 0 === $size[0] || 0 === $size[1] ) { + $same_ratio = wp_image_matches_ratio( $data['width'], $data['height'], $imagedata['width'], $imagedata['height'] ); + } else { + $same_ratio = wp_image_matches_ratio( $data['width'], $data['height'], $size[0], $size[1] ); + } + + if ( $same_ratio ) { + $candidates[ $data['width'] * $data['height'] ] = $data; + } + } + } + + if ( ! empty( $candidates ) ) { + // Sort the array by size if we have more than one candidate. + if ( 1 < count( $candidates ) ) { + ksort( $candidates ); + } + + $data = array_shift( $candidates ); + /* + * When the size requested is smaller than the thumbnail dimensions, we + * fall back to the thumbnail size to maintain backward compatibility with + * pre 4.6 versions of WordPress. + */ + } elseif ( ! empty( $imagedata['sizes']['thumbnail'] ) && $imagedata['sizes']['thumbnail']['width'] >= $size[0] && $imagedata['sizes']['thumbnail']['width'] >= $size[1] ) { + $data = $imagedata['sizes']['thumbnail']; + } else { + return false; + } + + // Constrain the width and height attributes to the requested values. + list( $data['width'], $data['height'] ) = image_constrain_size_for_editor( $data['width'], $data['height'], $size ); + + } elseif ( ! empty( $imagedata['sizes'][ $size ] ) ) { + $data = $imagedata['sizes'][ $size ]; + } + + // If we still don't have a match at this point, return false. + if ( empty( $data ) ) { + return false; + } + + // include the full filesystem path of the intermediate file + if ( empty( $data['path'] ) && ! empty( $data['file'] ) && ! empty( $imagedata['file'] ) ) { + $file_url = wp_get_attachment_url( $post_id ); + $data['path'] = path_join( dirname( $imagedata['file'] ), $data['file'] ); + $data['url'] = path_join( dirname( $file_url ), $data['file'] ); + } + + /** + * Filters the output of image_get_intermediate_size() + * + * @since 4.4.0 + * + * @see image_get_intermediate_size() + * + * @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). + */ + return apply_filters( 'image_get_intermediate_size', $data, $post_id, $size ); +} + +/** + * Gets the available intermediate image sizes. + * + * @since 3.0.0 + * + * @return array Returns a filtered array of image size strings. + */ +function get_intermediate_image_sizes() { + $default_sizes = array( 'thumbnail', 'medium', 'medium_large', 'large' ); + $additional_sizes = wp_get_additional_image_sizes(); + + if ( ! empty( $additional_sizes ) ) { + $default_sizes = array_merge( $default_sizes, array_keys( $additional_sizes ) ); + } + + /** + * Filters the list of intermediate image sizes. + * + * @since 2.5.0 + * + * @param array $default_sizes An array of intermediate image sizes. Defaults + * are 'thumbnail', 'medium', 'medium_large', 'large'. + */ + return apply_filters( 'intermediate_image_sizes', $default_sizes ); +} + +/** + * Returns a normalized list of all currently registered image sub-sizes. + * + * @since 5.3.0 + * @uses wp_get_additional_image_sizes() + * @uses get_intermediate_image_sizes() + * + * @return array Associative array of the registered image sub-sizes. + */ +function wp_get_registered_image_subsizes() { + $additional_sizes = wp_get_additional_image_sizes(); + $all_sizes = array(); + + foreach ( get_intermediate_image_sizes() as $size_name ) { + $size_data = array( + 'width' => 0, + 'height' => 0, + 'crop' => false, + ); + + if ( isset( $additional_sizes[ $size_name ]['width'] ) ) { + // For sizes added by plugins and themes. + $size_data['width'] = intval( $additional_sizes[ $size_name ]['width'] ); + } else { + // For default sizes set in options. + $size_data['width'] = intval( get_option( "{$size_name}_size_w" ) ); + } + + if ( isset( $additional_sizes[ $size_name ]['height'] ) ) { + $size_data['height'] = intval( $additional_sizes[ $size_name ]['height'] ); + } else { + $size_data['height'] = intval( get_option( "{$size_name}_size_h" ) ); + } + + if ( empty( $size_data['width'] ) && empty( $size_data['height'] ) ) { + // This size isn't set. + continue; + } + + if ( isset( $additional_sizes[ $size_name ]['crop'] ) ) { + $size_data['crop'] = $additional_sizes[ $size_name ]['crop']; + } else { + $size_data['crop'] = get_option( "{$size_name}_crop" ); + } + + if ( ! is_array( $size_data['crop'] ) || empty( $size_data['crop'] ) ) { + $size_data['crop'] = (bool) $size_data['crop']; + } + + $all_sizes[ $size_name ] = $size_data; + } + + return $all_sizes; +} + +/** + * Retrieve an image to represent an attachment. + * + * A mime icon for files, thumbnail or intermediate size for images. + * + * The returned array contains four values: the URL of the attachment image src, + * the width of the image file, the height of the image file, and a boolean + * representing whether the returned array describes an intermediate (generated) + * image size or the original, full-sized upload. + * + * @since 2.5.0 + * + * @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 bool $icon Optional. Whether the image should be treated as an icon. Default false. + * @return false|array Returns an array (url, width, height, is_intermediate), or false, if no image is available. + */ +function wp_get_attachment_image_src( $attachment_id, $size = 'thumbnail', $icon = false ) { + // get a thumbnail or intermediate image if there is one + $image = image_downsize( $attachment_id, $size ); + if ( ! $image ) { + $src = false; + + if ( $icon ) { + $src = wp_mime_type_icon( $attachment_id ); + + if ( $src ) { + /** This filter is documented in wp-includes/post.php */ + $icon_dir = apply_filters( 'icon_dir', ABSPATH . WPINC . '/images/media' ); + + $src_file = $icon_dir . '/' . wp_basename( $src ); + list( $width, $height ) = @getimagesize( $src_file ); + } + } + + if ( $src && $width && $height ) { + $image = array( $src, $width, $height ); + } + } + /** + * Filters the image src result. + * + * @since 4.3.0 + * + * @param array|false $image Either array with src, width & height, icon src, or false. + * @param int $attachment_id Image attachment ID. + * @param string|array $size Size of image. Image size or array of width and height values + * (in that order). Default 'thumbnail'. + * @param bool $icon Whether the image should be treated as an icon. Default false. + */ + return apply_filters( 'wp_get_attachment_image_src', $image, $attachment_id, $size, $icon ); +} + +/** + * Get an HTML img element representing an image attachment + * + * While `$size` will accept an array, it is better to register a size with + * add_image_size() so that a cropped version is generated. It's much more + * efficient than having to find the closest-sized image and then having the + * browser scale down the image. + * + * @since 2.5.0 + * + * @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 |