发布于 由admin

深入理解 WordPress `register_post_type()` 函数的源码：如何注册自定义文章类型。

各位朋友，大家好！欢迎来到今天的“WordPress深度剖析”讲座，我是你们的老朋友，代码界的段子手，今天咱们要聊的主题是：WordPress register_post_type() 函数的源码分析，以及如何注册自定义文章类型。

准备好了吗？咱们这就开讲，保证让你听完之后，感觉自己也能操刀改WordPress内核了！（当然，我只是说说，改内核需谨慎啊！）

一、 为什么要研究 register_post_type()？

想象一下，你想要在WordPress上创建一个“电影”栏目，或者一个“美食菜谱”栏目，甚至是一个“外星人观察报告”栏目（如果你相信的话）。这时候，普通的文章和页面可能就满足不了你的需求了。你需要一个自定义文章类型！

register_post_type() 函数就是用来注册这些自定义文章类型的核心武器。掌握它，你就掌握了在WordPress中构建复杂内容结构的关键技能。

二、 register_post_type() 的基本用法

在深入源码之前，咱们先回顾一下 register_post_type() 的基本用法，这样才能更好地理解源码背后的逻辑。

<?php
add_action( 'init', 'create_movie_post_type' );

function create_movie_post_type() {
  register_post_type( 'movie',
    array(
      'labels' => array(
        'name' => __( 'Movies' ),
        'singular_name' => __( 'Movie' )
      ),
      'public' => true,
      'has_archive' => true,
      'rewrite' => array( 'slug' => 'movies' ),
      'supports' => array( 'title', 'editor', 'thumbnail', 'excerpt', 'custom-fields', 'comments' ),
    )
  );
}
?>

这段代码做了什么？

  1. add_action( 'init', 'create_movie_post_type' );：在 init 钩子上挂载了一个函数 create_movie_post_type，确保在WordPress初始化完成后执行。
  2. register_post_type( 'movie', ... );：注册了一个名为 movie 的自定义文章类型。
  3. 'labels' => ...：定义了文章类型的各种标签，例如在后台显示的名称。
  4. 'public' => true：表示该文章类型是公开的，可以在前端显示。
  5. 'has_archive' => true：表示该文章类型拥有一个归档页面，用于显示所有该类型的文章。
  6. 'rewrite' => array( 'slug' => 'movies' )：定义了文章类型的URL别名，例如 yourdomain.com/movies/movie-title。
  7. 'supports' => ...：定义了文章类型支持的功能，例如标题、编辑器、特色图像等。

三、 register_post_type() 源码剖析

现在，咱们要深入到WordPress的源码中，看看 register_post_type() 到底做了什么。

register_post_type() 函数位于 wp-includes/post.php 文件中（具体行数可能会因WordPress版本而异，但文件位置基本不变）。

咱们简化一下，只关注核心逻辑：

function register_post_type( $post_type, $args = array() ) {
  global $wp_post_types;

  // 1. 参数校验和规范化
  if ( ! is_string( $post_type ) || empty( $post_type ) ) {
    return new WP_Error( 'invalid_post_type', __( 'Invalid post type' ) );
  }

  if ( strlen( $post_type ) > 20 ) {
    return new WP_Error( 'post_type_length_invalid', __( 'Post type names must be 20 characters or less in length.' ) );
  }

  // 2. 默认参数
  $args = wp_parse_args( $args, array(
    'labels' => array(),
    'description' => '',
    'public' => false,
    'exclude_from_search' => false,
    'publicly_queryable' => null,
    'show_ui' => null,
    'show_in_menu' => null,
    'show_in_nav_menus' => null,
    'show_in_admin_bar' => null,
    'menu_position' => null,
    'menu_icon' => null,
    'capability_type' => 'post',
    'capabilities' => array(),
    'map_meta_cap' => false,
    'hierarchical' => false,
    'supports' => array(),
    'register_meta_box_cb' => '',
    'taxonomies' => array(),
    'has_archive' => false,
    'rewrite' => true,
    'query_var' => true,
    'can_export' => true,
    'delete_with_user' => null,
    '_builtin' => false,
    '_edit_link' => 'post.php?post=%d',
  ) );

  // 3. 创建 WP_Post_Type 对象
  $post_type_object = new WP_Post_Type( $post_type, $args );

  // 4. 注册文章类型
  $wp_post_types[ $post_type ] = $post_type_object;

  // 5. 处理分类法关联
  foreach ( (array) $post_type_object->taxonomies as $taxonomy ) {
    register_taxonomy_for_object_type( $taxonomy, $post_type );
  }

  // 6. 执行 action
  do_action( 'registered_post_type', $post_type, $post_type_object );

  return $post_type_object;
}

咱们逐行分析一下：

  1. 参数校验和规范化：

    • 首先，它会检查你提供的 $post_type 是否有效，必须是字符串，并且不能为空。
    • 其次，它会检查 $post_type 的长度，不能超过20个字符。这是因为WordPress的数据库表结构对文章类型名称的长度有限制。
    if ( ! is_string( $post_type ) || empty( $post_type ) ) {
  return new WP_Error( 'invalid_post_type', __( 'Invalid post type' ) );
}

if ( strlen( $post_type ) > 20 ) {
  return new WP_Error( 'post_type_length_invalid', __( 'Post type names must be 20 characters or less in length.' ) );
}

    如果校验失败，它会返回一个 WP_Error 对象，告诉你哪里出错了。

  2. 默认参数：

    • wp_parse_args() 函数会将你提供的 $args 数组与默认参数数组合并。这意味着，如果你没有提供某个参数，它会使用默认值。
    $args = wp_parse_args( $args, array(
  'labels' => array(),
  'description' => '',
  'public' => false,
  // ... 其他参数
) );

    这里列出了一些常见的参数及其默认值。注意，'public' => false 意味着默认情况下，你的自定义文章类型是非公开的。

  3. 创建 WP_Post_Type 对象：

    • WP_Post_Type 是一个类，用于表示一个文章类型。它包含了文章类型的所有信息，例如名称、标签、支持的功能等。
    $post_type_object = new WP_Post_Type( $post_type, $args );

    这个对象会被存储起来，供WordPress后续使用。

  4. 注册文章类型：

    • $wp_post_types 是一个全局数组，用于存储所有已注册的文章类型。
    global $wp_post_types;
$wp_post_types[ $post_type ] = $post_type_object;

    这行代码将你创建的 WP_Post_Type 对象存储到 $wp_post_types 数组中，完成了文章类型的注册。

  5. 处理分类法关联：

    • 如果你的文章类型关联了某些分类法（例如分类目录、标签或自定义分类法），这段代码会将这些分类法与文章类型关联起来。
    foreach ( (array) $post_type_object->taxonomies as $taxonomy ) {
  register_taxonomy_for_object_type( $taxonomy, $post_type );
}

    register_taxonomy_for_object_type() 函数会将分类法与文章类型关联起来，这样你就可以在文章类型中使用这些分类法了。

  6. 执行 action：

    • do_action( 'registered_post_type', $post_type, $post_type_object );：这是一个钩子，允许其他插件或主题在文章类型注册完成后执行一些操作。
    do_action( 'registered_post_type', $post_type, $post_type_object );

    例如，你可以使用这个钩子来添加自定义的后台界面元素。

四、 WP_Post_Type 类解析

刚才咱们提到了 WP_Post_Type 类，它是表示文章类型的核心。咱们来看看这个类里有哪些重要的属性和方法。

WP_Post_Type 类的定义也在 wp-includes/post.php 文件中。

简化后的类结构如下：

class WP_Post_Type {
  public $name;
  public $label;
  public $labels;
  public $description;
  public $public;
  public $exclude_from_search;
  public $publicly_queryable;
  public $show_ui;
  public $show_in_menu;
  public $show_in_nav_menus;
  public $show_in_admin_bar;
  public $menu_position;
  public $menu_icon;
  public $capability_type;
  public $capabilities;
  public $map_meta_cap;
  public $hierarchical;
  public $supports;
  public $register_meta_box_cb;
  public $taxonomies;
  public $has_archive;
  public $rewrite;
  public $query_var;
  public $can_export;
  public $delete_with_user;
  public $_builtin;
  public $_edit_link;

  public function __construct( $post_type, $args = array() ) {
    $this->name = $post_type;

    foreach ( get_object_vars( $this ) as $key => $value ) {
      if ( isset( $args[ $key ] ) ) {
        $this->$key = $args[ $key ];
      }
    }

    $this->add_supports();
    $this->set_capabilities( $args );
    $this->set_labels();
  }

  private function add_supports() {
    // ... 处理 supports 属性
  }

  private function set_capabilities( $args ) {
    // ... 处理 capabilities 属性
  }

  private function set_labels() {
    // ... 处理 labels 属性
  }

  public function get_rewrite_slug() {
    // ... 获取 rewrite slug
  }
}

这个类包含了大量的属性，用于描述文章类型的各个方面。咱们挑几个重要的说一下：

  • $name：文章类型的名称，例如 'movie'。
  • $labels：一个数组，包含了文章类型的各种标签，例如 'name'、'singular_name'、'add_new' 等。
  • $public：一个布尔值，表示文章类型是否公开。
  • $supports：一个数组，包含了文章类型支持的功能，例如 'title'、'editor'、'thumbnail' 等。
  • $rewrite：一个数组或布尔值，用于控制文章类型的URL重写规则。
  • $capabilities：一个数组，包含了文章类型所需的各种权限。

WP_Post_Type 类的构造函数会将你提供的 $args 数组中的值赋值给对应的属性。它还会调用一些私有方法来处理 $supports、$capabilities 和 $labels 属性。

五、 常用参数详解

理解了源码之后，咱们再来详细了解一下 register_post_type() 函数中一些常用的参数，以便更好地控制自定义文章类型的行为。

参数 类型 描述 默认值
labels array 定义文章类型的各种标签，例如在后台显示的名称。这是一个非常重要的参数，因为它影响了用户在后台与文章类型的交互。 空数组
description string 文章类型的描述，用于在后台显示。 空字符串
public boolean 表示文章类型是否公开，可以在前端显示。如果设置为 true，则文章类型可以在前端被访问。 false
has_archive boolean 表示文章类型是否拥有一个归档页面，用于显示所有该类型的文章。如果设置为 true，WordPress会自动创建一个归档页面，用于显示所有该类型的文章。 false
rewrite array 定义文章类型的URL重写规则。可以设置为一个数组，包含 'slug'、'with_front'、'feeds'、'pages' 等键。 'slug' 用于定义文章类型的URL别名， 'with_front' 用于控制是否在URL中包含前缀， 'feeds' 用于控制是否启用Feed， 'pages' 用于控制是否支持分页。 true
supports array 定义文章类型支持的功能，例如标题、编辑器、特色图像等。常用的值包括 'title'、'editor'、'thumbnail'、'excerpt'、'custom-fields'、'comments'、'revisions'、'author'、'trackbacks'、'post-formats'。 空数组
taxonomies array 定义文章类型关联的分类法。可以设置为一个数组，包含分类目录、标签或自定义分类法。 空数组
menu_icon string 定义文章类型在后台菜单中显示的图标。可以使用Dashicons，也可以使用自定义的URL。 null
capabilities array 定义文章类型所需的各种权限。可以自定义权限，也可以使用WordPress内置的权限。 空数组

六、 高级技巧：自定义权限

WordPress的权限系统非常强大，你可以为自定义文章类型定义自定义的权限，以便更精细地控制用户的访问权限。

例如，你可以创建一个 edit_movie 权限，只允许特定用户编辑“电影”类型的文章。

<?php
add_action( 'init', 'create_movie_post_type' );

function create_movie_post_type() {
  $capabilities = array(
    'edit_post' => 'edit_movie',
    'read_post' => 'read_movie',
    'delete_post' => 'delete_movie',
    'edit_posts' => 'edit_movies',
    'edit_others_posts' => 'edit_others_movies',
    'read_private_posts' => 'read_private_movies',
    'publish_posts' => 'publish_movies',
    'delete_posts' => 'delete_movies',
    'delete_others_posts' => 'delete_others_movies',
  );

  register_post_type( 'movie',
    array(
      'labels' => array(
        'name' => __( 'Movies' ),
        'singular_name' => __( 'Movie' )
      ),
      'public' => true,
      'has_archive' => true,
      'rewrite' => array( 'slug' => 'movies' ),
      'supports' => array( 'title', 'editor', 'thumbnail', 'excerpt', 'custom-fields', 'comments' ),
      'capabilities' => $capabilities,
      'map_meta_cap' => true, // 必须设置为 true 才能使用自定义权限
    )
  );
}

// 赋予用户权限的示例 (在插件激活时执行)
function my_plugin_activate() {
  $role = get_role( 'administrator' ); // 获取管理员角色
  $role->add_cap( 'edit_movie' ); // 赋予管理员编辑 movie 的权限
}
register_activation_hook( __FILE__, 'my_plugin_activate' );

?>

这段代码做了什么？

  1. 定义了一个 $capabilities 数组，包含了自定义的权限名称。
  2. 在 register_post_type() 函数中，将 $capabilities 数组赋值给 'capabilities' 参数。
  3. 将 'map_meta_cap' 参数设置为 true，这是使用自定义权限的关键。
  4. 在插件激活时，获取管理员角色，并赋予 edit_movie 权限。

七、 避坑指南

在使用 register_post_type() 函数时，有一些常见的坑需要注意：

  1. 文章类型名称冲突：确保你的文章类型名称是唯一的，不要与其他插件或主题使用的文章类型名称冲突。
  2. 刷新固定链接：在注册或修改自定义文章类型后，务必刷新固定链接，否则可能会出现404错误。
  3. 'map_meta_cap' => true：如果要使用自定义权限，必须将 'map_meta_cap' 参数设置为 true。
  4. 'public' => true 和 'publicly_queryable' => true 的区别: 'public' => true 表示该文章类型是公开的，但需要 'publicly_queryable' => true 才能让用户通过 URL 查询到该文章类型的内容。
  5. 加载顺序问题：确保在需要使用自定义文章类型之前，已经注册了该文章类型。通常建议在 init 钩子上注册文章类型。

八、 总结

今天咱们深入剖析了 WordPress register_post_type() 函数的源码，了解了它的基本用法、核心逻辑和常用参数。咱们还学习了如何自定义权限，以及在使用 register_post_type() 函数时需要注意的坑。

希望今天的讲座能帮助你更好地理解和使用 register_post_type() 函数，构建更强大的 WordPress 站点。

记住，代码的世界充满了乐趣，只要你敢于探索，就能发现无限的可能！

感谢大家的收听，咱们下期再见！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注