Function Reference/WP Rewrite

阅读这个文件的前提是，你熟悉Apache的mod_rewrite。如果你从没有听说过这个，试着阅读Beginner's Guide to URL Rewriting。

WP_Rewrite角色

WP_Rewrite是WordPress的class，用来管理rewrite 规则，使你能够使用Pretty Permalinks功能。从数据库中的参数值中产生rewrite 规则，有几种方法，当上传rewrite 规则的时候，是在内部使用的，同时查找某篇文章，某个网页，类别归档，等等的URL。定义在wp-includes/rewrite.php中而且一个全局singleton, $wp_rewrite,在wp-settings.php中初始化。

方法和属性

这是WP_Rewrite一个正式的文档。试着不要直接地访问或者设置属性，而是使用方法与$wp_rewrite object互动。

属性

$permalink_structure

数据库中的permalnk结构。这是你在Permalink选项网页上设置的内容，而且包含'标签' 像 %year%, %month% 和 %post_id%。

$category_base

在类别归档URLs之前插入的任何内容。默认为'类别/'。

$category_structure

类别归档URLs的结构。这只是$category_base和'%category%'。

$author_base

作者归档URLs之前插入的任何内容。默认为'作者/'。

$author_structure

作者归档URLs的结构。这只是$author_base和 '%author%'。

$feed_base

feed URLs之前插入的任何内容。默认为'feed/'。

$feed_structure

feed URLs的结构。这只是$feed_base 和 '%feed%'。

$search_base

searchs之前插入的任何内容。默认为'搜索/'。

$search_structure

搜索URLs的结构。这只是$search_base 和 '%search%'。

$comments_base

$feed_structure之前插入的任何内容，以得到最新的评论feed。默认为'评论'。

$comments_feed_structure

最新的评论feed的结构。这只是$comments_base 和 $feed_base 和'%feed%'。

$date_structure

有日期的归档URLs的结构。试着为'%year%/%monthnum%/%day%', '%day%/%monthnum%/%year%' 或者 '%monthnum%/%day%/%year%'，但是如果在你的$permalink_structure中没有发现这些，默认为'%year%/%monthnum%/%day%'。不同的函数使用这个结构得到更普通的结构：例如get_year_permastruct()这是从$date_structure中移除了'%monthnum%' 和 '%day%'标签。

$page_structure

网页结构。只是'%pagename%'。

$front

任何关于你的$permalink_structure第一个标签启动的内容。

$root

你的WordPress安装的根，是所有结构开始的地方。

$matches

当计算rewrite 规则的references的时候，在内部使用这个。

$rules

The rewrite rules. Set when rewrite_rules() is called.

$rules

rewrite规则。当调用rewrite_rules()时候，得到设置。

$non_wp_rules

Associative array of "rules that don't redirect to WP's index.php (and thus shouldn't be handled by WP at all)" roughly in the form 'Pattern' => 'Substitution' (see below).

$non_wp_rules

"没有redirect to WP's index.php的规则 (因此不应该由WP处理)"的结合数组，基本形式是'Pattern' => 'Substitution'（请看看下面的）。

$rewritecode

An array of all the tags available for the permalink structure. See Using Permalinks for a list.

$rewritecode

permalink结构可以使用的所有标签的数组。请看看Using Permalinks的列表。

$rewritereplace

对于rewrite 规则的regex部分，每个标签会由什么取代。$rewritereplace中的第一个元素是$rewritecode中第一个元素的regex，第二个元素对应着第二个，等等。

$queryreplace

在rewrite规则的rewrite部分，每个标签会由什么来取代。在$rewritereplace中可以取代的部分，在这里也可以适用。

方法

add_rewrite_tag($tag, $pattern, $query)

给$rewritecode, $rewritereplace和$queryreplace添加一个元素，单独地使用每个参数。如果$rewritecode中已经存在$tag，当前的参数值就会被覆盖。

flush_rules()

重新产生rewrite规则，并将这个规则保存到数据库中。

generate_rewrite_rule($permalink_structure, $walk_dirs = false)

从permalink结构中产生不提供必要服务的rewrite规则。没有将要创建的额外网页或者feeds的规则。

generate_rewrite_rules($permalink_structure, $ep_mask = EP_NONE, $page =true, $feed = true, $forcomments = false, $walk_dirs =true)

一个很大的函数，为一个给定的结构$permalink_structure产生rewrite规则。如果$page 是true，会产生额外的rewrite 规则，来访问不同的网页(例如 /category/tech/page/2 指向'tech' 类别归档的第二个页面)。如果$feed 是true，会产生额外的rewrite规则，得到当前页面的feed，而且如果$walk_dirs 是true，那么会产生当前结构的每个目录的rewrite规则，例如，如果你提供 '/%year%/%month%/%day/', rewrite 规则会产生 '/%year%/', /%year%/%month%/' 和'/%year%/%month%/%day%/'。这返回了结合数组，使用rewrite 规则的regex部分作为keys，使用 redirect part of the rewrite 规则的redirect部分作为参数值。

get_date_permastruct(), get_category_permastruct(), get_date_permastruct()等等

在相关的属性上加上内容（例如$date_structure关于get_date_permastruct()）。如果没有设置，将其返回。函数get_month_permastruct() 和get_year_permastruct()没有相关的属性：是通过获得$date_structure并且移除其不需要的标签（如get_month_permastruct() 移除了'%day%' 标签，因为其只要表明年份和月份）得到结构。

init()

设置object，从数据库中设置$permalink_structure和$category_base。将$root设置为$index加上'/'。将$front设置为permalink结构中第一个标签开始的任何内容。取消所有其它属性。

mod_rewrite_rules()

返回所有规则的字符串（不是数组）。包含在Apache <IfModule> block，确保激活了mod_rewrite。

page_rewrite_rules()

返回你已经创建的任何网页的规则。

rewrite_rules()

如generate_rewrite_rules()中那样，使用结合的数组填充并且返回$rules变数。这是从文章，日期，评论，搜索，类别，作者和网页结构中返回的。

set_category_base($category_base)

更改类别基础。

set_permalink_structure($permalink_structure)

更改permalink 结构。

using_index_permalinks()

如果你的博客使用PATHINFO permalinks，返回true。

using_mod_rewrite_permalinks

如果你的博客通过mod_rewrite使用"pretty"permalinks，返回true。

using_permalinks()

如果你的博客正在使用任何permalink结构（例如，不是默认的查询URIs ?p=n, ?cat=n），返回true。

WP_Rewrite (构造器)

调用 init()。

wp_rewrite_rules()

如rewrite_rules()，返回rewrite规则的数组，但是使用$matches[xxx]（xxx是个数字的位置），而不是普通的mod_rewrite backreferences，$xxx（xxx是个数字的位置）。当你准备在PHP内部使用规则的时候而不是在.htaccess文件中编写，这很有用。

插件Hooks

因为rewrite规则是你的网络博客泛函性的一个重要的方面，WordPress允许插件hook into几点的产生过程。rewrite_rules()包含有九个过滤器和一个hook来精确地控制rewrite规则的过程。下面是你可以在rewrite_rules()中过滤什么：

• 要过滤为permalinks URLs产生的重写规则，请使用post_rewrite_rules。

• 要过滤为日期归档 URLs产生的重写规则，请使用date_rewrite_rules。

• 要过滤为类别归档 URLs产生的重写规则，请使用category_rewrite_rules。

• 要过滤为搜索 URLs产生的重写规则，请使用search_rewrite_rules。

• 要过滤为最近评论feed URLs产生的重写规则，请使用comments_rewrite_rules。

• 要过滤为作者归档 URLs产生的重写规则，请使用author_rewrite_rules。

• 要过滤为你的网页产生的重写规则，请使用page_rewrite_rules。

• 要过滤为你的网络日志根目录产生的重写规则，请使用root_rewrite_rules。

• 要过滤整个内容，请使用rewrite_rules_array。

• action hook generate_rewrite_rules在所有规则创建之后，才运行。如果你的函数获得一个参数，会得到reference传递到整个$wp_rewrite object。

mod_rewrite_rules()是个函数，获得rewrite_rules()产生的数组，而且将这个转变为.htaccess文件的rewrite规则。这个函数也有过滤器mod_rewrite_rules，会传递函数所有规则的字符串，为.htaccess编写，包含<IfModule>周围的部分。（注：你可能也会看到插件使用rewrite_ruleshook，但是这个已经取消了)。

例子

（也看看：自定义归档的Permalinks）

插件处理$wp_rewrite 对象，典型的就是添加插件自身的rewrite 规则。这非常简单。过滤一般的rewrite_rules_array。Jerome's Keywords插件执行这个操作，激活URLs，如http://example.com/tag/sausages。

function keywords_createRewriteRules($rewrite) {
	global $wp_rewrite;
	
	//添加rewrite记号
	$keytag_token = '%tag%';
	$wp_rewrite->add_rewrite_tag($keytag_token, '(.+)', 'tag=');
	
	$keywords_structure = $wp_rewrite->root . "tag/$keytag_token";
	$keywords_rewrite = $wp_rewrite->generate_rewrite_rules($keywords_structure);
	
	return ( $rewrite + $keywords_rewrite );
}

Jerome没有将rewrite 规则插入到$rewrite数组，而是又创建了一个数组$keywords_rewrite，使用WP_Rewrite 函数generate_rewrite_rules()。使用那个函数，意味着这插件不需要为额外的网页（像page/2），或者feeds（像e feed/atom），等等创建rewrite规则。这个数组会附加到$rewrite数组上，并且会返回。

关于这个的一个简单的例子是Ryan Boren的Feed Director插件。这只是将URLs象http://example.com/feed.xml 导向了http://example.com/feed/rss2：

function feed_dir_rewrite($wp_rewrite) {
    $feed_rules = array(
        'index.rdf' => 'index.php?feed=rdf',
        'index.xml' => 'index.php?feed=rss2',
        '(.+).xml' => 'index.php?feed=' . $wp_rewrite->preg_index(1)
    );

    $wp_rewrite->rules = $feed_rules + $wp_rewrite->rules;
}

// Hook in.
add_filter('generate_rewrite_rules', 'feed_dir_rewrite');

因为这里的数组非常简单，没有必要调用generate_rewrite_rules()。同时，插件的规则添加到WordPress。注意因为这个函数过滤了generate_rewrite_rules，函数接受了整个$wp_rewrite object作为一个参数，而不仅仅rewrite 规则。

当然，因为你将你的rewrite规则添加到数组后，WordPress才能够处理这个规则，你的插件rewrite规则可能包含在WordPress处理rewrite规则的任何内容之中，象将其写入.htaccess文件一样。

非Wordpress rewrite规则

%%% <?php $wp_rewrite->non_wp_rules = array( 'Pattern' => 'Substitution' ); print_r($wp_rewrite->mod_rewrite_rules()); ?> %%%

prints

 <IfModule mod_rewrite.c>
 RewriteEngine On
 RewriteBase /wp_home/
 RewriteRule ^Pattern /wp_home/Substitution [QSA,L]
 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{REQUEST_FILENAME} !-d
 RewriteRule . /wp_home/index.php [L]
 </IfModule>

/wp_home/是WordPress的主目录（如果WordPress安装在你的网络根目录上，是根URL /。）