云策 WordPress 开发者社区

函数文档

add_permastruct()

查看官方原文 ↗
💡 云策文档标注

概述

add_permastruct() 函数用于向 WordPress 添加自定义的固定链接结构，通常与 WP_Rewrite 类配合使用。它允许开发者定义新的 URL 规则，以支持自定义内容类型的重写。

关键要点

  • 函数接受三个参数：$name（结构名称）、$struct（固定链接结构字符串）和 $args（可选参数数组）。
  • 内部调用 WP_Rewrite::add_permastruct() 方法，实现重写规则的添加。
  • 支持向后兼容，允许旧参数 $with_front 和 $ep_mask 的传递方式。
  • 常用于自定义文章类型或分类法的重写规则设置，如 WP_Taxonomy::add_rewrite_rules() 和 WP_Post_Type::add_rewrite_rules()。
  • 自 WordPress 3.0.0 版本引入。

代码示例

// 示例：添加自定义固定链接结构
add_action('init', 'wpdocs_custom_permalink');
function wpdocs_custom_permalink() {
    add_permastruct('legal', 'legal/%my_slug%', ['ep_mask' => EP_PERMALINK]);
    add_rewrite_tag('%my_slug%', '([^/]+)', "post_type=page&name=");
    // 仅在结构变化时刷新重写规则
    if ($has_changed) {
        flush_rewrite_rules();
    }
}

注意事项

  • add_permastruct() 需要在每次请求时调用（如通过 'init' 钩子），以确保重写规则生效。
  • flush_rewrite_rules() 应仅在固定链接结构发生变化时调用（如插件激活时），以避免性能问题。
  • 参数 $args 可包含 'with_front'、'ep_mask' 等选项，用于控制重写行为。
📄 原文内容

Adds a permalink structure.

Description

See also

Parameters

$namestringrequired
Name for permalink structure.
$structstringrequired
Permalink structure.
$argsarrayoptional
Arguments for building the rules from the permalink structure, see WP_Rewrite::add_permastruct() for full details.

Default:array()

Source

function add_permastruct( $name, $struct, $args = array() ) {
	global $wp_rewrite;

	// Back-compat for the old parameters: $with_front and $ep_mask.
	if ( ! is_array( $args ) ) {
		$args = array( 'with_front' => $args );
	}

	if ( func_num_args() === 4 ) {
		$args['ep_mask'] = func_get_arg( 3 );
	}

	$wp_rewrite->add_permastruct( $name, $struct, $args );
}

View all references View on Trac View on GitHub

Uses Description
WP_Rewrite::add_permastruct()wp-includes/class-wp-rewrite.php

Adds a new permalink structure.
Used by Description
WP_Taxonomy::add_rewrite_rules()wp-includes/class-wp-taxonomy.php

Adds the necessary rewrite rules for the taxonomy.
WP_Post_Type::add_rewrite_rules()wp-includes/class-wp-post-type.php

Adds the necessary rewrite rules for the post type.

Changelog

Version Description
3.0.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    Marcio Zebedeu


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    You can change rules to rewrite your type of posting as well as change your structure. Imagine that your permalink structure is like:
    /locations/%k7_locations%

    you can switch to

    /test/%message%

    global $wp_rewrite;
$args = array(
    'with_front' => true,
    'ep_mask' => 3,
    'paged' => 1,
    'feed' => 1,
    'forcomments' => 0,
    'walk_dirs' => 1,
    'endpoints' => 1
);
add_permastruct( 'locations', 'test/%message/', $args);

    output:

    Array
(
    [with_front] => 1
    [ep_mask] => 3
    [paged] => 1
    [feed] => 1
    [forcomments] => 0
    [walk_dirs] => 1
    [endpoints] => 1
    [struct] => /test/%message/%
)

  2. Skip to note 4 content


    Philipp Stracker


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    To add a custom URL-/permalink-structure, this function must be called on every request (not only once). I usually do this in the ‘init’ hook.

    However, the related function flush_rewrite_rules() should only be called when the permalink structure changes.

    Sample:

    add_action( 'init', 'wpdocs_custom_permalink' );
function wpdocs_custom_permalinks() {
  // Register the permastruct and rewrite tag on every page load:
  add_permastruct( 'legal', 'legal/%my_slug%', [ 'ep_mask' => EP_PERMALINK ] );
  add_rewrite_tag( '%my_slug%', '([^/]+)', "post_type=page&name;=" );

  // Only flush rewrite rules, if your permalink changed (e.g. on plugin activation):
  if ( $has_changed ) {
    flush_rewrite_rules();
  }
}