分析 WordPress `the_content()` 函数的源码：它如何通过 `the_content` 过滤器处理文章内容。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

大家好，欢迎来到今天的 WordPress 内核深度解析讲座！今天我们要聊的，是 WordPress 中一个至关重要的函数 —— the_content()。你可能会觉得它很简单，不就是输出文章内容吗？但实际上，它背后的机制远比你想象的要复杂和有趣。

咱们今天要像剥洋葱一样，一层层地揭开 the_content() 的神秘面纱，看看它是如何通过 the_content 过滤器，把原始的文章内容变成我们最终看到的精美网页的。

开场白：the_content() 是什么？

简单来说，the_content() 函数的作用就是输出当前文章的内容。它通常被放在主题的 single.php (单篇文章页面) 或者 page.php (页面) 这样的模板文件中。

<?php
if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        the_content(); // 这就是我们今天的主角！
    endwhile;
endif;
?>

但是，如果你认为 the_content() 只是简单地 echo 了一下文章内容，那就太小看它了。实际上，在输出内容之前，the_content() 会对文章内容进行一系列的处理，而这些处理的核心就是 the_content 过滤器。

the_content 过滤器：文章内容的变形金刚

the_content 过滤器是一个强大的 Hook，允许开发者在文章内容显示之前对其进行修改。想象一下，你写了一篇很棒的文章，但是你想在文章的开头添加一些广告，或者在文章中自动插入一些图片，又或者你想把文章中的某些关键词替换成链接，the_content 过滤器都能帮你实现。

你可以把它看作是一个文章内容处理的流水线，你可以在流水线的不同环节添加自己的处理工序，最终得到你想要的结果。

the_content() 源码解析：一步一步看它怎么运作

让我们一起深入 the_content() 的源码，看看它到底是如何工作的。为了方便理解，我这里简化了部分代码，保留了核心逻辑。

function the_content( $more_link_text = null, $strip_teaser = false ) {
  $content = get_the_content( $more_link_text, $strip_teaser );

  $content = apply_filters( 'the_content', $content );

  $content = str_replace( ']]>', ']]&gt;', $content );

  echo $content;
}

可以看到，the_content() 函数主要做了三件事：

获取文章内容： 调用 get_the_content() 函数来获取文章的原始内容。
应用过滤器： 使用 apply_filters( 'the_content', $content ) 来应用 the_content 过滤器，对文章内容进行处理。
替换特殊字符： 将文章内容中的 ]]> 替换为 ]]>，这是一个为了防止某些插件或者主题出现问题的安全措施。
输出内容： 使用 echo 函数将处理后的文章内容输出到页面上。

现在，我们来详细分析一下这三个步骤。

1. get_the_content()：获取文章的原始素材

get_the_content() 函数负责从数据库中获取文章的原始内容。它还会处理  标签，用于实现文章的摘要和全文显示。

function get_the_content( $more_link_text = null, $strip_teaser = false ) {
  global $post, $more;

  $output = '';
  $content = get_post_field( 'post_content', $post->ID );

  if ( post_password_required( $post ) ) {
    return get_the_password_form( $post );
  }

  if ( null === $more_link_text ) {
    $more_link_text = __( '(继续阅读)' );
  }

  // 检查是否有 <!--more--> 标签
  if ( strpos( $content, '<!--more-->' ) ) {
    $content = explode( '<!--more-->', $content, 2 );
    if ( ! empty( $more ) && $strip_teaser ) {
      $output = _cleanup_header_comment( $content[1] );
    } else {
      $output = _cleanup_header_comment( $content[0] );
      $output .= '<span id="more-' . $post->ID . '"></span>' . _wp_link_page( 1 ) . '<a href="' . get_permalink() . "#more-" . $post->ID .'" class="more-link">' . $more_link_text . '</a>';
    }
  } else {
    $output = _cleanup_header_comment( $content );
  }

  return apply_filters( 'get_the_content', $output );
}

这个函数做了这些事情：

获取文章内容： 使用 get_post_field( 'post_content', $post->ID ) 从数据库中获取文章的原始内容。
密码保护： 如果文章设置了密码保护，则返回密码输入表单。
处理  标签： 如果文章中使用了  标签，则根据 $more 和 $strip_teaser 的值，决定是显示摘要还是全文。
应用过滤器： 使用 apply_filters( 'get_the_content', $output ) 应用 get_the_content 过滤器。

2. apply_filters( 'the_content', $content )：核心所在

apply_filters() 函数是 WordPress 过滤器机制的核心。它的作用是将文章内容传递给所有注册到 the_content 过滤器上的函数进行处理，最终返回处理后的文章内容。

$content = apply_filters( 'the_content', $content );

这行代码就像一个魔法入口，所有的文章内容处理都发生在这里。让我们来仔细看看它是如何工作的。

apply_filters() 的工作原理

apply_filters() 函数接收两个或多个参数：

过滤器名称： 这里是 'the_content'，表示我们要应用的是 the_content 过滤器。
要过滤的值： 这里是 $content，表示我们要过滤的文章内容。
其他参数： 可选参数，可以传递给过滤器函数。

apply_filters() 函数会遍历所有注册到 'the_content' 过滤器上的函数，依次调用这些函数，并将文章内容作为参数传递给它们。每个函数都可以对文章内容进行修改，并将修改后的内容返回给 apply_filters() 函数。 apply_filters() 函数会将每个函数返回的内容依次传递给下一个函数，直到所有函数都执行完毕。最终，apply_filters() 函数会返回经过所有函数处理后的文章内容。

默认的 the_content 过滤器函数

WordPress 核心以及一些插件和主题，会默认注册一些函数到 the_content 过滤器上。这些函数负责处理文章内容中的各种特殊格式，例如：

函数名称	功能描述
`wpautop()`	自动将文本中的换行符转换为 HTML 的 `<p>` 和 `<br>` 标签，实现段落和换行的自动格式化。
`shortcode_unautop()`	移除由 `wpautop()` 函数自动添加的短代码周围的 `<p>` 标签，防止短代码的显示出现问题。
`do_shortcode()`	解析并执行文章内容中的短代码。
`convert_smilies()`	将文章内容中的文本表情符号（例如 `:)`、`:(`）转换为对应的图片表情。
`wptexturize()`	将文章内容中的普通引号、省略号、破折号等字符转换为排版更美观的特殊字符。
`convert_chars()`	将文章内容中的一些 HTML 实体转换为对应的字符。
`make_clickable()`	自动将文章内容中的 URL 转换为可点击的链接。
`force_balance_tags()`	强制平衡文章内容中的 HTML 标签，防止 HTML 结构错误。
`capital_P_dangit()`	将文章内容中的 "WordPress" 修正为 "WordPress"。
`wp_kses_post()`	使用 WordPress 的 KSES 过滤系统，对文章内容进行安全过滤，移除不安全的 HTML 标签和属性。

这些函数按照一定的顺序依次执行，共同完成了对文章内容的格式化、美化和安全处理。

3. str_replace( ']]>', ']]>', $content )：安全小卫士

这行代码的作用是将文章内容中的 ]]> 替换为 ]]>。这是一个为了防止某些插件或者主题出现问题的安全措施。在某些情况下，]]> 可能会被误认为是 HTML 注释的结束标签，导致页面显示错误。

4. echo $content：最终呈现

最后，the_content() 函数使用 echo 函数将经过所有处理后的文章内容输出到页面上，呈现在用户面前。

自定义 the_content 过滤器：打造你的专属内容处理流水线

现在，你已经了解了 the_content() 函数的工作原理。接下来，让我们来看看如何自定义 the_content 过滤器，实现你自己的文章内容处理逻辑。

使用 add_filter() 函数注册过滤器函数

要自定义 the_content 过滤器，你需要使用 add_filter() 函数。 add_filter() 函数接收三个参数：

过滤器名称： 这里是 'the_content'，表示我们要注册到 the_content 过滤器上。
过滤器函数： 你要定义的处理文章内容的函数。
优先级（可选）： 指定过滤器函数的执行顺序，默认为 10。数字越小，优先级越高，越先执行。
参数个数（可选）： 指定过滤器函数接收的参数个数，默认为 1。

例如，如果你想在文章的开头添加一段广告，你可以这样写：

function add_ad_to_content( $content ) {
  $ad = '<div class="ad">这里是广告</div>';
  return $ad . $content;
}
add_filter( 'the_content', 'add_ad_to_content' );

这段代码会将 add_ad_to_content() 函数注册到 the_content 过滤器上。当 the_content() 函数被调用时，add_ad_to_content() 函数会被自动执行，并将文章内容作为参数传递给它。 add_ad_to_content() 函数会在文章内容的开头添加一段广告，并将修改后的内容返回给 the_content() 函数。

更复杂的例子：自动插入图片

假设你想在文章中每隔一段文字自动插入一张图片，你可以这样写：

function insert_image_into_content( $content ) {
  $image_url = 'http://example.com/image.jpg';
  $image_tag = '<img src="' . $image_url . '" alt="自动插入的图片">';

  $paragraphs = explode( '</p>', $content );
  $paragraph_count = count( $paragraphs );

  $new_content = '';
  for ( $i = 0; $i < $paragraph_count; $i++ ) {
    $new_content .= $paragraphs[ $i ] . '</p>';
    if ( ( $i + 1 ) % 3 == 0 ) { // 每隔3段插入一张图片
      $new_content .= $image_tag;
    }
  }

  return $new_content;
}
add_filter( 'the_content', 'insert_image_into_content' );

这段代码会将 insert_image_into_content() 函数注册到 the_content 过滤器上。当 the_content() 函数被调用时，insert_image_into_content() 函数会被自动执行，并将文章内容作为参数传递给它。 insert_image_into_content() 函数会将文章内容分割成段落，并在每隔 3 段文字后插入一张图片，并将修改后的内容返回给 the_content() 函数。

总结：the_content() 的强大之处

通过今天的讲座，我们深入了解了 WordPress 的 the_content() 函数及其背后的 the_content 过滤器机制。我们可以得出以下结论：

the_content() 函数不仅仅是输出文章内容，它还是一个强大的内容处理中心。
the_content 过滤器允许开发者在文章内容显示之前对其进行修改，实现各种各样的自定义功能。
通过自定义 the_content 过滤器，你可以打造你自己的专属内容处理流水线，让你的 WordPress 网站更加个性化和强大。

希望今天的讲座能够帮助你更好地理解 WordPress 的内核机制，并在实际开发中灵活运用 the_content() 函数和 the_content 过滤器，创造出更加出色的 WordPress 网站。

谢谢大家！

发表回复 取消回复

发表回复取消回复