详解 WordPress `wp_insert_attachment()` 函数的源码：附件上传后，如何进行数据库操作和元数据处理。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷，大家好！我是你们的老朋友，人称“WordPress百事通”的程序猿老王。今天，咱们不聊风花雪月，直接开干，深入剖析WordPress的wp_insert_attachment()函数，看看它在附件上传后，是如何在数据库里兴风作浪，以及如何处理那些五花八门的元数据的。

准备好了吗？老王要发车了！

一、wp_insert_attachment()函数：何方神圣？

首先，咱们得认识一下今天的主角wp_insert_attachment()。这个函数是WordPress负责将上传的附件信息插入到数据库中的关键人物。它接收附件的相关信息，比如文件路径、标题、描述等等，然后将其转化为数据库中的一条记录，并关联到相应的文章或页面。

简单来说，就是把你的图片、视频、PDF等文件，变成WordPress眼中可以管理的对象。

二、源码剖析：一步一个脚印

咱们直接上源码，一点一点拆解，看看这个函数是怎么运作的。为了方便阅读，我会省略一些不太重要的部分，并加上详细的注释。

function wp_insert_attachment( $attachment, $post_id = 0, $wp_error = false ) {
    global $wpdb;

    // 1. 参数验证和准备
    $defaults = array( 'post_status' => 'inherit', 'post_type' => 'attachment' );
    $attachment = wp_parse_args( $attachment, $defaults );

    // Sanitize title, if not provided.
    if ( empty( $attachment['post_title'] ) ) {
        $attachment['post_title'] = preg_replace( '/.[^.]+$/', '', wp_basename( $attachment['file'] ) );
    }

    $attachment['post_title'] = sanitize_title( $attachment['post_title'] ); //安全起见，清理标题

    // 2. 插入前的过滤器
    $attachment = apply_filters( 'wp_insert_attachment_data', $attachment, $post_id );

    // 3. 插入数据库
    $attachment_id = wp_insert_post( $attachment, $wp_error );

    if ( is_wp_error( $attachment_id ) ) {
        return $attachment_id;
    }

    // 4. 更新附件元数据（重点！）
    if ( ! empty( $attachment['file'] ) ) {
        $file = $attachment['file'];
        $file_array = array();

        // Fill in required fields for wp_generate_attachment_metadata().
        $file_array['tmp_name'] = $file; // 临时文件名
        $file_array['name'] = wp_basename( $file ); // 原始文件名

        $attachment_metadata = wp_generate_attachment_metadata( $attachment_id, $file ); // 生成元数据

        wp_update_attachment_metadata( $attachment_id, $attachment_metadata ); // 更新元数据
    }

    // 5. 设置附件关联的文章
    if ( $post_id ) {
        add_post_meta( $attachment_id, '_wp_attached_file', $attachment['file'] ); // 保存附件路径
        update_post_meta( $attachment_id, '_wp_attachment_metadata', $attachment_metadata ); //保存元数据

    }

    // 6. 插入后的过滤器
    do_action( 'wp_insert_attachment', $attachment_id );

    return $attachment_id;
}

看起来是不是有点眼花缭乱？别怕，老王给你慢慢讲解。

2.1 参数验证和准备：穿上防护服

首先，函数会接收一个 $attachment 数组，这个数组包含了附件的各种信息，比如标题、描述、文件路径等等。$post_id 参数表示附件要关联到的文章或页面的ID。$wp_error 参数决定是否返回 WP_Error 对象来表示错误。

wp_parse_args() 函数会将传入的 $attachment 数组与默认值合并，确保必要的字段都存在。如果没有提供标题，函数会尝试从文件名中提取一个，并进行清理，防止出现恶意代码。

2.2 插入前的过滤器：未雨绸缪

apply_filters( 'wp_insert_attachment_data', $attachment, $post_id ) 这一行非常重要。它允许其他插件或主题通过过滤器修改 $attachment 数组，在附件信息真正插入数据库之前进行一些自定义的操作。这就像给附件穿上防护服，可以防止一些潜在的问题。

2.3 插入数据库：落户安家

wp_insert_post( $attachment, $wp_error ) 函数是真正将附件信息插入到 wp_posts 表中的关键。它会创建一个新的文章记录，并将附件的各种属性存储到相应的字段中。

wp_posts 表的 post_type 字段会被设置为 'attachment'，表示这是一个附件类型的文章。

2.4 更新附件元数据：精雕细琢

这部分是整个函数的核心，也是我们今天要重点关注的地方。

wp_generate_attachment_metadata()：生成元数据

这个函数会根据附件的文件类型，生成相应的元数据。比如，如果是图片，它会生成图片的宽度、高度、缩略图等等。如果是视频，它会生成视频的长度、编码等等。

这个函数内部会调用不同的函数来处理不同类型的附件。比如，对于图片，它会调用 wp_get_image_editor() 函数来获取图像编辑器对象，然后使用该对象来获取图片的尺寸、生成缩略图等等。

生成的元数据通常是一个数组，包含了各种关于附件的信息。
wp_update_attachment_metadata()：更新元数据

这个函数会将 wp_generate_attachment_metadata() 函数生成的元数据存储到 wp_postmeta 表中。wp_postmeta 表是WordPress用来存储文章、页面、附件等等的元数据的通用表。

它会将元数据序列化后，存储到 wp_postmeta 表的 meta_value 字段中。meta_key 字段则会被设置为 _wp_attachment_metadata。

2.5 设置附件关联的文章：建立联系

如果提供了 $post_id 参数，函数会使用 add_post_meta() 和 update_post_meta() 函数来设置附件与文章或页面之间的关联。

add_post_meta( $attachment_id, '_wp_attached_file', $attachment['file'] )：保存附件的路径。
update_post_meta( $attachment_id, '_wp_attachment_metadata', $attachment_metadata )：保存附件的元数据。

这两个函数会将相应的元数据存储到 wp_postmeta 表中，meta_key 分别为 _wp_attached_file 和 _wp_attachment_metadata。

2.6 插入后的过滤器：盖棺定论

do_action( 'wp_insert_attachment', $attachment_id ) 这一行会触发一个 action hook，允许其他插件或主题在附件插入完成后执行一些自定义的操作。这就像给附件盖棺定论，可以做一些收尾工作。

三、数据库操作：抽丝剥茧

咱们来具体看看 wp_insert_attachment() 函数在数据库里都做了些什么。

wp_posts 表：
- 插入一条新的记录，post_type 字段设置为 'attachment'。
- post_title 字段设置为附件的标题。
- post_content 字段可以设置为附件的描述。
- post_status 字段设置为 'inherit'，表示附件的状态继承自其关联的文章或页面。
wp_postmeta 表：
- 插入或更新三条记录：
  - meta_key 为 _wp_attached_file，meta_value 为附件的路径。
  - meta_key 为 _wp_attachment_metadata，meta_value 为附件的元数据（序列化后的数组）。
  - meta_key 为 _wp_attachment_image_alt，meta_value 为附件的alt描述(如果没有描述则为空)。

为了更清晰地展示，咱们用一个表格来总结一下：

表名	操作	字段	说明
`wp_posts`	插入	`post_type`	设置为 `'attachment'`，表示这是一个附件类型的文章。
`wp_posts`	插入	`post_title`	附件的标题。
`wp_posts`	插入	`post_content`	附件的描述。
`wp_posts`	插入	`post_status`	设置为 `'inherit'`，表示附件的状态继承自其关联的文章或页面。
`wp_postmeta`	插入/更新	`meta_key` 为 `_wp_attached_file`	`meta_value` 为附件的路径。
`wp_postmeta`	插入/更新	`meta_key` 为 `_wp_attachment_metadata`	`meta_value` 为附件的元数据（序列化后的数组），包含了图片的宽度、高度、缩略图等等信息。
`wp_postmeta`	插入/更新	`meta_key` 为 `_wp_attachment_image_alt`	`meta_value` 为附件的alt描述。

四、元数据处理：知根知底

wp_generate_attachment_metadata() 函数生成的元数据到底长什么样呢？咱们以图片为例，看看它的结构：

array(
    'width'  => 800,      // 图片宽度
    'height' => 600,      // 图片高度
    'file'   => '2023/10/my-image.jpg', // 原始文件路径（相对于 uploads 目录）
    'sizes'  => array(
        'thumbnail' => array(
            'file'   => 'my-image-150x150.jpg',
            'width'  => 150,
            'height' => 150,
            'mime-type' => 'image/jpeg',
        ),
        'medium'    => array(
            'file'   => 'my-image-300x225.jpg',
            'width'  => 300,
            'height' => 225,
            'mime-type' => 'image/jpeg',
        ),
        'large'     => array(
            'file'   => 'my-image-600x450.jpg',
            'width'  => 600,
            'height' => 450,
            'mime-type' => 'image/jpeg',
        ),
        'full' => array(
            'file'   => 'my-image.jpg',
            'width'  => 800,
            'height' => 600,
            'mime-type' => 'image/jpeg',
        ),
    ),
    'image_meta' => array( // 图片的 EXIF 信息
        'aperture'          => '2.8',
        'credit'            => '',
        'camera'            => 'Canon EOS 5D Mark III',
        'caption'           => '',
        'created_timestamp' => '1698883200',
        'copyright'         => '',
        'focal_length'      => '50',
        'iso'               => '100',
        'shutter_speed'     => '1/100',
        'title'             => '',
        'orientation'       => '1',
        'keywords'          => array(),
    ),
)

可以看到，这个数组包含了图片的宽度、高度、文件路径、各种尺寸的缩略图，以及图片的 EXIF 信息。

WordPress会根据这些元数据，在前端展示图片的时候，自动选择合适的尺寸，并提供一些其他的功能，比如显示图片的 EXIF 信息等等。

五、自定义扩展：任你发挥

wp_insert_attachment() 函数提供了很多过滤器和 action hook，允许开发者进行自定义扩展。

wp_insert_attachment_data 过滤器：
- 可以在附件信息插入数据库之前，修改 $attachment 数组。
- 可以用来添加自定义的字段，或者修改已有的字段。
wp_insert_attachment action hook：
- 可以在附件插入数据库之后，执行一些自定义的操作。
- 可以用来发送通知邮件，或者更新缓存等等。

举个栗子：

假设你想在附件上传后，自动给图片添加一个水印。你可以使用 wp_insert_attachment action hook 来实现：

add_action( 'wp_insert_attachment', 'my_add_watermark_to_image' );

function my_add_watermark_to_image( $attachment_id ) {
    // 获取附件的元数据
    $metadata = wp_get_attachment_metadata( $attachment_id );

    // 检查是否是图片
    if ( ! isset( $metadata['mime-type'] ) || strpos( $metadata['mime-type'], 'image/' ) === false ) {
        return;
    }

    // 获取图片的路径
    $file = get_attached_file( $attachment_id );

    // 添加水印的代码（这里省略）
    // ...

    // 更新附件的元数据
    wp_update_attachment_metadata( $attachment_id, $metadata );
}

六、总结：胸有成竹

今天，咱们一起深入剖析了 WordPress 的 wp_insert_attachment() 函数，了解了它在附件上传后，是如何在数据库里兴风作浪，以及如何处理那些五花八门的元数据的。

希望通过今天的讲解，各位观众老爷能够对 wp_insert_attachment() 函数有一个更深入的理解，并在实际开发中灵活运用。

记住，掌握了这些知识，你就可以更好地控制 WordPress 的附件管理，并构建出更加强大的插件和主题。

好了，今天的讲座就到这里。如果大家有什么疑问，欢迎在评论区留言。老王会尽力解答。

咱们下期再见！

发表回复 取消回复

发表回复取消回复