解析 WordPress `WP_Theme` 类的源码：如何从 `style.css` 文件中解析主题信息，并封装为对象属性。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷，大家好！今天咱们来聊聊 WordPress 主题背后的功臣——WP_Theme 类，尤其是它如何从 style.css 这个看起来平平无奇的文件中，榨取出主题的灵魂和精髓，并变成我们熟悉的、可以调用的对象属性。

开场白：style.css，主题的身份证

想象一下，style.css 就像一个人的身份证，上面记录着姓名、性别、住址等等信息。对于 WordPress 主题来说，style.css 记录着主题的名称、作者、版本、描述等等关键信息。WP_Theme 类就像一位尽职尽责的户籍警，专门负责读取并解析这张“身份证”，然后把信息整理成结构化的数据，方便我们使用。

WP_Theme 类的诞生：加载和初始化

WP_Theme 类是 WordPress 的核心类之一，位于 wp-includes/class-wp-theme.php 文件中。它的主要职责是管理和操作 WordPress 主题。当我们激活一个主题时，WordPress 会创建一个 WP_Theme 类的实例，代表当前激活的主题。

首先，让我们看看 WP_Theme 类的构造函数 __construct()，它负责加载主题的基本信息：

public function __construct( $theme_dir, $stylesheet_dir = null ) {
    if ( is_dir( $theme_dir ) ) {
        $this->theme_root = $theme_dir;

        if ( ! isset( $stylesheet_dir ) || ! is_dir( $stylesheet_dir ) ) {
            $stylesheet_dir = $theme_dir;
        }

        $this->stylesheet_dir = $stylesheet_dir;

        $this->stylesheet = trailingslashit( $this->stylesheet_dir ) . 'style.css';
        $this->template = $this->theme_root;

        $this->cache_hash = md5( $this->template . $this->stylesheet . get_theme_root_uri( $this->template, $this->stylesheet ) );
        $this->name = $this->display( 'Name', false, false );

        // ... 其它初始化操作 ...
    } else {
        $this->errors = new WP_Error( 'theme_not_found', __( 'The theme directory does not exist.' ) );
    }
}

这段代码首先检查主题目录是否存在。如果存在，它会设置主题的根目录 ($this->theme_root) 和样式表目录 ($this->stylesheet_dir)。然后，它会计算样式表的路径 ($this->stylesheet) 和模板的路径 ($this->template)。最后，它会生成一个缓存哈希值 ($this->cache_hash)，并尝试获取主题的名称 ($this->name)。

get_stylesheet() 和 get_template()：获取目录路径

这两个方法分别用于获取主题的样式表目录和模板目录：

public function get_stylesheet() {
    return $this->stylesheet;
}

public function get_template() {
    return $this->template;
}

很简单，就是返回构造函数中设置的 $this->stylesheet 和 $this->template 属性。

重头戏：get_file_data()，解析 style.css 的魔法棒

核心在于 get_file_data() 方法，它定义在 wp-includes/functions.php 文件中。虽然它不是 WP_Theme 类的方法，但 WP_Theme 类会调用它来读取 style.css 文件并解析其中的信息。

function get_file_data( $file, $default_headers, $context = '' ) {
    // We don't need to write to the file, so just use r for read.
    $fp = fopen( $file, 'r' );

    // Pull out the first 8kiB of the file.
    $file_data = fread( $fp, 8192 );

    // PHP will close file handle, but we are good citizens.
    fclose( $fp );

    // Make sure we catch CR-only line endings.
    $file_data = str_replace( "r", "n", $file_data );

    $all_headers = $default_headers;

    foreach ( $all_headers as $field => $regex ) {
        if ( preg_match( '/' . preg_quote( $regex, '/' ) . ':(.*)$/mi', $file_data, $match ) && ! empty( $match[1] ) ) {
            $all_headers[ $field ] = trim( _cleanup_header_comment( $match[1] ) );
        } else {
            $all_headers[ $field ] = '';
        }
    }

    return $all_headers;
}

这个函数接收三个参数：

$file: 要读取的文件路径，这里是 style.css 的路径。
$default_headers: 一个关联数组，定义了要读取的头部字段和对应的正则表达式。
$context: 上下文，可选参数，用于过滤结果。

这个函数的工作流程如下：

打开文件: 使用 fopen() 函数以只读模式打开 style.css 文件。
读取文件内容: 使用 fread() 函数读取文件的前 8KB 内容。为什么要读取 8KB 呢？因为主题信息通常位于文件的开头，8KB 足够覆盖大部分主题信息了。
关闭文件: 使用 fclose() 函数关闭文件。
处理换行符: 使用 str_replace() 函数将 r 替换为 n，确保跨平台兼容性。
循环解析头部字段: 遍历 $default_headers 数组，使用 preg_match() 函数和正则表达式从文件内容中提取对应的头部字段的值。
清理头部注释: 使用 _cleanup_header_comment() 函数清理头部注释，去除多余的空格和特殊字符。
返回结果: 返回一个关联数组，包含了所有头部字段的值。

$default_headers：定义要读取的头部字段

$default_headers 数组定义了要从 style.css 文件中读取的头部字段和对应的正则表达式。对于主题来说，$default_headers 通常包含以下字段：

字段名	描述	正则表达式
`Name`	主题名称	`Theme Name`
`ThemeURI`	主题 URI	`Theme URI`
`Description`	主题描述	`Description`
`Author`	作者	`Author`
`AuthorURI`	作者 URI	`Author URI`
`Version`	版本	`Version`
`Template`	父主题	`Template`
`Status`	状态	`Status`
`Tags`	标签	`Tags`
`TextDomain`	文本域名	`Text Domain`
`DomainPath`	域名路径	`Domain Path`

这些字段必须以注释的形式写在 style.css 文件的开头，例如：

/*
Theme Name:   My Awesome Theme
Theme URI:    https://example.com/my-awesome-theme/
Description:  A simple and clean theme for WordPress.
Author:       John Doe
Author URI:   https://example.com/
Version:      1.0.0
*/

display() 方法：获取主题信息

WP_Theme 类提供了 display() 方法来获取主题信息：

public function display( $header, $translate = true, $use_cache = true ) {
    $header = trim( $header );
    $file = $this->get_stylesheet();
    $file_data = $this->get_file_data();

    if ( ! isset( $file_data[ $header ] ) ) {
        return false;
    }

    $value = $file_data[ $header ];

    if ( $translate && ( 'Tags' !== $header ) && ! empty( $value ) ) {
        $value = translate( $value, 'theme' );
    }

    return $value;
}

这个方法接收三个参数：

$header: 要获取的头部字段名，例如 Name、Description 等。
$translate: 是否进行翻译，默认为 true。
$use_cache: 是否使用缓存，默认为 true。

这个方法的工作流程如下：

获取文件路径: 调用 get_stylesheet() 方法获取 style.css 文件的路径。
获取文件数据: 调用 get_file_data() 方法获取 style.css 文件的数据。这里会调用 _get_theme_headers() 方法来获取默认的头部字段。
检查字段是否存在: 检查 $file_data 数组中是否存在 $header 对应的键。如果不存在，则返回 false。
获取字段值: 从 $file_data 数组中获取 $header 对应的值。
进行翻译: 如果 $translate 为 true 且 $header 不是 Tags，则使用 translate() 函数进行翻译。
返回结果: 返回获取到的字段值。

get_file_data() 的缓存机制：提高性能

为了提高性能，WP_Theme 类使用了缓存机制来存储 style.css 文件的数据。get_file_data() 方法会检查缓存中是否已经存在对应的数据，如果存在，则直接从缓存中读取，否则才读取文件并解析数据。

protected function get_file_data() {
    if ( ! isset( $this->file_data ) ) {
        $this->file_data = get_file_data( $this->stylesheet, _get_theme_headers() );
    }
    return $this->file_data;
}

实际应用：获取主题名称和描述

有了 WP_Theme 类，我们可以很方便地获取主题的各种信息。例如，要获取主题的名称和描述，可以使用以下代码：

$theme = wp_get_theme(); // 获取当前主题的 WP_Theme 对象

$theme_name = $theme->get( 'Name' ); // 获取主题名称
$theme_description = $theme->get( 'Description' ); // 获取主题描述

echo 'Theme Name: ' . esc_html( $theme_name ) . '<br>';
echo 'Theme Description: ' . esc_html( $theme_description ) . '<br>';

wp_get_theme() 函数：获取 WP_Theme 对象

wp_get_theme() 函数用于获取一个 WP_Theme 对象。它可以接收一个参数，指定主题的目录名。如果不指定参数，则返回当前激活主题的 WP_Theme 对象。

function wp_get_theme( $stylesheet = null, $theme_root = null ) {
    if ( isset( $stylesheet ) ) {
        $theme = WP_Theme::get_instance( $stylesheet, $theme_root );
    } else {
        $theme = WP_Theme::get_instance();
    }

    return $theme;
}

总结：WP_Theme 类，主题信息的守护者

WP_Theme 类是 WordPress 主题管理的核心类之一。它通过解析 style.css 文件，将主题的各种信息封装成对象属性，方便我们使用。通过 get_file_data() 方法，我们可以读取 style.css 文件并解析其中的头部字段。通过 display() 方法，我们可以获取主题的各种信息。WP_Theme 类还使用了缓存机制来提高性能。

简单来说，WP_Theme 类就像一个主题信息的守护者，它负责从 style.css 文件中提取信息，并将其安全地存储起来，供我们随时调用。

彩蛋：_get_theme_headers() 函数

_get_theme_headers() 函数定义了默认的头部字段。这个函数返回一个关联数组，包含了所有默认的头部字段和对应的正则表达式。

function _get_theme_headers() {
    $headers = array(
        'Name'        => 'Theme Name',
        'ThemeURI'    => 'Theme URI',
        'Description' => 'Description',
        'Author'      => 'Author',
        'AuthorURI'   => 'Author URI',
        'Version'     => 'Version',
        'Template'    => 'Template',
        'Status'      => 'Status',
        'Tags'        => 'Tags',
        'TextDomain'  => 'Text Domain',
        'DomainPath'  => 'Domain Path',
    );

    return $headers;
}

结束语：掌握 WP_Theme 类，玩转 WordPress 主题

掌握 WP_Theme 类的原理和使用方法，可以帮助我们更好地理解 WordPress 主题的工作机制，从而更好地开发和定制 WordPress 主题。希望今天的讲座对大家有所帮助！下次再见！

发表回复 取消回复

发表回复取消回复