发布于 由admin

详解 WordPress `wp_insert_attachment()` 函数源码：附件上传后的数据库操作与元数据处理。

同学们，晚上好！ 咱们今天来聊聊WordPress里一个相当关键的函数：wp_insert_attachment()。 它负责处理你上传的图片、视频、文档等等，并将它们的信息存入数据库，让WordPress知道你都有些什么宝贝疙瘩。 简单来说，就是附件上传成功后，WordPress如何“登记户口”的。

开场白： 附件的“户口”问题

想象一下，你辛辛苦苦上传了一个精美的图片，结果WordPress压根不知道它的存在，那岂不是白忙活了？ wp_insert_attachment() 就是来解决这个问题的，它负责在数据库里为你的附件创建一个“档案”，记录它的各种信息，比如文件名、上传路径、MIME类型等等。 这样，WordPress才能正确地管理和显示你的附件。

wp_insert_attachment() 函数概览

先来看看这个函数的庐山真面目：

/**
 * Creates a new attachment post.
 *
 * @since 2.0.0
 *
 * @param array $attachment Array of elements that make up the attachment to update.
 * @param string $file Optional path to the file.
 * @param int   $parent_post_id Optional post ID of the parent.
 * @param array $post_data Optional. An array of elements that make up the post to update.
 * @return int|WP_Error The ID of the post. WP_Error object on failure.
 */
function wp_insert_attachment( $attachment = array(), $file = null, $parent_post_id = 0, $post_data = array() ) {
    global $wpdb;

    // Sanitize, validate, and extract required information.
    $attachment = wp_parse_args( $attachment, array(
        'post_mime_type' => '',
        'guid'           => '',
        'post_parent'    => 0,
        'post_title'     => '',
        'post_content'   => '',
        'post_status'    => 'inherit',
    ) );

    if ( empty( $attachment['post_title'] ) ) {
        if ( ! empty( $attachment['file'] ) ) {
            $attachment['post_title'] = wp_basename( $attachment['file'] );
        } else {
            return new WP_Error( 'missing_attachment_title', __( 'Missing attachment title.' ) );
        }
    }

    if ( ! empty( $file ) ) {
        $attachment['file'] = $file;
    }

    if ( ! empty( $parent_post_id ) ) {
        $attachment['post_parent'] = $parent_post_id;
    }

    // Expected to be numbers.
    $attachment['post_parent'] = (int) $attachment['post_parent'];

    // Make sure we have a file name, and that it is valid.
    if ( empty( $attachment['file'] ) ) {
        return new WP_Error( 'missing_attachment_file', __( 'Missing attachment file.' ) );
    }

    // Check the file exists.
    if ( ! file_exists( $attachment['file'] ) ) {
        return new WP_Error( 'invalid_attachment_file', __( 'Invalid attachment file.' ) );
    }

    // Make sure we have a mime type.
    if ( empty( $attachment['post_mime_type'] ) ) {
        return new WP_Error( 'missing_attachment_mime_type', __( 'Missing attachment mime type.' ) );
    }

    $attachment['post_type'] = 'attachment';

    // Insert attachment.
    $id = wp_insert_post( $attachment, true, false );

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

    update_post_meta( $id, '_wp_attached_file', $attachment['file'] );

    // Generate and save attachment metadata.
    $metadata = wp_generate_attachment_metadata( $id, $attachment['file'] );
    wp_update_attachment_metadata( $id, $metadata );

    /**
     * Fires after an attachment is created.
     *
     * @since 2.1.0
     *
     * @param int $id Attachment ID.
     */
    do_action( 'add_attachment', $id );

    return $id;
}

参数说明：

  • $attachment (array): 一个包含附件各种信息的数组，比如MIME类型、GUID、父级文章ID、标题、内容、状态等等。 这是个关键参数，稍后我们会详细讲解。
  • $file (string, optional): 附件文件的路径。 默认值为 null。
  • $parent_post_id (int, optional): 附件所属的父级文章ID。 例如，你上传一张图片到某篇文章中，那么该文章的ID就是$parent_post_id。 默认值为 0。
  • $post_data (array, optional): 允许你传入一些额外的文章数据，例如修改文章的日期、作者等等。 默认值为 array()。

返回值：

  • (int|WP_Error): 如果成功，返回附件的ID。 如果失败，返回一个 WP_Error 对象，包含了错误信息。

源码拆解：一步一步扒光它

  1. 参数预处理 (Sanitize, Validate, and Extract)

    首先，函数会对传入的 $attachment 数组进行预处理，使用 wp_parse_args() 函数来填充默认值，确保我们需要的关键信息都有。

    $attachment = wp_parse_args( $attachment, array(
    'post_mime_type' => '',
    'guid'           => '',
    'post_parent'    => 0,
    'post_title'     => '',
    'post_content'   => '',
    'post_status'    => 'inherit',
) );

    wp_parse_args() 的作用是把 $attachment 数组和默认值数组合并。 如果 $attachment 数组中已经存在某个键，则保留 $attachment 中的值； 如果不存在，则使用默认值数组中的值。 这就保证了 $attachment 数组中至少包含了这些关键字段。

    接下来，是一些基本的验证和处理：

    • 标题检查: 如果附件没有标题，尝试从文件名中提取。

      if ( empty( $attachment['post_title'] ) ) {
    if ( ! empty( $attachment['file'] ) ) {
        $attachment['post_title'] = wp_basename( $attachment['file'] );
    } else {
        return new WP_Error( 'missing_attachment_title', __( 'Missing attachment title.' ) );
    }
}

    • 文件路径和父级ID赋值: 如果传入了 $file 和 $parent_post_id 参数，则更新 $attachment 数组中相应的值。

      if ( ! empty( $file ) ) {
    $attachment['file'] = $file;
}

if ( ! empty( $parent_post_id ) ) {
    $attachment['post_parent'] = $parent_post_id;
}

// Expected to be numbers.
$attachment['post_parent'] = (int) $attachment['post_parent'];

    • 关键信息校验: 确保 $attachment 数组中包含了文件路径和MIME类型，并且文件确实存在。

      if ( empty( $attachment['file'] ) ) {
    return new WP_Error( 'missing_attachment_file', __( 'Missing attachment file.' ) );
}

// Check the file exists.
if ( ! file_exists( $attachment['file'] ) ) {
    return new WP_Error( 'invalid_attachment_file', __( 'Invalid attachment file.' ) );
}

// Make sure we have a mime type.
if ( empty( $attachment['post_mime_type'] ) ) {
    return new WP_Error( 'missing_attachment_mime_type', __( 'Missing attachment mime type.' ) );
}

  2. 插入附件 (Insert Attachment)

    终于要开始往数据库里写数据了！ wp_insert_attachment() 函数内部调用了 wp_insert_post() 函数来创建一个新的文章，并且指定文章类型为 ‘attachment’。

    $attachment['post_type'] = 'attachment';

// Insert attachment.
$id = wp_insert_post( $attachment, true, false );

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

    wp_insert_post() 函数负责将 $attachment 数组中的数据插入到 wp_posts 表中。 注意，这里传递了 true 作为第二个参数，表示进行数据过滤和验证。 第三个参数 false 则表示不触发 wp_insert_post 钩子。

    如果插入失败，wp_insert_post() 会返回一个 WP_Error 对象，wp_insert_attachment() 会直接将这个错误对象返回。

  3. 更新附件元数据 (Update Attachment Metadata)

    附件光有基本信息还不够，还需要一些额外的元数据，比如附件的存储路径、尺寸等等。 wp_insert_attachment() 函数使用 update_post_meta() 和 wp_update_attachment_metadata() 函数来更新这些元数据。

    update_post_meta( $id, '_wp_attached_file', $attachment['file'] );

// Generate and save attachment metadata.
$metadata = wp_generate_attachment_metadata( $id, $attachment['file'] );
wp_update_attachment_metadata( $id, $metadata );

    • update_post_meta( $id, '_wp_attached_file', $attachment['file'] ): 这个函数将附件的存储路径保存到 wp_postmeta 表中，键名为 _wp_attached_file。

    • wp_generate_attachment_metadata( $id, $attachment['file'] ): 这个函数会根据附件的类型，生成相应的元数据。 例如，如果是图片，它会生成图片的宽度、高度、缩略图等等。

    • wp_update_attachment_metadata( $id, $metadata ): 这个函数将生成的元数据保存到 wp_postmeta 表中，键名为 _wp_attachment_metadata。

  4. 触发钩子 (Do Action)

    最后，wp_insert_attachment() 函数会触发一个 add_attachment 钩子，允许其他插件或主题对附件创建过程进行干预。

    /**
 * Fires after an attachment is created.
 *
 * @since 2.1.0
 *
 * @param int $id Attachment ID.
 */
do_action( 'add_attachment', $id );

    这个钩子传递了附件的ID作为参数，其他插件或主题可以通过这个ID来获取附件的信息，并进行一些额外的操作。

  5. 返回附件ID (Return Attachment ID)

    如果一切顺利，wp_insert_attachment() 函数会返回附件的ID。

关键数据表：附件信息存放在哪里？

wp_insert_attachment() 函数主要操作两个数据表：

  • wp_posts: 这个表存储了文章的基本信息，包括附件的ID、标题、内容、状态等等。 附件在 wp_posts 表中的 post_type 字段值为 ‘attachment’。
  • wp_postmeta: 这个表存储了文章的元数据，也就是一些附加信息。 附件的存储路径和元数据就保存在这个表中。

下面是一些常用的元数据键名：

元数据键名 含义
_wp_attached_file 附件的存储路径。
_wp_attachment_metadata 附件的元数据，例如图片的宽度、高度、缩略图等等。 这是一个序列化的数组。
_wp_attachment_image_alt 附件的ALT文本。

实战演练：如何使用 wp_insert_attachment()？

假设你要上传一张图片，并将其关联到一篇文章。 你可以这样使用 wp_insert_attachment() 函数：

$file = '/path/to/your/image.jpg'; // 你的图片路径
$parent_post_id = 123; // 父级文章的ID

$attachment = array(
    'post_mime_type' => 'image/jpeg',
    'post_title'     => preg_replace( '/.[^.]+$/', '', basename( $file ) ),
    'post_content'   => '',
    'post_status'    => 'inherit'
);

$attachment_id = wp_insert_attachment( $attachment, $file, $parent_post_id );

if ( is_wp_error( $attachment_id ) ) {
    // 处理错误
    echo 'Error: ' . $attachment_id->get_error_message();
} else {
    // 附件上传成功
    echo 'Attachment ID: ' . $attachment_id;

    // 获取附件的URL
    $image_url = wp_get_attachment_url( $attachment_id );
    echo '<img src="' . esc_url( $image_url ) . '" />';
}

代码解释：

  1. 定义文件路径和父级文章ID: 你需要指定上传的图片路径和要关联的文章ID。
  2. 构建 $attachment 数组: 这个数组包含了附件的基本信息，例如MIME类型、标题、内容、状态等等。 注意，post_title 可以从文件名中提取。
  3. 调用 wp_insert_attachment() 函数: 将 $attachment 数组、文件路径和父级文章ID传递给 wp_insert_attachment() 函数。
  4. 处理返回值: 如果上传成功，wp_insert_attachment() 函数会返回附件的ID。 你可以使用 wp_get_attachment_url() 函数来获取附件的URL，并在页面上显示图片。 如果上传失败，wp_insert_attachment() 函数会返回一个 WP_Error 对象，你需要处理这个错误。

深入理解：wp_generate_attachment_metadata() 的奥秘

wp_generate_attachment_metadata() 函数是生成附件元数据的关键。 它的逻辑比较复杂，会根据附件的类型进行不同的处理。

对于图片，它会：

  • 获取图片的宽度和高度。
  • 生成不同尺寸的缩略图。
  • 如果安装了 GD 库或 Imagick 扩展，还可以进行一些图像处理操作，例如水印、裁剪等等。

对于视频和音频，它会：

  • 获取视频和音频的长度、编码格式等等。

你可以通过 wp_get_attachment_metadata() 函数来获取附件的元数据。

$metadata = wp_get_attachment_metadata( $attachment_id );

if ( ! empty( $metadata ) ) {
    // 输出图片的宽度和高度
    echo 'Width: ' . $metadata['width'] . '<br>';
    echo 'Height: ' . $metadata['height'] . '<br>';

    // 输出缩略图的URL
    if ( ! empty( $metadata['sizes']['thumbnail']['url'] ) ) {
        echo '<img src="' . esc_url( $metadata['sizes']['thumbnail']['url'] ) . '" />';
    }
}

高级技巧：自定义附件处理流程

WordPress提供了很多钩子，允许你自定义附件的处理流程。 例如，你可以使用 add_filter() 函数来修改附件的元数据，或者使用 add_action() 函数来在附件上传后执行一些额外的操作。

/**
 * 修改附件的元数据
 *
 * @param array   $metadata  附件的元数据
 * @param int     $attachment_id 附件的ID
 * @return array
 */
function my_custom_attachment_metadata( $metadata, $attachment_id ) {
    // 在元数据中添加一个自定义字段
    $metadata['my_custom_field'] = 'This is a custom field';

    return $metadata;
}
add_filter( 'wp_generate_attachment_metadata', 'my_custom_attachment_metadata', 10, 2 );

/**
 * 在附件上传后执行一些额外的操作
 *
 * @param int $attachment_id 附件的ID
 */
function my_custom_attachment_action( $attachment_id ) {
    // 发送一封邮件通知管理员
    wp_mail( '[email protected]', 'New attachment uploaded', 'A new attachment has been uploaded with ID: ' . $attachment_id );
}
add_action( 'add_attachment', 'my_custom_attachment_action' );

总结：附件的“身份证”办理流程

wp_insert_attachment() 函数是WordPress附件管理的核心。 它负责将附件的信息存入数据库，并生成相应的元数据。 了解这个函数的原理，可以帮助你更好地管理和自定义附件的处理流程。 记住，附件的“户口”登记好，WordPress才能更好地为你服务！

思考题：

  1. 如果上传的不是图片，而是视频文件，wp_generate_attachment_metadata() 函数会生成哪些元数据？
  2. 如何使用钩子来禁止上传某些类型的文件？
  3. 如何优化附件的存储和加载性能？

希望今天的讲座对大家有所帮助！ 祝大家学习愉快！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注