WordPress源码深度解析之：`WordPress`的`Media Library`：媒体上传与元数据的底层存储。

大家好，欢迎来到“WordPress源码深度解析”系列讲座！今天我们要啃的骨头是WordPress的“Media Library”（媒体库）。别担心，我会尽量把它讲得像吃薯片一样轻松。我们不仅要搞清楚媒体文件怎么上传，还要深挖那些看不见的“元数据”是如何被WordPress悄悄保存起来的。准备好了吗？Let’s roll!

开场白：Media Library 的“前世今生”

想象一下，你写了一篇精彩绝伦的博客，但如果光秃秃的只有文字，是不是有点寂寞？这时候，就需要图片、视频这些“颜值担当”来撑场面了。WordPress的Media Library就是专门用来管理这些“颜值担当”的。它不仅能上传文件，还能存储关于这些文件的各种信息，比如标题、描述、拍摄时间等等。这些信息，我们统称为“元数据”。

第一部分：媒体文件的上传流程

上传文件，听起来简单，但WordPress在背后做了很多事情。让我们来一步一步分解一下：

1. 用户选择文件： 在后台，用户通过Media Library的上传界面，选择要上传的文件。
2. 前端验证： 在文件正式上传到服务器之前，前端会做一些基本的验证，比如文件类型、大小等。这部分通常使用JavaScript实现。
3. 文件上传： 文件通过HTTP POST请求发送到服务器。WordPress使用wp_handle_upload()函数来处理上传的文件。
4. 文件存储： wp_handle_upload()函数会将文件保存到wp-content/uploads目录下。WordPress会根据年月创建子目录，方便管理。
5. 生成缩略图： WordPress会自动生成不同尺寸的缩略图，方便在不同的场景中使用。
6. 数据库记录： 最重要的一步！WordPress会在数据库中创建一个attachment类型的post，用来记录这个文件的信息，包括文件路径、MIME类型、尺寸、以及各种元数据。

下面我们重点看看wp_handle_upload()这个函数，它可是上传流程的核心：

function wp_handle_upload( &$file, $overrides = false, $time = null ) {
    // 各种安全检查...

    // 创建上传目录
    $upload_dir = wp_upload_dir( $time );

    // 生成唯一的文件名
    $filename = wp_unique_filename( $upload_dir['path'], $file['name'], $unique_filename_callback );

    // 移动文件到上传目录
    $new_file = $upload_dir['path'] . "/$filename";
    $move_new_file = @move_uploaded_file( $file['tmp_name'], $new_file );

    // 获取文件类型
    $wp_filetype = wp_check_filetype( $new_file, null );

    // 构建返回数组
    $return = array(
        'file' => $filename,
        'url'  => $upload_dir['url'] . "/$filename",
        'type' => $wp_filetype['type']
    );

    // ...更多处理，比如生成缩略图...

    return $return;
}

这个函数做了很多事情，包括：

• 安全检查： 确保上传的文件是安全的，防止恶意代码注入。
• 创建上传目录： 使用wp_upload_dir()函数获取上传目录，并根据年月创建子目录。
• 生成唯一的文件名： 使用wp_unique_filename()函数生成唯一的文件名，避免文件覆盖。
• 移动文件： 将上传的文件移动到上传目录。
• 获取文件类型： 使用wp_check_filetype()函数获取文件的MIME类型。
• 构建返回数组： 将文件的相关信息封装成一个数组，返回给调用者。

第二部分：元数据的存储与管理

上传文件只是第一步，更重要的是如何存储和管理这些文件的元数据。WordPress使用两种方式来存储元数据：

1. wp_posts表： 文件本身的信息，比如文件路径、MIME类型、尺寸等，存储在wp_posts表中。每个上传的文件都会在wp_posts表中创建一个attachment类型的post。
2. wp_postmeta表： 其他的元数据，比如标题、描述、拍摄时间等，存储在wp_postmeta表中。wp_postmeta表是一个键值对存储表，可以存储任意类型的元数据。

让我们来看一个例子：

假设我们上传了一张名为sunset.jpg的图片。

• wp_posts表：

ID	post_author	post_date	post_content	post_title	post_status	post_type	guid
123	1	2023-10-27 10:00:00		sunset.jpg	inherit	attachment	http://example.com/wp-content/uploads/2023/10/sunset.jpg

• wp_postmeta表：

meta_id	post_id	meta_key	meta_value
456	123	_wp_attached_file	2023/10/sunset.jpg
457	123	_wp_attachment_metadata	a:5:{s:5:"width";i:1920;s:6:"height";i:1080;s:4:"file";s:16:"2023/10/sunset.jpg";s:5:"sizes";a:5:{s:9:"thumbnail";a:4:{s:4:"file";s:20:"sunset-150×150.jpg";s:5:"width";i:150;s:6:"height";i:150;s:9:"mime-type";s:10:"image/jpeg";}s:6:"medium";a:4:{s:4:"file";s:20:"sunset-300×169.jpg";s:5:"width";i:300;s:6:"height";i:169;s:9:"mime-type";s:10:"image/jpeg";}s:5:"large";a:4:{s:4:"file";s:21:"sunset-1024×576.jpg";s:5:"width";i:1024;s:6:"height";i:576;s:9:"mime-type";s:10:"image/jpeg";}s:12:"medium_large";a:4:{s:4:"file";s:21:"sunset-768×432.jpg";s:5:"width";i:768;s:6:"height";i:432;s:9:"mime-type";s:10:"image/jpeg";}s:10:"full";a:4:{s:4:"file";s:16:"2023/10/sunset.jpg";s:5:"width";i:1920;s:6:"height";i:1080;s:9:"mime-type";s:10:"image/jpeg";}}s:10:"image_meta";a:12:{s:8:"aperture";s:1:"0";s:6:"credit";s:0:"";s:12:"camera";s:0:"";s:7:"caption";s:0:"";s:17:"created_timestamp";s:1:"0";s:9:"copyright";s:0:"";s:12:"focal_length";s:1:"0";s:3:"iso";s:1:"0";s:13:"shutter_speed";s:1:"0";s:5:"title";s:0:"";s:11:"orientation";s:1:"1";s:8:"keywords";a:0:{}}

从上面的例子可以看出：

• wp_posts表存储了图片的基本信息，比如ID、作者、上传时间、标题、文件路径等。
• wp_postmeta表存储了图片的详细信息，比如文件存储路径（相对于wp-content/uploads目录）、图片的尺寸、缩略图的信息、图片的EXIF信息等。

注意，_wp_attachment_metadata这个meta_key对应的meta_value是一个序列化的数组。这是WordPress常用的存储复杂数据的方式。

第三部分：与 Media Library 相关的常用函数

WordPress提供了很多函数来操作Media Library。下面列出一些常用的：

函数名	功能
wp_upload_dir()	获取上传目录的信息，包括路径、URL等。
wp_handle_upload()	处理上传的文件，保存到上传目录，并生成缩略图。
wp_insert_attachment()	在wp_posts表中创建一个attachment类型的post，记录文件的信息。
wp_get_attachment_url()	获取附件的URL。
wp_get_attachment_image()	获取附件的HTML代码，包括<img>标签。
get_post_meta()	获取post的meta数据。
update_post_meta()	更新post的meta数据。
delete_post_meta()	删除post的meta数据。

下面我们来看几个例子：

• 获取上传目录的信息：

$upload_dir = wp_upload_dir();
echo '<pre>';
print_r( $upload_dir );
echo '</pre>';

• 创建一个attachment类型的post：

$file = '/path/to/your/image.jpg';
$filename = basename( $file );
$upload_file = wp_upload_bits( $filename, null, file_get_contents( $file ) );
if ( ! $upload_file['error'] ) {
    $wp_filetype = wp_check_filetype( $filename, null );
    $attachment = array(
        'post_mime_type' => $wp_filetype['type'],
        'post_title'     => preg_replace( '/.[^.]+$/', '', $filename ),
        'post_content'   => '',
        'post_status'    => 'inherit'
    );
    $attach_id = wp_insert_attachment( $attachment, $upload_file['file'] );
    require_once( ABSPATH . 'wp-admin/includes/image.php' );
    $attach_data = wp_generate_attachment_metadata( $attach_id, $upload_file['file'] );
    wp_update_attachment_metadata( $attach_id, $attach_data );
}

• 获取附件的URL：

$attachment_id = 123; // 附件的ID
$attachment_url = wp_get_attachment_url( $attachment_id );
echo '<img src="' . esc_url( $attachment_url ) . '" alt="">';

第四部分：Media Library 的扩展与定制

WordPress的Media Library非常灵活，可以通过插件和主题进行扩展和定制。下面是一些常见的扩展和定制方式：

1. 自定义元数据： 可以通过add_post_meta_box()函数添加自定义的meta box，让用户可以输入自定义的元数据。
2. 自定义上传处理： 可以通过wp_handle_upload_prefilter和wp_handle_upload等filter，自定义上传文件的处理流程。
3. 自定义缩略图尺寸： 可以通过add_image_size()函数添加自定义的缩略图尺寸。
4. 自定义Media Library界面： 可以通过JavaScript和CSS，自定义Media Library的界面。

例如，我们可以添加一个自定义的meta box，让用户可以输入图片的拍摄地点：

add_action( 'add_meta_boxes', 'add_image_location_meta_box' );
function add_image_location_meta_box() {
    add_meta_box(
        'image_location',
        '拍摄地点',
        'image_location_meta_box_callback',
        'attachment',
        'side',
        'default'
    );
}

function image_location_meta_box_callback( $post ) {
    wp_nonce_field( 'image_location_nonce', 'image_location_nonce' );
    $location = get_post_meta( $post->ID, '_image_location', true );
    echo '<label for="image_location">地点：</label>';
    echo '<input type="text" id="image_location" name="image_location" value="' . esc_attr( $location ) . '" size="25">';
}

add_action( 'save_post', 'save_image_location_meta' );
function save_image_location_meta( $post_id ) {
    if ( ! isset( $_POST['image_location_nonce'] ) ) {
        return;
    }
    if ( ! wp_verify_nonce( $_POST['image_location_nonce'], 'image_location_nonce' ) ) {
        return;
    }
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
        return;
    }
    if ( ! current_user_can( 'edit_post', $post_id ) ) {
        return;
    }

    $location = sanitize_text_field( $_POST['image_location'] );
    update_post_meta( $post_id, '_image_location', $location );
}

这段代码会在Media Library的编辑界面添加一个名为“拍摄地点”的meta box，用户可以在这个meta box中输入图片的拍摄地点。这个拍摄地点的信息会被存储在wp_postmeta表中，meta_key为_image_location。

总结：Media Library 的“灵魂”

Media Library是WordPress的核心功能之一，它不仅能上传和管理媒体文件，还能存储和管理这些文件的元数据。理解Media Library的底层存储机制，可以帮助我们更好地扩展和定制Media Library，满足各种需求。

今天的讲座就到这里。希望大家对WordPress的Media Library有了更深入的了解。下次再见！