阐述 WordPress `template_redirect` 钩子的源码实现：如何判断并加载正确的模板文件。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

好的，各位，欢迎来到今天的 WordPress 源码探秘讲座！今天咱们要聊的是一个非常关键的钩子：template_redirect。它就像一个交通警察，指挥着 WordPress 在茫茫模板文件中找到正确的道路，最终把用户带到他们想看的内容。准备好了吗？咱们系好安全带，一起深入源码，看看这位“警察叔叔”是怎么工作的。

一、template_redirect 的地位和作用

在 WordPress 的请求处理流程中，template_redirect 钩子扮演着至关重要的角色。简单来说，它发生在 WordPress 分析完请求，确定了要显示什么内容（例如，一篇文章、一个分类目录、一个搜索结果等）之后，但在真正加载模板文件之前。

你可以把它想象成一个“最后的机会”，让你有机会修改 WordPress 的决定，或者执行一些必要的准备工作。比如，你可以根据用户的角色重定向到不同的页面，或者根据一些自定义的条件加载不同的模板。

二、源码寻踪：template_redirect 的调用

template_redirect 钩子是在 wp-includes/template-loader.php 文件中调用的。这个文件是 WordPress 模板加载的核心。让我们来看看相关的代码片段：

<?php
// wp-includes/template-loader.php

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Determine the correct template to load.
 *
 * Used for all requests, except for feeds and AJAX.
 *
 * @since 1.5.0
 */
function template_loader() {
    if ( defined( 'DOING_AJAX' ) ) {
        return;
    }

    /**
     * Fires before determining which template to load.
     *
     * @since 2.0.0
     */
    do_action( 'template_redirect' );

    $template = false;

    // ... (省略大量模板判断代码) ...

    if ( $template ) {
        /**
         * Fires immediately before a template is loaded.
         *
         * @since 4.5.0
         *
         * @param string $template The path to the template about to be included.
         */
        do_action( 'template_include', $template );

        include $template;
    } else {
        /**
         * Fires if a theme is missing the index.php template file.
         *
         * @since 3.0.0
         */
        do_action( 'template_redirect_404' );

        status_header( 404 );
        nocache_headers();
        include( get_query_template( '404' ) );
    }
}

template_loader();

从上面的代码中，我们可以看到：

首先，template_loader() 函数会检查是否正在执行 AJAX 请求。如果是，则直接返回，因为 AJAX 请求通常不需要加载模板。
然后，do_action( 'template_redirect' ) 这一行代码就是我们今天的主角。它会触发所有挂载到 template_redirect 钩子上的函数。
接下来，template_loader() 函数会进行一系列复杂的判断，试图找到最合适的模板文件。
如果找到了模板文件，它会触发 template_include 钩子，然后使用 include 语句加载模板。
如果没有找到模板文件，它会触发 template_redirect_404 钩子，设置 HTTP 状态码为 404，并加载 404 模板。

三、模板判断的逻辑：源码中的“侦探”

template_loader() 函数中模板判断的逻辑非常复杂，它会根据不同的请求类型（例如，首页、文章页、分类页、搜索结果页等）使用不同的函数来查找模板文件。这些函数包括：

get_home_template()：查找首页模板。
get_single_template()：查找文章页模板。
get_page_template()：查找页面模板。
get_category_template()：查找分类页模板。
get_tag_template()：查找标签页模板。
get_search_template()：查找搜索结果页模板。
get_archive_template()：查找归档页模板。
get_404_template()：查找 404 模板。

这些函数会按照一定的优先级顺序查找模板文件。例如，对于文章页，get_single_template() 函数会首先查找名为 single-{post_type}-{slug}.php 的模板文件，然后查找 single-{post_type}.php，最后查找 single.php。如果以上文件都不存在，它会返回 index.php 作为默认模板。

四、 template_redirect 钩子的妙用：自定义模板加载

template_redirect 钩子最强大的地方在于，你可以使用它来完全控制模板加载的流程。你可以根据自己的需求，修改 WordPress 的默认行为，加载自定义的模板文件。

下面是一些使用 template_redirect 钩子的常见场景：

根据用户角色加载不同的模板： 你可以检查用户的角色，然后加载不同的模板，以便为不同的用户提供不同的内容和体验。

<?php
function my_custom_template_redirect() {
    if ( is_user_logged_in() ) {
        $user = wp_get_current_user();
        if ( in_array( 'administrator', (array) $user->roles ) ) {
            // 管理员
            if ( is_page( 'my-page' ) ) {
                $template = locate_template( 'page-admin.php' );
                if ( $template ) {
                    include( $template );
                    exit;
                }
            }
        } else {
            // 普通用户
            if ( is_page( 'my-page' ) ) {
                $template = locate_template( 'page-user.php' );
                if ( $template ) {
                    include( $template );
                    exit;
                }
            }
        }
    } else {
        // 未登录用户
        if ( is_page( 'my-page' ) ) {
            $template = locate_template( 'page-guest.php' );
            if ( $template ) {
                include( $template );
                exit;
            }
        }
    }
}
add_action( 'template_redirect', 'my_custom_template_redirect' );

这段代码会根据用户的角色，加载不同的页面模板。如果用户是管理员，它会加载 page-admin.php 模板；如果用户是普通用户，它会加载 page-user.php 模板；如果用户未登录，它会加载 page-guest.php 模板。

根据自定义字段加载不同的模板： 你可以使用自定义字段来控制模板的加载。例如，你可以添加一个名为 "template" 的自定义字段，然后在 template_redirect 钩子中检查该字段的值，并加载相应的模板。

<?php
function my_custom_template_redirect() {
    global $post;

    if ( is_single() ) {
        $template_name = get_post_meta( $post->ID, 'template', true );

        if ( ! empty( $template_name ) ) {
            $template = locate_template( $template_name . '.php' );
            if ( $template ) {
                include( $template );
                exit;
            }
        }
    }
}
add_action( 'template_redirect', 'my_custom_template_redirect' );

这段代码会在文章页中检查名为 "template" 的自定义字段的值。如果该字段的值不为空，它会加载名为 $template_name.php 的模板文件。

根据 URL 参数加载不同的模板： 你可以使用 URL 参数来控制模板的加载。例如，你可以添加一个名为 "template" 的 URL 参数，然后在 template_redirect 钩子中检查该参数的值，并加载相应的模板。
```
<?php
function my_custom_template_redirect() {
    if ( isset( $_GET['template'] ) ) {
        $template_name = sanitize_text_field( $_GET['template'] );
        $template = locate_template( $template_name . '.php' );
        if ( $template ) {
            include( $template );
            exit;
        }
    }
}
add_action( 'template_redirect', 'my_custom_template_redirect' );
```
这段代码会检查 URL 中是否有名为 "template" 的参数。如果存在，它会加载名为 $template_name.php 的模板文件。注意，在使用 URL 参数时，一定要进行安全过滤，以防止恶意代码注入。 sanitize_text_field() 函数可以帮助你过滤 URL 参数中的文本内容。

五、 locate_template() 函数：模板文件定位器

在上面的代码示例中，我们都使用了 locate_template() 函数。这个函数的作用是在主题目录中查找指定的模板文件。它的原型如下：

<?php
/**
 * Retrieve the name of the highest priority template file that exists.
 *
 * Searches in the STYLESHEETPATH before TEMPLATEPATH so that themes which
 * inherit from a parent theme can just define new templates and not worry
 * about duplicating the parent theme's templates.
 *
 * @since 2.7.0
 *
 * @param string|string[] $template_names Template file(s) to search for, in order.
 * @param bool            $load          If true the template file will be loaded if it is found.
 * @param bool            $require_once  Whether to require_once or require. Has no effect if $load is false.
 *                                       Default true.
 * @return string The template filename if one is located.
 */
function locate_template( $template_names, $load = false, $require_once = true ) {
    $located = '';
    foreach ( (array) $template_names as $template_name ) {
        if ( ! $template_name ) {
            continue;
        }

        if ( file_exists( STYLESHEETPATH . '/' . $template_name ) ) {
            $located = STYLESHEETPATH . '/' . $template_name;
            break;
        } elseif ( file_exists( TEMPLATEPATH . '/' . $template_name ) ) {
            $located = TEMPLATEPATH . '/' . $template_name;
            break;
        }
    }

    if ( $load && '' != $located ) {
        load_template( $located, $require_once );
    }

    return $located;
}

locate_template() 函数会按照以下顺序查找模板文件：

当前主题的 Stylesheet 目录（通常是子主题的目录）。
当前主题的 Template 目录（通常是父主题的目录）。

如果找到了模板文件，它会返回该文件的完整路径。如果 load 参数为 true，它还会使用 load_template() 函数加载该模板文件。

六、 load_template() 函数：加载模板文件

load_template() 函数的作用是加载指定的模板文件。它的原型如下：

<?php
/**
 * Requires the theme template file with WordPress environment.
 *
 * The WordPress environment is available within the file.
 *
 * @since 3.0.0
 *
 * @param string $template_path The path to the template file.
 * @param bool   $require_once Whether to require_once or require. Default true.
 * @param array  $args Optional. Additional variables passed to the template.
 * @return void
 */
function load_template( $template_path, $require_once = true, array $args = array() ) {
    global $posts, $post, $wp_did_template_redirect, $wp_query, $wp_rewrite, $wpdb, $wp_locale, $wp, $l10n, $doing_it_wrong, $base;

    /**
     * Fires before the specified template is loaded.
     *
     * @since 5.2.0
     *
     * @param string $template_path The path to the template file.
     * @param string $template_name The filename of the template.
     * @param array  $args          Additional variables passed to the template.
     */
    do_action( 'load_template', $template_path, basename( $template_path ), $args );

    if ( ! empty( $args ) ) {
        extract( $args );
    }

    if ( $require_once ) {
        require_once( $template_path );
    } else {
        require( $template_path );
    }
}

load_template() 函数会使用 require_once() 或 require() 语句加载模板文件。它还会将一些 WordPress 的全局变量传递给模板文件，以便在模板文件中使用。

七、最佳实践和注意事项

优先级： template_redirect 钩子的执行顺序很重要。如果你需要覆盖 WordPress 的默认行为，你应该使用一个较高的优先级，以确保你的函数在 WordPress 的函数之前执行。可以使用 add_action( 'template_redirect', 'my_custom_template_redirect', 0 ); 来设置优先级为 0，使其最先执行。
性能： 在 template_redirect 钩子中执行的代码会影响网站的性能。你应该尽量减少在该钩子中执行的代码量，并避免执行耗时的操作。
安全： 在使用 template_redirect 钩子时，一定要注意安全问题。你应该对用户输入进行验证和过滤，以防止恶意代码注入。
调试： 如果你的自定义模板加载逻辑出现问题，可以使用 wp_die() 函数来调试代码。例如，你可以使用 wp_die( 'Template not found' ); 来输出一条错误消息，并停止代码的执行。
避免无限循环： 确保你的 template_redirect 函数不会导致无限循环。例如，如果你在 template_redirect 函数中重定向到同一个页面，可能会导致无限循环。

八、总结

template_redirect 钩子是 WordPress 中一个非常强大和灵活的钩子。你可以使用它来完全控制模板加载的流程，并根据自己的需求加载自定义的模板文件。但是，在使用 template_redirect 钩子时，一定要注意性能和安全问题，并避免导致无限循环。

希望今天的讲座能够帮助你更好地理解 template_redirect 钩子的工作原理和使用方法。现在，轮到你们去探索和实践了！祝你们在 WordPress 的世界里玩得开心！谢谢大家！

发表回复 取消回复

发表回复取消回复