解析 WordPress `get_edit_term_link()` 函数的源码：如何生成分类术语编辑页的链接。

各位同学，欢迎来到今天的“WordPress源码探秘”小课堂！今天我们要一起解剖一个非常实用的函数：get_edit_term_link()。它就像WordPress后台的一位老司机，专门负责带我们去编辑分类、标签等术语的页面。

准备好了吗？让我们系好安全带，开始一段刺激的源码之旅吧！

一、get_edit_term_link() 函数的概览

首先，让我们大致了解一下 get_edit_term_link() 函数的作用和基本用法。

• 作用: 生成编辑指定分类术语的链接。
• 位置: wp-includes/link-template.php 文件中。
• 基本用法:

$term_id = 5; // 假设我们要编辑的分类 ID 是 5
$taxonomy = 'category'; // 假设我们要编辑的是分类
$edit_link = get_edit_term_link( $term_id, $taxonomy );

echo '<a href="' . esc_url( $edit_link ) . '">编辑此分类</a>';

这段代码会生成一个链接，点击后会跳转到 ID 为 5 的分类的编辑页面。

二、源码解剖：一步一步来

现在，让我们深入 get_edit_term_link() 函数的源码，看看它是如何工作的。

function get_edit_term_link( $term, $taxonomy = '', $object_type = '' ) {
    global $wp_rewrite;

    $term = get_term( $term, $taxonomy, $object_type );

    if ( is_wp_error( $term ) ) {
        return $term;
    }

    if ( ! current_user_can( 'edit_term', $term->term_id ) ) {
        return '';
    }

    $taxonomy = $term->taxonomy;

    $args = array(
        'taxonomy' => $taxonomy,
        'tag_ID'   => $term->term_id,
        'post_type' => ( isset( $_GET['post_type'] ) ) ? $_GET['post_type'] : '',
    );

    $url = add_query_arg( $args, admin_url( 'term.php' ) );

    /**
     * Filters the edit term link.
     *
     * @since 3.1.0
     *
     * @param string  $url      The edit term link.
     * @param WP_Term $term     Term object.
     * @param string  $taxonomy Taxonomy name.
     */
    return apply_filters( 'get_edit_term_link', $url, $term, $taxonomy );
}

让我们一行一行地解读这段代码：

1. 函数定义: function get_edit_term_link( $term, $taxonomy = '', $object_type = '' )

   • 定义了函数 get_edit_term_link()，它接受三个参数：
     • $term: 术语 ID 或术语对象。
     • $taxonomy: 分类法（taxonomy）的名称，例如 ‘category’, ‘post_tag’。
     • $object_type: 对象类型，通常可以省略。

2. 获取术语对象: $term = get_term( $term, $taxonomy, $object_type );

   • 使用 get_term() 函数获取术语对象。如果传入的是术语 ID，get_term() 会根据 ID 和分类法获取对应的术语对象。
   • get_term() 函数是 WordPress 提供的一个核心函数，用于从数据库中检索术语信息。

3. 错误处理: if ( is_wp_error( $term ) ) { return $term; }

   • 检查 get_term() 函数是否返回了错误。如果返回了 WP_Error 对象，则直接返回该错误对象。

4. 权限检查: if ( ! current_user_can( 'edit_term', $term->term_id ) ) { return ''; }

   • 使用 current_user_can() 函数检查当前用户是否有编辑该术语的权限。 edit_term 是一个 capability，需要用户拥有相应的权限才能编辑。如果用户没有权限，则返回空字符串。 这部分代码非常重要，确保了安全性。不是谁都能随便编辑分类的！

5. 确定分类法: $taxonomy = $term->taxonomy;

   • 从术语对象中获取分类法名称。 即使在函数调用时传入了 taxonomy，这里也会覆盖掉，使用术语对象中实际的 taxonomy，确保准确性。

6. 构建 URL 参数:

   $args = array(
       'taxonomy' => $taxonomy,
       'tag_ID'   => $term->term_id,
       'post_type' => ( isset( $_GET['post_type'] ) ) ? $_GET['post_type'] : '',
   );

   • 创建一个包含 URL 参数的数组。
     • taxonomy: 分类法名称。
     • tag_ID: 术语 ID。 注意这里使用了 tag_ID，虽然看起来像标签 ID，但实际上也用于分类和其他类型的术语。
     • post_type: 文章类型。 如果 URL 中有 post_type 参数，则将其添加到 URL 中。 这通常在编辑文章时，如果文章关联了某个分类，编辑分类的链接会带上 post_type 参数，以便在编辑完分类后能够返回到原来的文章编辑页面。

7. 构建 URL: $url = add_query_arg( $args, admin_url( 'term.php' ) );

   • 使用 add_query_arg() 函数将 URL 参数添加到 WordPress 后台的 term.php 页面的 URL 中。
   • admin_url( 'term.php' ) 获取 term.php 文件的 URL，这是 WordPress 后台管理术语的页面。
   • add_query_arg() 函数的作用是将 $args 数组中的参数添加到 URL 中。

8. 应用过滤器: return apply_filters( 'get_edit_term_link', $url, $term, $taxonomy );

   • 使用 apply_filters() 函数应用 get_edit_term_link 过滤器。
   • 这个过滤器允许开发者修改最终生成的编辑链接。
   • apply_filters() 函数接收三个参数：
     • 'get_edit_term_link': 过滤器的名称。
     • $url: 要过滤的值（即生成的 URL）。
     • $term: 术语对象。
     • $taxonomy: 分类法名称。

三、重点函数解析

在 get_edit_term_link() 函数中，有几个关键的辅助函数，理解它们对于理解整个函数至关重要。

1. get_term()

   • 作用: 根据术语 ID 或术语对象以及分类法名称，获取术语对象。
   • 源码位置: wp-includes/taxonomy.php
   • 示例:

   $term_id = 5;
   $taxonomy = 'category';
   $term = get_term( $term_id, $taxonomy );
   
   if ( ! is_wp_error( $term ) && $term ) {
       echo '术语名称: ' . $term->name;
       echo '术语别名: ' . $term->slug;
   } else {
       echo '未找到术语';
   }

   • 功能拆解：get_term() 函数内部会进行缓存查询，如果术语信息已经被缓存，则直接从缓存中获取，否则会查询数据库。

2. current_user_can()

   • 作用: 检查当前用户是否具有指定的权限。
   • 源码位置: wp-includes/capabilities.php
   • 示例:

   if ( current_user_can( 'edit_posts' ) ) {
       echo '当前用户可以编辑文章';
   } else {
       echo '当前用户没有编辑文章的权限';
   }

   • 权限控制：current_user_can() 函数是 WordPress 权限控制的核心，它允许你根据用户的角色和权限来控制用户可以执行的操作。

3. add_query_arg()

   • 作用: 向 URL 添加查询参数。
   • 源码位置: wp-includes/functions.php
   • 示例:

   $url = 'https://example.com/page.php';
   $args = array(
       'param1' => 'value1',
       'param2' => 'value2',
   );
   $new_url = add_query_arg( $args, $url );
   
   echo $new_url; // 输出: https://example.com/page.php?param1=value1&param2=value2

   • URL构建利器：add_query_arg() 函数可以方便地向 URL 添加参数，避免手动拼接字符串的麻烦，而且还能处理 URL 中已经存在参数的情况。

4. admin_url()

   • 作用: 获取 WordPress 后台的 URL。
   • 源码位置: wp-includes/link-template.php
   • 示例:

   $admin_url = admin_url();
   echo $admin_url; // 输出: https://example.com/wp-admin/
   
   $edit_post_url = admin_url( 'post.php?post=10&action=edit' );
   echo $edit_post_url; // 输出: https://example.com/wp-admin/post.php?post=10&action=edit

   • 后台入口：admin_url() 函数可以方便地获取 WordPress 后台的 URL，以及后台特定页面的 URL。

5. apply_filters()

   • 作用： 执行过滤器，允许修改数据。
   • 源码位置： wp-includes/plugin.php
   • 示例：

     
     function modify_text( $text ) {
     return 'Modified: ' . $text;
     }
     add_filter( 'my_text_filter', 'modify_text' );

   $original_text = ‘Hello World’;
   $modified_text = apply_filters( ‘my_text_filter’, $original_text );

   echo $modified_text; // 输出: Modified: Hello World

   
   * **灵活扩展：** `apply_filters()` 是 WordPress 插件系统的重要组成部分，允许开发者通过过滤器来修改 WordPress 的核心功能和数据。

四、 实际应用场景

了解了 get_edit_term_link() 函数的原理，我们来看看它在实际开发中有哪些应用场景。

1. 自定义分类列表:

   假设你想要在前端显示一个分类列表，并且允许用户点击链接直接进入后台编辑某个分类。你可以这样实现：

   $terms = get_terms( array(
       'taxonomy' => 'category',
       'hide_empty' => false, // 显示空分类
   ) );
   
   if ( ! empty( $terms ) && ! is_wp_error( $terms ) ) {
       echo '<ul>';
       foreach ( $terms as $term ) {
           $edit_link = get_edit_term_link( $term->term_id, 'category' );
           echo '<li><a href="' . esc_url( $edit_link ) . '">' . $term->name . '</a></li>';
       }
       echo '</ul>';
   }

   这段代码会获取所有的分类，并为每个分类生成一个指向后台编辑页面的链接。

2. 在文章编辑页面添加分类编辑链接:

   有时，你可能需要在文章编辑页面直接提供一个链接，方便用户编辑文章所属的分类。 可以使用 admin_notice 钩子来实现：

   function add_edit_category_link() {
       global $post;
   
       if ( ! isset( $post->ID ) ) {
           return;
       }
   
       $categories = get_the_category( $post->ID );
   
       if ( ! empty( $categories ) ) {
           $category = $categories[0]; // 取第一个分类
           $edit_link = get_edit_term_link( $category->term_id, 'category' );
           if($edit_link){
           echo '<div class="notice notice-info"><p>编辑分类：<a href="' . esc_url( $edit_link ) . '">' . $category->name . '</a></p></div>';
           }
       }
   }
   add_action( 'admin_notices', 'add_edit_category_link' );

   这段代码会在文章编辑页面显示一个通知，如果文章有分类，通知中会包含一个指向该分类编辑页面的链接。

3. 自定义术语编辑链接：

通过 get_edit_term_link 过滤器，你可以完全自定义术语编辑链接的生成方式。 假设你想给所有分类的编辑链接添加一个自定义参数 custom_param=true，可以这样做：

function custom_edit_term_link( $url, $term, $taxonomy ) {
    if ( $taxonomy === 'category' ) {
        $url = add_query_arg( 'custom_param', 'true', $url );
    }
    return $url;
}
add_filter( 'get_edit_term_link', 'custom_edit_term_link', 10, 3 );

这段代码会修改所有分类的编辑链接，添加 custom_param=true 参数。

五、 总结

get_edit_term_link() 函数虽然看起来简单，但它却是 WordPress 后台管理的重要组成部分。 它负责生成编辑分类、标签等术语的链接，保证了用户能够方便地管理网站的内容。通过深入理解它的源码，我们可以更好地掌握 WordPress 的内部机制，并能够更加灵活地进行自定义开发。

以下是一个表格，总结了get_edit_term_link()函数涉及的一些重要知识点：

知识点	描述
函数作用	生成编辑分类术语的链接。
关键函数	get_term(), current_user_can(), add_query_arg(), admin_url(), apply_filters()
权限控制	使用 current_user_can() 检查用户是否具有编辑术语的权限。
URL 构建	使用 add_query_arg() 将参数添加到 term.php 页面的 URL 中。
过滤器	get_edit_term_link 过滤器允许开发者修改最终生成的编辑链接。
应用场景	自定义分类列表，文章编辑页面添加分类编辑链接，自定义术语编辑链接等。
源码位置	wp-includes/link-template.php
重要参数	$term (术语 ID 或术语对象), $taxonomy (分类法名称)

希望今天的课程对你有所帮助！ 下次再见！