函数文档

wp_getimagesize()

💡 云策文档标注

概述

wp_getimagesize() 是 WordPress 中用于获取图像尺寸和信息的函数,基于 PHP 的 getimagesize() 实现,增加了调试支持和现代图像格式(如 WebP、AVIF、HEIC)的兼容性。它根据 WP_DEBUG 设置控制错误报告,并处理 PHP 版本不支持的图像格式。

关键要点

  • 函数签名:wp_getimagesize( $filename, ?array &$image_info = null ),返回数组或 false。
  • 调试模式:当 WP_DEBUG 启用且非单元测试时,不抑制 getimagesize() 的错误;否则使用 @ 操作符抑制错误。
  • 支持现代格式:自动检测并处理 WebP、AVIF 和 HEIC 图像,通过辅助函数提取尺寸信息以模拟原生返回格式。
  • 返回值:成功时返回包含宽度、高度、IMAGETYPE 常量、HTML 字符串和 MIME 类型等信息的数组;失败时返回 false。
  • 相关函数:依赖 wp_get_image_mime()、wp_get_webp_info()、wp_get_avif_info()、wp_is_heic_image_mime_type() 和 wp_get_image_editor() 等。

代码示例

$size = wp_getimagesize( '/path/to/image.jpg' );
if ( $size !== false ) {
    echo 'Width: ' . $size[0] . ', Height: ' . $size[1];
}

注意事项

  • 在调试环境中,错误可能被显示,有助于诊断图像处理问题。
  • 对于不支持的图像格式,函数会尝试通过备用方法获取尺寸,但可能仍返回 false。
  • 确保文件路径正确,否则函数可能因文件无法访问而失败。

📄 原文内容

Allows PHP’s getimagesize() to be debuggable when necessary.

Parameters

$filenamestringrequired
The file path.
$image_infoarrayoptional
Extended image information (passed by reference).

Default:null

Return

array|false Array of image information or false on failure.

Source

function wp_getimagesize( $filename, ?array &$image_info = null ) {
	// Don't silence errors when in debug mode, unless running unit tests.
	if ( defined( 'WP_DEBUG' ) && WP_DEBUG && ! defined( 'WP_RUN_CORE_TESTS' ) ) {
		if ( 2 === func_num_args() ) {
			$info = getimagesize( $filename, $image_info );
		} else {
			$info = getimagesize( $filename );
		}
	} else {
		/*
		 * Silencing notice and warning is intentional.
		 *
		 * getimagesize() has a tendency to generate errors, such as
		 * "corrupt JPEG data: 7191 extraneous bytes before marker",
		 * even when it's able to provide image size information.
		 *
		 * See https://core.trac.wordpress.org/ticket/42480
		 */
		if ( 2 === func_num_args() ) {
			$info = @getimagesize( $filename, $image_info );
		} else {
			$info = @getimagesize( $filename );
		}
	}

	if (
		! empty( $info ) &&
		// Some PHP versions return 0x0 sizes from `getimagesize` for unrecognized image formats, including AVIFs.
		! ( empty( $info[0] ) && empty( $info[1] ) )
	) {
		return $info;
	}

	$image_mime_type = wp_get_image_mime( $filename );

	// Not an image?
	if ( false === $image_mime_type ) {
		return false;
	}

	/*
	 * For PHP versions that don't support WebP images,
	 * extract the image size info from the file headers.
	 */
	if ( 'image/webp' === $image_mime_type ) {
		$webp_info = wp_get_webp_info( $filename );
		$width     = $webp_info['width'];
		$height    = $webp_info['height'];

		// Mimic the native return format.
		if ( $width && $height ) {
			return array(
				$width,
				$height,
				IMAGETYPE_WEBP,
				sprintf(
					'width="%d" height="%d"',
					$width,
					$height
				),
				'mime' => 'image/webp',
			);
		}
	}

	// For PHP versions that don't support AVIF images, extract the image size info from the file headers.
	if ( 'image/avif' === $image_mime_type ) {
		$avif_info = wp_get_avif_info( $filename );

		$width  = $avif_info['width'];
		$height = $avif_info['height'];

		// Mimic the native return format.
		if ( $width && $height ) {
			return array(
				$width,
				$height,
				IMAGETYPE_AVIF,
				sprintf(
					'width="%d" height="%d"',
					$width,
					$height
				),
				'mime' => 'image/avif',
			);
		}
	}

	// For PHP versions that don't support HEIC images, extract the size info using Imagick when available.
	if ( wp_is_heic_image_mime_type( $image_mime_type ) ) {
		$editor = wp_get_image_editor( $filename );

		if ( is_wp_error( $editor ) ) {
			return false;
		}

		// If the editor for HEICs is Imagick, use it to get the image size.
		if ( $editor instanceof WP_Image_Editor_Imagick ) {
			$size = $editor->get_size();
			return array(
				$size['width'],
				$size['height'],
				IMAGETYPE_HEIF,
				sprintf(
					'width="%d" height="%d"',
					$size['width'],
					$size['height']
				),
				'mime' => 'image/heic',
			);
		}
	}

	// The image could not be parsed.
	return false;
}

Changelog

Version Description
6.5.0 Added support for AVIF images.
5.8.0 Added support for WebP images.
5.7.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content

    Usage (if you only have image URL):

    
    
    <img <?php echo $getimagesize[3]; ?> src="" />

    Returns array of data:

    $getimagesize[0]          = The width of the image.
    $getimagesize[1]          = The height of the image.
    $getimagesize[2]          = One of the <a href="https://www.php.net/manual/en/image.constants.php" rel="nofollow ugc">IMAGETYPE_ constants</a> indicating the type of the image.
    $getimagesize[3]          = A text string with the correct height="yyy" width="xxx" string that can be used directly in an IMG tag.
    $getimagesize['mime']     = The correspondent MIME type of the image. This information can be used to deliver images with the correct HTTP Content-type header.
    $getimagesize['channels'] = 3 for RGB pictures and 4 for CMYK pictures.
    $getimagesize['bits']     = The number of bits for each color.
    
    Array
    (
        [0] => 440
        [1] => 95
        [2] => 3
        [3] => width="440" height="95"
        [bits] => 8
        [mime] => image/png
    )