wp_get_attachment_metadata()
云策文档标注
概述
wp_get_attachment_metadata() 函数用于根据附件 ID 检索附件的元数据，包括尺寸、文件路径、图像元数据等。它支持可选参数以跳过过滤器，并返回数组或失败时返回 false。
关键要点
- 函数参数：$attachment_id（必需，默认为全局 $post）和 $unfiltered（可选，默认为 false）。
- 返回值：成功时返回包含 width、height、file、sizes、image_meta 和 filesize 等键的数组；失败时返回 false。
- 内部实现：通过 get_post_meta() 获取 '_wp_attachment_metadata' 元数据，并应用 wp_get_attachment_metadata 过滤器。
- 版本变化：WordPress 6.0 起，返回值新增 filesize 键，便于获取文件大小。
代码示例
// 示例返回值数组（图像格式）
Array
(
[width] => 2400
[height] => 1559
[file] => 2011/12/press_image.jpg
[sizes] => Array
(
[thumbnail] => Array
(
[file] => press_image-150x150.jpg
[width] => 150
[height] => 150
[mime-type] => image/jpeg
)
[medium] => Array
(
[file] => press_image-4-300x194.jpg
[width] => 300
[height] => 194
[mime-type] => image/jpeg
)
[large] => Array
(
[file] => press_image-1024x665.jpg
[width] => 1024
[height] => 665
[mime-type] => image/jpeg
)
[post-thumbnail] => Array
(
[file] => press_image-624x405.jpg
[width] => 624
[height] => 405
[mime-type] => image/jpeg
)
)
[image_meta] => Array
(
[aperture] => 5
[credit] =>
[camera] => Canon EOS-1Ds Mark III
[caption] =>
[created_timestamp] => 1323190643
[copyright] =>
[focal_length] => 35
[iso] => 800
[shutter_speed] => 0.016666666666667
[title] =>
)
)注意事项
- file 键返回的是相对于 wp-content/uploads 的文件路径，如需完整 URL，需结合 wp_upload_dir() 使用。
- 从 WordPress 6.0 开始，返回值包含 filesize 键，可用于获取文件大小而无需调用 PHP 的 filesize() 函数。
- 该函数广泛用于媒体处理、REST API 和前端显示等场景。
原文内容
Retrieves attachment metadata for attachment ID.
Parameters
$attachment_idintrequired-
Attachment post ID. Defaults to global $post.
$unfilteredbooloptional-
If true, filters are not run.
Default:
false
Source
function wp_get_attachment_metadata( $attachment_id = 0, $unfiltered = false ) {
$attachment_id = (int) $attachment_id;
if ( ! $attachment_id ) {
$post = get_post();
if ( ! $post ) {
return false;
}
$attachment_id = $post->ID;
}
$data = get_post_meta( $attachment_id, '_wp_attachment_metadata', true );
if ( ! $data ) {
return false;
}
if ( $unfiltered ) {
return $data;
}
/**
* Filters the attachment meta data.
*
* @since 2.1.0
*
* @param array $data Array of meta data for the given attachment.
* @param int $attachment_id Attachment post ID.
*/
return apply_filters( 'wp_get_attachment_metadata', $data, $attachment_id );
}
Hooks
- apply_filters( ‘wp_get_attachment_metadata’, array $data, int $attachment_id )
-
Filters the attachment meta data.
Skip to note 5 content
Codex
Example return value
Array ( [width] => 2400 [height] => 1559 [file] => 2011/12/press_image.jpg [sizes] => Array ( [thumbnail] => Array ( [file] => press_image-150x150.jpg [width] => 150 [height] => 150 [mime-type] => image/jpeg ) <!-- Missing Medium URL --> => Array ( [file] => press_image-4-300x194.jpg [width] => 300 [height] => 194 [mime-type] => image/jpeg ) [large] => Array ( [file] => press_image-1024x665.jpg [width] => 1024 [height] => 665 [mime-type] => image/jpeg ) [post-thumbnail] => Array ( [file] => press_image-624x405.jpg [width] => 624 [height] => 405 [mime-type] => image/jpeg ) ) [image_meta] => Array ( [aperture] => 5 [credit] => [camera] => Canon EOS-1Ds Mark III => [created_timestamp] => 1323190643 [copyright] => [focal_length] => 35 [iso] => 800 [shutter_speed] => 0.016666666666667 [title] => ) )Skip to note 6 content
Toru Miki
Note that, since WordPress 6.0, return value includes filesize. This is for can be utilized so that image file size ca be retrieved without having to call php function filesize.
See Media: storing file size as part of metadata.
Skip to note 7 content
Anonymous User
Example for video format:
array(10) { ["filesize"] => int(227431276) ["mime_type"] => string(9) "video/mp4" ["length"] => int(918) ["length_formatted"] => string(5) "15:18" ["width"] => int(1280) ["height"] => int(720) ["fileformat"] => string(3) "mp4" ["dataformat"] => string(9) "quicktime" ["audio"] => array(7) { ["dataformat"] => string(3) "mp4" ["codec"] => string(19) "ISO/IEC 14496-3 AAC" ["sample_rate"] => float(44100) ["channels"] => int(2) ["bits_per_sample"] => int(16) ["lossless"] => bool(false) ["channelmode"] => string(6) "stereo" } ["created_timestamp"]=> int(-2082844800) }Skip to note 8 content
nellalink
NOTE that when calling wp_get_attachment_metadata() , the ARRAY index returned from ‘file’ is the file path relative to wp-content/uploads.
If you want to get url of domain to link up, you can use snippet below
$upload_dir = wp_upload_dir(); $attachment_metadata = wp_get_attachment_metadata( $attachment_id ); echo var_dump( $upload_dir['url'] . '/' . $attachment_metadata['sizes']['medium_large']['file'] );