云策 WordPress 开发者社区

钩子文档

wp_handle_upload_prefilter

查看官方原文 ↗
💡 云策文档标注

概述

wp_handle_upload_prefilter 是一个 WordPress 管理端过滤器，用于在文件上传前检查和修改文件数据。它允许开发者基于文件属性动态调整上传行为，如重命名文件或限制文件大小。

关键要点

  • wp_handle_upload_prefilter 是 wp_handle_upload 函数调用的过滤器，用于处理单个文件的上传数据。
  • 参数 $file 是一个数组，代表 $_FILES 数组中的单个元素，包含文件名、大小、类型等信息。
  • 通过此过滤器，开发者可以修改文件名、添加前缀、检查文件大小或类型，并设置错误信息以阻止上传。
  • 该过滤器自 WordPress 2.9.0 引入，并非已弃用，但在 4.0 版本后变为动态钩子。

代码示例

// 示例：为所有上传文件添加前缀
add_filter('wp_handle_upload_prefilter', function( $file ) {
    $file['name'] = 'wordpress-is-awesome-' . $file['name'];
    return $file;
});

// 示例：限制图片文件大小不超过 200KB
function plugin_prefix_max_image_size( $file ) {
    $limit    = 200;
    $size     = $file['size'] / 1024;
    $is_image = strpos( $file['type'], 'image' ) !== false;
    if ( $is_image && $size > $limit ) {
        $file['error'] = "Image files must be smaller than {$limit}kb";
    }
    return $file;
}
add_filter( 'wp_handle_upload_prefilter', 'plugin_prefix_max_image_size' );

注意事项

  • wp_handle_upload_prefilter 是一个管理端过滤器，仅在 WordPress 后台上传媒体时触发。
  • 修改 $file['error'] 可以阻止文件上传，并向用户显示错误消息。
  • 该过滤器与 upload_dir 过滤器结合使用，可以动态决定上传目录。
  • 注意：该过滤器在 WordPress 4.0 后变为动态钩子，但功能未变，并非已弃用。
📄 原文内容

Filter data for the current file to upload.

Parameters

$filearray
An array of data for a single file.

More Information

When you upload Media from your WordPress admin dashboard, wp_handle_upload is called once for each file the user specified. wp_handle_upload_prefilter is an admin filter that is called by the wp_handle_upload function. The single parameter, $file, represent a single element of the $_FILES array. The wp_handle_upload_prefilter provides you with an opportunity to examine or alter the filename before the file is moved to its final location.

Using this, in conjunction with the upload_dir, you can dynamically determine which directory to upload to, based on the files you upload.

add_filter('wp_handle_upload_prefilter', 'custom_upload_filter' );

function custom_upload_filter( $file ) {
$file['name'] = 'wordpress-is-awesome-' . $file['name'];
return $file;
}

Source

'txt',

View all references View on Trac View on GitHub

Changelog

Version Description
2.9.0 Introduced.

User Contributed Notes

  1. Skip to note 5 content


    David Aguilera


    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

    Example: Prevent images larger than 200kb from being uploaded.

    function plugin_prefix_max_image_size( $file ) {
  $limit    = 200;
  $size     = $file['size'] / 1024;
  $is_image = strpos( $file['type'], 'image' ) !== false;
  if ( $is_image && $size > $limit ) {
    $file['error'] = "Image files must be smaller than {$limit}kb";
  }
  return $file;
}
add_filter( 'wp_handle_upload_prefilter', 'plugin_prefix_max_image_size' );

  3. Skip to note 7 content


    Jules Colle


    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note

    Example: prepend all uploaded files with wordpress-is-awesome-

    add_filter( 'wp_handle_upload_prefilter', function( $file ) {
    $file['name'] = 'wordpress-is-awesome-' . $file['name'];
    return $file;
} );

    (According to https://wordpress.stackexchange.com/a/333935/5986 this code was originally in the docs. I’m adding it here again since I can’t find it anywhere else.)