函数文档

_load_image_to_edit_path()

💡 云策文档标注

概述

_load_image_to_edit_path() 函数用于获取附件文件的路径或 URL,支持本地文件系统和远程 URL 处理。它根据附件 ID 和指定尺寸返回文件路径或 URL,若文件不存在且服务器支持 allow_url_fopen,则返回 URL。

关键要点

  • 函数接受两个参数:$attachment_id(必需,附件 ID)和 $size(可选,图像尺寸,默认为 'full')。
  • 返回值为字符串(成功时文件路径或 URL)或 false(失败时)。
  • 优先检查本地文件是否存在,若存在且尺寸非 'full',则通过 image_get_intermediate_size() 获取中间尺寸路径。
  • 若本地文件不存在且 allow_url_fopen 启用,则返回附件 URL 并应用相关过滤器。
  • 提供了多个过滤器钩子,如 load_image_to_edit_filesystempath、load_image_to_edit_attachmenturl 和 load_image_to_edit_path,用于自定义路径或 URL 处理。

代码示例

function _load_image_to_edit_path( $attachment_id, $size = 'full' ) {
    $filepath = get_attached_file( $attachment_id );

    if ( $filepath && file_exists( $filepath ) ) {
        if ( 'full' !== $size ) {
            $data = image_get_intermediate_size( $attachment_id, $size );

            if ( $data ) {
                $filepath = path_join( dirname( $filepath ), $data['file'] );
                $filepath = apply_filters( 'load_image_to_edit_filesystempath', $filepath, $attachment_id, $size );
            }
        }
    } elseif ( function_exists( 'fopen' ) && ini_get( 'allow_url_fopen' ) ) {
        $filepath = apply_filters( 'load_image_to_edit_attachmenturl', wp_get_attachment_url( $attachment_id ), $attachment_id, $size );
    }

    return apply_filters( 'load_image_to_edit_path', $filepath, $attachment_id, $size );
}

注意事项

  • 该函数自 WordPress 3.4.0 版本引入,主要用于图像编辑场景。
  • 相关函数包括 get_attached_file()、image_get_intermediate_size()、wp_get_attachment_url() 和 path_join()。
  • 在远程文件处理时,需确保服务器配置支持 allow_url_fopen。

📄 原文内容

Retrieves the path or URL of an attachment’s attached file.

Description

If the attached file is not present on the local filesystem (usually due to replication plugins), then the URL of the file is returned if allow_url_fopen is supported.

Parameters

$attachment_idintrequired
Attachment ID.
$sizestring|int[]optional
Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order). Default 'full'.

Return

string|false File path or URL on success, false on failure.

Source

function _load_image_to_edit_path( $attachment_id, $size = 'full' ) {
	$filepath = get_attached_file( $attachment_id );

	if ( $filepath && file_exists( $filepath ) ) {
		if ( 'full' !== $size ) {
			$data = image_get_intermediate_size( $attachment_id, $size );

			if ( $data ) {
				$filepath = path_join( dirname( $filepath ), $data['file'] );

				/**
				 * Filters the path to an attachment's file when editing the image.
				 *
				 * The filter is evaluated for all image sizes except 'full'.
				 *
				 * @since 3.1.0
				 *
				 * @param string       $path          Path to the current image.
				 * @param int          $attachment_id Attachment ID.
				 * @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).
				 */
				$filepath = apply_filters( 'load_image_to_edit_filesystempath', $filepath, $attachment_id, $size );
			}
		}
	} elseif ( function_exists( 'fopen' ) && ini_get( 'allow_url_fopen' ) ) {
		/**
		 * Filters the path to an attachment's URL when editing the image.
		 *
		 * The filter is only evaluated if the file isn't stored locally and `allow_url_fopen` is enabled on the server.
		 *
		 * @since 3.1.0
		 *
		 * @param string|false $image_url     Current image URL.
		 * @param int          $attachment_id Attachment ID.
		 * @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).
		 */
		$filepath = apply_filters( 'load_image_to_edit_attachmenturl', wp_get_attachment_url( $attachment_id ), $attachment_id, $size );
	}

	/**
	 * Filters the returned path or URL of the current image.
	 *
	 * @since 2.9.0
	 *
	 * @param string|false $filepath      File path or URL to current image, or false.
	 * @param int          $attachment_id Attachment ID.
	 * @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).
	 */
	return apply_filters( 'load_image_to_edit_path', $filepath, $attachment_id, $size );
}

Hooks

apply_filters( ‘load_image_to_edit_attachmenturl’, string|false $image_url, int $attachment_id, string|int[] $size )

Filters the path to an attachment’s URL when editing the image.

apply_filters( ‘load_image_to_edit_filesystempath’, string $path, int $attachment_id, string|int[] $size )

Filters the path to an attachment’s file when editing the image.

apply_filters( ‘load_image_to_edit_path’, string|false $filepath, int $attachment_id, string|int[] $size )

Filters the returned path or URL of the current image.

Changelog

Version Description
3.4.0 Introduced.