云策 WordPress 开发者社区

函数文档

add_rewrite_endpoint()

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

概述

add_rewrite_endpoint() 函数用于在 WordPress 中创建自定义端点，类似于 /trackback/，通过位掩码指定端点应用的位置，并自动生成重写规则和查询变量。

关键要点

  • 函数添加端点，为指定位置（如 EP_PERMALINK | EP_PAGES）创建额外的重写规则，例如将 [permalink]/json/foo/ 重写为 json=foo。
  • 参数包括端点名称 $name（字符串）、位置掩码 $places（使用 EP_* 常量，如 EP_ALL 或组合）和可选的查询变量名 $query_var（默认为 $name，可传递 false 跳过注册）。
  • 使用后需调用 flush_rewrite_rules() 刷新重写规则，以确保更改生效，建议在插件激活和停用时执行。
  • 端点名称作为查询变量，值可以是端点后的文本（如 /foo/），可通过 template_redirect 钩子测试，适用于 AJAX 处理、表单提交等场景。
  • 注意：$places 参数必须使用 EP_* 常量（如 EP_PERMALINK），避免直接使用数值，因为其值可能变化；从 4.3.0 版本起支持 $query_var 为 false 跳过查询变量注册。

代码示例

function add_rewrite_endpoint( $name, $places, $query_var = true ) {
	global $wp_rewrite;
	$wp_rewrite->add_endpoint( $name, $places, $query_var );
}
📄 原文内容

Adds an endpoint, like /trackback/.

Description

Adding an endpoint creates extra rewrite rules for each of the matching places specified by the provided bitmask. For example:

add_rewrite_endpoint( 'json', EP_PERMALINK | EP_PAGES );

will add a new rewrite rule ending with “json(/(.*))?/?$” for every permastruct that describes a permalink (post) or page. This is rewritten to “json=$match” where $match is the part of the URL matched by the endpoint regex (e.g. “foo” in “[permalink]/json/foo/”).

A new query var with the same name as the endpoint will also be created.

When specifying $places ensure that you are using the EP_* constants (or a combination of them using the bitwise OR operator) as their values are not guaranteed to remain static (especially EP_ALL).

Be sure to flush the rewrite rules – see flush_rewrite_rules() – when your plugin gets activated and deactivated.

Parameters

$namestringrequired
Name of the endpoint.
$placesintrequired
Endpoint mask describing the places the endpoint should be added.
Accepts a mask of:

  • EP_ALL
  • EP_NONE
  • EP_ALL_ARCHIVES
  • EP_ATTACHMENT
  • EP_AUTHORS
  • EP_CATEGORIES
  • EP_COMMENTS
  • EP_DATE
  • EP_DAY
  • EP_MONTH
  • EP_PAGES
  • EP_PERMALINK
  • EP_ROOT
  • EP_SEARCH
  • EP_TAGS
  • EP_YEAR

$query_varstring|booloptional
Name of the corresponding query variable. Pass false to skip registering a query_var for this endpoint. Defaults to the value of $name.

Default:true

More Information

This adds the endpoint to all link types indicated (e.g. posts, pages, category, author, search) and then template-loader.php includes the relevant handler file.

The name of the endpoint is added as query variable and this gets as value any text present after the endpoint name, separated from the name with a ‘/’. The template_redirect action hook should test this query variable.

This can be used for all sorts of things:

  • ajax handler
  • form submission handler
  • alternative notification handler

Source

function add_rewrite_endpoint( $name, $places, $query_var = true ) {
	global $wp_rewrite;
	$wp_rewrite->add_endpoint( $name, $places, $query_var );
}

View all references View on Trac View on GitHub

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

Adds an endpoint, like /trackback/.

Changelog

Version Description
4.3.0 Added support for skipping query var registration by passing false to $query_var.
2.1.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    crstauf


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

    Available values for $places:

    EP_NONE
    Endpoint Mask for default, which is nothing.
    Bitwise value: 0

    EP_PERMALINK
    Endpoint Mask for Permalink.
    Bitwise value: 1

    EP_ATTACHMENT
    Endpoint Mask for Attachment.
    Bitwise value: 2

    EP_DATE
    Endpoint Mask for date.
    Bitwise value: 4

    EP_YEAR
    Endpoint Mask for year
    Bitwise value: 8

    EP_MONTH
    Endpoint Mask for month.
    Bitwise value: 16

    EP_DAY
    Endpoint Mask for day.
    Bitwise value: 32

    EP_ROOT
    Endpoint Mask for root.
    Bitwise value: 64

    EP_COMMENTS
    Endpoint Mask for comments.
    Bitwise value: 128

    EP_SEARCH
    Endpoint Mask for searches.
    Bitwise value: 256

    EP_CATEGORIES
    Endpoint Mask for categories.
    Bitwise value: 512

    EP_TAGS
    Endpoint Mask for tags.
    Bitwise value: 1024

    EP_AUTHORS
    Endpoint Mask for authors.
    Bitwise value: 2048

    EP_PAGES
    Endpoint Mask for pages.
    Bitwise value: 4096

    EP_ALL_ARCHIVES
    Endpoint Mask for all archive views.
    Same as using EP_DATE | EP_YEAR | EP_MONTH | EP_DAY | EP_CATEGORIES | EP_TAGS | EP_AUTHORS

    EP_ALL
    Endpoint Mask for everything.
    Same as using EP_PERMALINK | EP_ATTACHMENT | EP_ROOT | EP_COMMENTS | EP_SEARCH | EP_PAGES | EP_ALL_ARCHIVES