研究 WP_Embed 类在内容中处理 oEmbed 链接的解析过程 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

WordPress oEmbed 技术内幕：WP_Embed 类深度解析

大家好！今天我们深入探讨 WordPress 中处理 oEmbed 链接的核心机制，特别是 WP_Embed 类。我们将从 oEmbed 的基本概念出发，逐步剖析 WP_Embed 类的架构、方法，以及它如何在内容中自动解析和嵌入 oEmbed 资源。

1. oEmbed 协议：内容嵌入的标准化途径

oEmbed 是一种开放格式，允许网站将其他网站的内容嵌入到自己的页面中，而无需复杂的代码或 API 集成。它通过简单的 HTTP 请求和 JSON 或 XML 响应来实现。

Provider (提供者): 提供嵌入资源的网站 (例如：YouTube, Vimeo, Twitter)。
Consumer (消费者): 消费嵌入资源的网站 (例如：WordPress)。
oEmbed Endpoint (端点): Provider 提供的 URL，Consumer 通过该 URL 请求嵌入信息。

工作流程:

Consumer 在内容中找到一个 Provider 的 URL (例如 YouTube 视频 URL)。
Consumer 向 Provider 的 oEmbed Endpoint 发送一个 HTTP 请求，包含该 URL 以及一些可选参数（例如 maxwidth, maxheight）。
Provider 返回一个 JSON 或 XML 响应，其中包含嵌入所需的 HTML 代码、元数据（例如标题、作者）和其他信息。
Consumer 将响应中的 HTML 代码嵌入到页面中。

2. `WP_Embed` 类：WordPress 的 oEmbed 引擎

WP_Embed 类是 WordPress 中负责处理 oEmbed 链接的核心类。它位于 wp-includes/class-wp-embed.php 文件中，负责以下主要任务：

自动发现 oEmbed 链接: 扫描内容，识别符合 oEmbed 格式的 URL。
查询 oEmbed Providers: 向相应的 Provider 发送请求，获取嵌入信息。
缓存 oEmbed 响应: 缓存 Provider 的响应，减少重复请求，提高性能。
生成嵌入代码: 根据 Provider 返回的响应，生成最终的 HTML 嵌入代码。

3. `WP_Embed` 类的架构和主要方法

WP_Embed 类包含多个方法，负责不同的 oEmbed 处理环节。下面列出一些核心方法：

方法名	功能描述
`__construct()`	构造函数，初始化 `WP_Embed` 类。它设置默认的 oEmbed 提供者，以及一些内置的简码。
`shortcode()`	处理简码。允许用户手动嵌入 oEmbed 资源，即使自动发现失败。
`autoembed()`	核心方法，负责自动发现和嵌入 oEmbed 链接。它扫描内容，查找匹配的 URL，并调用 `data2html()` 方法获取嵌入代码。
`data2html()`	根据 oEmbed Provider 返回的数据，生成 HTML 嵌入代码。它会根据响应类型 (例如 `photo`, `video`, `link`, `rich`) 选择不同的处理方式。
`get_data()`	向 oEmbed Provider 发送请求，获取嵌入信息。它使用 `wp_remote_get()` 函数发送 HTTP 请求，并处理响应。它也处理缓存逻辑，避免重复请求相同的 URL。
`cache_oembed()`	缓存 oEmbed 响应。它使用 WordPress 的 transient API (`set_transient()`) 缓存响应，设置一个过期时间。
`oembed_cache_key()`	生成 oEmbed 缓存的键。它根据 URL 和一些可选参数生成一个唯一的键，用于缓存和检索 oEmbed 响应。
`add_provider()`	添加自定义的 oEmbed Provider。允许开发者添加新的 oEmbed Provider，扩展 WordPress 的 oEmbed 支持。你需要提供 Provider 的 URL 模式和 oEmbed Endpoint。
`delete_oembed_cache()`	删除特定 URL 的 oEmbed 缓存。主要用于在内容更新或删除时清除缓存，确保嵌入的内容是最新的。

4. 自动发现和嵌入 oEmbed 链接：`autoembed()` 方法

autoembed() 方法是 WP_Embed 类中最关键的方法之一。它负责自动发现和嵌入 oEmbed 链接。

工作流程:

扫描内容: autoembed() 方法接收一段文本内容作为输入。它使用正则表达式扫描内容，查找符合 oEmbed 格式的 URL。WordPress 默认内置了一些常见的 oEmbed Provider 的 URL 模式，例如 YouTube、Vimeo、Twitter 等。
匹配 Provider: 对于每个找到的 URL，autoembed() 方法会检查它是否匹配已注册的 oEmbed Provider 的 URL 模式。Provider 的 URL 模式可以使用通配符 (*) 来匹配不同的 URL 格式。
获取嵌入信息: 如果找到匹配的 Provider，autoembed() 方法会调用 data2html() 方法，将 URL 传递给它。data2html() 方法会进一步调用 get_data() 方法，向 Provider 的 oEmbed Endpoint 发送请求，获取嵌入信息。
生成嵌入代码: data2html() 方法会根据 Provider 返回的响应，生成 HTML 嵌入代码。它会根据响应类型 (例如 photo, video, link, rich) 选择不同的处理方式。例如，对于 video 类型的响应，它可能会生成一个 <iframe> 标签，嵌入视频播放器。
替换 URL: 最后，autoembed() 方法会将原始的 URL 替换为生成的 HTML 嵌入代码。

示例代码 (简化版):

public function autoembed( $content ) {
    if ( empty( $this->use_autoembed ) || empty( $this->autoembed_callback ) ) {
        return $content;
    }

    $replacements = array();

    foreach ( $this->autoembed_callback as $id => $callback ) {
        $pattern = $this->autoembed_regex[ $id ];
        $content = preg_replace_callback( $pattern, array( $this, 'autoembed_callback' ), $content );
    }

    return $content;
}

protected function autoembed_callback( $matches ) {
    $url = trim( $matches[1] );

    // Avoid endless loops.
    if ( in_array( $url, $this->linked_urls, true ) ) {
        return $matches[0];
    }

    $this->linked_urls[] = $url;

    $width  = (int) $this->width;
    $height = (int) $this->height;

    $result = $this->shortcode( array( 'url' => $url, 'width' => $width, 'height' => $height ) );

    if ( ! empty( $result ) ) {
        return $result;
    } else {
        return $matches[0]; // Return the original URL if embedding fails.
    }
}

public function shortcode( $attr ) {
  $atts = shortcode_atts( array('url' => ''), $attr, 'embed');
  $url = $atts['url'];

  if ( empty( $url ) )
    return '';

  $rawattr = (array) $attr;
  $width = empty( $rawattr['width'] ) ? null : (int) $rawattr['width'];
  $height = empty( $rawattr['height'] ) ? null : (int) $rawattr['height'];

  if ( false !== stripos($url, 'soundcloud.com') ) {
    $width = 600;
  }

  $data = $this->get_data( $url, array( 'width' => $width, 'height' => $height ) );

  if ( ! $data )
    return $url;

  return $this->data2html( $data, $url );
}

5. 获取 oEmbed 数据：`get_data()` 方法

get_data() 方法负责向 oEmbed Provider 发送请求，获取嵌入信息。

工作流程:

生成缓存键: get_data() 方法首先调用 oembed_cache_key() 方法，生成一个唯一的缓存键。该缓存键基于 URL 和一些可选参数（例如 maxwidth, maxheight）生成。
检查缓存: get_data() 方法使用 get_transient() 函数检查缓存中是否已存在该 URL 的 oEmbed 响应。如果缓存命中，则直接返回缓存的响应。
发送 HTTP 请求: 如果缓存未命中，get_data() 方法使用 wp_remote_get() 函数向 Provider 的 oEmbed Endpoint 发送一个 HTTP 请求。请求中包含 URL 以及一些可选参数。
处理响应: get_data() 方法会检查 HTTP 响应的状态码。如果状态码不是 200 OK，则表示请求失败。get_data() 方法还会检查响应的 Content-Type，确保响应是 JSON 或 XML 格式。
解析响应: get_data() 方法使用 wp_remote_retrieve_body() 函数获取响应的内容。然后，它会根据响应的 Content-Type 使用 wp_json_decode() 或 simplexml_load_string() 函数解析响应。
缓存响应: get_data() 方法调用 cache_oembed() 方法，将解析后的响应缓存起来。缓存的过期时间默认为一天，可以通过 oembed_ttl 过滤器进行修改。
返回数据: get_data() 方法返回解析后的 oEmbed 数据。

示例代码 (简化版):

public function get_data( $url, $args = array() ) {
    $args = wp_parse_args( $args );

    $cache_key = $this->oembed_cache_key( $url, $args );

    $data = get_transient( $cache_key );

    if ( ! empty( $data ) ) {
        return $data;
    }

    $provider = $this->get_provider( $url, $args );

    if ( ! $provider ) {
        return false;
    }

    $remote_args = array(
        'timeout' => 10,
        'httpversion' => '1.1',
        'user-agent' => 'WordPress/' . get_bloginfo( 'version' ) . '; ' . get_bloginfo( 'url' ),
    );

    $response = wp_remote_get( $provider, $remote_args );

    if ( is_wp_error( $response ) ) {
        return false;
    }

    $response_code = wp_remote_retrieve_response_code( $response );

    if ( 200 !== (int) $response_code ) {
        return false;
    }

    $content_type = wp_remote_retrieve_header( $response, 'content-type' );

    $body = wp_remote_retrieve_body( $response );

    if ( empty( $body ) ) {
        return false;
    }

    if ( false !== strpos( $content_type, 'application/json' ) ) {
        $data = json_decode( trim( $body ), true );
    } elseif ( false !== strpos( $content_type, 'text/xml' ) || false !== strpos( $content_type, 'application/xml' ) ) {
        $data = simplexml_load_string( $body );
    } else {
        return false;
    }

    if ( empty( $data ) ) {
        return false;
    }

    $this->cache_oembed( $cache_key, $data, $url );

    return $data;
}

6. 生成 HTML 嵌入代码：`data2html()` 方法

data2html() 方法根据 oEmbed Provider 返回的数据，生成 HTML 嵌入代码。

工作流程:

检查数据类型: data2html() 方法首先检查 oEmbed 数据的 type 字段。type 字段表示嵌入资源的类型，例如 photo, video, link, rich。
根据类型生成 HTML: data2html() 方法会根据 type 字段选择不同的处理方式，生成相应的 HTML 嵌入代码。
- photo: 生成一个 <img> 标签，显示图片。
- video: 生成一个 <iframe> 标签，嵌入视频播放器。
- link: 生成一个 <a> 标签，链接到资源。
- rich: 直接使用 html 字段中的 HTML 代码。
添加 wp-embedded-content 类: data2html() 方法会给生成的 HTML 标签添加 wp-embedded-content 类。这个类可以用于自定义嵌入内容的样式。
处理 maxwidth 和 maxheight: data2html() 方法会根据 maxwidth 和 maxheight 参数，调整嵌入内容的尺寸。
返回 HTML 代码: data2html() 方法返回生成的 HTML 嵌入代码。

示例代码 (简化版):

public function data2html( $data, $url ) {
    if ( ! is_object( $data ) && ! is_array( $data ) ) {
        return false;
    }

    $return = false;

    switch ( $data['type'] ) {
        case 'photo':
            $return = '<a href="' . esc_url( $url ) . '"><img src="' . esc_url( $data['url'] ) . '" alt="' . esc_attr( $data['title'] ) . '" /></a>';
            break;
        case 'video':
            $return = $data['html'];
            break;
        case 'link':
            $return = '<a href="' . esc_url( $url ) . '">' . esc_html( $data['title'] ) . '</a>';
            break;
        case 'rich':
            $return = $data['html'];
            break;
    }

    if ( $return ) {
        $return = '<div class="wp-embedded-content">' . $return . '</div>';
    }

    return $return;
}

7. 添加自定义 oEmbed Provider：`add_provider()` 方法

add_provider() 方法允许开发者添加自定义的 oEmbed Provider，扩展 WordPress 的 oEmbed 支持。

参数:

$format: Provider 的 URL 模式。可以使用通配符 (*) 来匹配不同的 URL 格式。例如，#https?://(www.)?example.com/watch.*#i。
$endpoint: Provider 的 oEmbed Endpoint。例如，https://example.com/oembed。
$regex: 是否使用正则表达式匹配 URL。默认为 false。

示例代码:

global $wp_embed;

$wp_embed->add_provider( '#https?://(www.)?example.com/watch.*#i', 'https://example.com/oembed' );

这段代码会将 https://example.com/oembed 添加为一个新的 oEmbed Provider，用于处理 https://example.com/watch URL。

8. 缓存机制：提高性能的关键

WP_Embed 类使用 WordPress 的 transient API (set_transient(), get_transient()) 来缓存 oEmbed 响应。缓存可以显著提高性能，减少对 oEmbed Provider 的重复请求。

缓存键: 缓存键基于 URL 和一些可选参数生成，确保每个 URL 都有一个唯一的缓存。
缓存过期时间: 缓存的过期时间默认为一天，可以通过 oembed_ttl 过滤器进行修改。
缓存清除: 可以使用 delete_oembed_cache() 方法手动清除特定 URL 的 oEmbed 缓存。

9. 总结

我们深入了解了 WP_Embed 类的架构和主要方法，以及它如何在 WordPress 中处理 oEmbed 链接。WP_Embed 类通过自动发现、查询 Provider、缓存响应和生成嵌入代码，实现了 oEmbed 资源的无缝集成。理解 WP_Embed 类的工作原理对于自定义 oEmbed 功能、扩展 WordPress 的嵌入能力至关重要。

10. 如何扩展和自定义 oEmbed

添加自定义 Provider: 使用 add_provider() 方法添加新的 oEmbed Provider，支持更多网站的嵌入。
修改缓存过期时间: 使用 oembed_ttl 过滤器修改 oEmbed 缓存的过期时间。
自定义嵌入代码: 使用 embed_oembed_html 过滤器修改生成的 HTML 嵌入代码。
禁用自动嵌入: 使用 embed_oembed_discover 过滤器禁用自动嵌入功能。

11. 结论

WP_Embed 类是 WordPress 处理 oEmbed 的强大引擎。通过深入理解它的工作原理，开发者可以更好地利用 oEmbed 技术，为用户提供更丰富的嵌入体验。希望本次讲座能帮助大家更好地理解 WordPress 的 oEmbed 机制，并能运用到实际开发中。

WordPress oEmbed 技术内幕：WP_Embed 类深度解析

1. oEmbed 协议：内容嵌入的标准化途径

2. WP_Embed 类：WordPress 的 oEmbed 引擎

3. WP_Embed 类的架构和主要方法

4. 自动发现和嵌入 oEmbed 链接：autoembed() 方法

5. 获取 oEmbed 数据：get_data() 方法

6. 生成 HTML 嵌入代码：data2html() 方法

7. 添加自定义 oEmbed Provider：add_provider() 方法

8. 缓存机制：提高性能的关键

9. 总结

10. 如何扩展和自定义 oEmbed

11. 结论

发表回复 取消回复

2. `WP_Embed` 类：WordPress 的 oEmbed 引擎

3. `WP_Embed` 类的架构和主要方法

4. 自动发现和嵌入 oEmbed 链接：`autoembed()` 方法

5. 获取 oEmbed 数据：`get_data()` 方法

6. 生成 HTML 嵌入代码：`data2html()` 方法

7. 添加自定义 oEmbed Provider：`add_provider()` 方法

发表回复取消回复