get_attached_file()

💡 云策文档标注

概述

get_attached_file() 函数用于根据附件 ID 检索附件的文件路径。它通过获取 _wp_attached_file 元数据值实现，并支持通过 'get_attached_file' 过滤器进行修改。

关键要点

函数基于附件 ID 返回文件路径，若路径为相对路径，则自动添加上传目录前缀。
参数 $unfiltered 控制是否跳过 'get_attached_file' 过滤器，默认值为 false。
返回值为字符串（文件路径）或 false（失败时）。
内部使用 get_post_meta() 获取元数据，并应用 apply_filters() 钩子。

代码示例

$fullsize_path = get_attached_file( $attachment_id ); // 完整路径
$filename_only = basename( get_attached_file( $attachment_id ) ); // 仅文件名

📄 原文内容

Retrieves attached file path based on attachment ID.

Description

By default the path will go through the ‘get_attached_file’ filter, but passing true to the $unfiltered argument will return the file path unfiltered.

The function works by retrieving the _wp_attached_file post meta value.
This is a convenience function to prevent looking up the meta name and provide a mechanism for sending the attached filename through a filter.

Parameters

$attachment_idintrequired: Attachment ID.
$unfilteredbooloptional: Whether to skip the ‘get_attached_file’ filter.

Default:false

Return

string|false The file path to where the attached file should be, false otherwise.

Source

function get_attached_file( $attachment_id, $unfiltered = false ) {
	$file = get_post_meta( $attachment_id, '_wp_attached_file', true );

	// If the file is relative, prepend upload dir.
	if ( $file && ! str_starts_with( $file, '/' ) && ! preg_match( '|^.:\|', $file ) ) {
		$uploads = wp_get_upload_dir();
		if ( false === $uploads['error'] ) {
			$file = $uploads['basedir'] . "/$file";
		}
	}

	if ( $unfiltered ) {
		return $file;
	}

	/**
	 * Filters the attached file based on the given ID.
	 *
	 * @since 2.1.0
	 *
	 * @param string|false $file          The file path to where the attached file should be, false otherwise.
	 * @param int          $attachment_id Attachment ID.
	 */
	return apply_filters( 'get_attached_file', $file, $attachment_id );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘get_attached_file’, string|false $file, int $attachment_id ): Filters the attached file based on the given ID.

Uses	Description
wp_get_upload_dir()`wp-includes/functions.php`	Retrieves uploads directory information.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
get_post_meta()`wp-includes/post.php`	Retrieves a post meta field for the given post ID.

Show 1 more Show less

Used by	Description
wp_get_original_image_path()`wp-includes/post.php`	Retrieves the path to an uploaded image file.
WP_Customize_Manager::_validate_header_video()`wp-includes/class-wp-customize-manager.php`	Callback for validating the header_video value.
WP_Customize_Manager::import_theme_starter_content()`wp-includes/class-wp-customize-manager.php`	Imports theme starter content into the customized state.
WP_Media_List_Table::column_title()`wp-admin/includes/class-wp-media-list-table.php`	Handles the title column output.
wp_attachment_is()`wp-includes/post.php`	Verifies an attachment is of a given type.
File_Upload_Upgrader::__construct()`wp-admin/includes/class-file-upload-upgrader.php`	Construct the upgrader for a form.
wp_restore_image()`wp-admin/includes/image-edit.php`	Restores the metadata for a given attachment.
wp_save_image()`wp-admin/includes/image-edit.php`	Saves image to post, along with enqueued changes in `$_REQUEST['history']`.
_copy_image_file()`wp-admin/includes/image.php`	Copies an existing image file.
_load_image_to_edit_path()`wp-admin/includes/image.php`	Retrieves the path or URL of an attachment’s attached file.
wp_crop_image()`wp-admin/includes/image.php`	Crops an image to a given size.
attachment_submitbox_metadata()`wp-admin/includes/media.php`	Displays non-editable attachment metadata in the publish meta box.
get_media_item()`wp-admin/includes/media.php`	Retrieves HTML form for modifying the image attachment.
Custom_Image_Header::step_2()`wp-admin/includes/class-custom-image-header.php`	Displays second step of custom header image page.
Custom_Image_Header::step_3()`wp-admin/includes/class-custom-image-header.php`	Displays third step of custom header image page.
wp_load_image()`wp-includes/deprecated.php`	Load an image from a string, if PHP supports it.
get_attachment_icon_src()`wp-includes/deprecated.php`	Retrieve icon URL and Path.
wp_get_attachment_link()`wp-includes/post-template.php`	Retrieves an attachment page link using an image or icon, if possible.
wp_maybe_generate_attachment_metadata()`wp-includes/media.php`	Maybe attempts to generate attachment metadata, if missing.
wp_prepare_attachment_for_js()`wp-includes/media.php`	Prepares an attachment post object for JS, where it is expected to be JSON-encoded and fit into an Attachment model.
get_attachment_taxonomies()`wp-includes/media.php`	Retrieves taxonomies attached to given the attachment.
image_downsize()`wp-includes/media.php`	Scales an image to fit a particular size (such as ‘thumb’ or ‘medium’).
wp_mime_type_icon()`wp-includes/post.php`	Retrieves the icon for a MIME type or attachment.
wp_delete_attachment()`wp-includes/post.php`	Trashes or deletes an attachment.
wp_get_attachment_thumb_file()`wp-includes/deprecated.php`	Retrieves thumbnail for an attachment.

Show 20 more Show less

Changelog

Version	Description
2.0.0	Introduced.

User Contributed Notes

Skip to note 2 content

Codex

11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note
Examples
```
$fullsize_path = get_attached_file( $attachment_id ); // Full path
$filename_only = basename( get_attached_file( $attachment_id ) ); // Just the file name
```
Log in to add feedback

云策 WordPress 开发者社区

函数文档