enmi-conf.org: comparison wp/wp-includes/rewrite.php

equal deleted inserted replaced

-:346c88efed21
+:5e2f62d02dcd
 * Add an endpoint, like /trackback/.
 *
 * Adding an endpoint creates extra rewrite rules for each of the matching
 * places specified by the provided bitmask. For example:
 *
-* <code>
+*     add_rewrite_endpoint( 'json', EP_PERMALINK | EP_PAGES );
-* add_rewrite_endpoint( 'json', EP_PERMALINK | EP_PAGES );
-* </code>
 *
 * 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/").
+* "[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).
+* guaranteed to remain static (especially `EP_ALL`).
 *
-* Be sure to flush the rewrite rules - flush_rewrite_rules() - when your plugin gets
+* Be sure to flush the rewrite rules - {@see flush_rewrite_rules()} - when your plugin gets
 * activated and deactivated.
 *
 * @since 2.1.0
 * @see WP_Rewrite::add_endpoint()
 * @global object $wp_rewrite
 *
 * @param string $name Name of the endpoint.
 * @param int $places Endpoint mask describing the places the endpoint should be added.
-*/
+* @param string $query_var Name of the corresponding query variable. Defaults to $name.
-function add_rewrite_endpoint( $name, $places ) {
+*/
+function add_rewrite_endpoint( $name, $places, $query_var = null ) {
 	global $wp_rewrite;
-	$wp_rewrite->add_endpoint( $name, $places );
+	$wp_rewrite->add_endpoint( $name, $places, $query_var );
 }
 /**
 * Filter the URL base for taxonomies.
 *
 * @return int Post ID, or 0 on failure.
 */
 function url_to_postid($url) {
 	global $wp_rewrite;
-	$url = apply_filters('url_to_postid', $url);
+	/**
+	 * Filter the URL to derive the post ID from.
+	 *
+	 * @since 2.2.0
+	 *
+	 * @param string $url The URL to derive the post ID from.
+	 */
+	$url = apply_filters( 'url_to_postid', $url );
 	// First, check to see if there is a 'p=N' or 'page_id=N' to match against
 	if ( preg_match('#[?&](p|page_id|attachment_id)=(\d+)#', $url, $values) )	{
 		$id = absint($values[2]);
 		if ( $id )
 		// If the requesting file is the anchor of the match, prepend it
 		// to the path info.
 		if ( !empty($url) && ($url != $request) && (strpos($match, $url) === 0) )
 			$request_match = $url . '/' . $request;
-		if ( preg_match("!^$match!", $request_match, $matches) ) {
+		if ( preg_match("#^$match#", $request_match, $matches) ) {
 			if ( $wp_rewrite->use_verbose_page_rules && preg_match( '/pagename=\$matches\[([0-9]+)\]/', $query, $varmatch ) ) {
-				// this is a verbose page match, lets check to be sure about it
+				// This is a verbose page match, let's check to be sure about it.
 				if ( ! get_page_by_path( $matches[ $varmatch[1] ] ) )
 					continue;
 			}
 			// Got a match.
 class WP_Rewrite {
 	/**
 	 * Permalink structure for posts.
 	 *
 	 * @since 1.5.0
+	 * @var string
+	 */
+	public $permalink_structure;
+	/**
+	 * Whether to add trailing slashes.
+	 *
+	 * @since 2.2.0
+	 * @var bool
+	 */
+	public $use_trailing_slashes;
+	/**
+	 * Base for the author permalink structure (example.com/$author_base/authorname).
+	 *
+	 * @since 1.5.0
 	 * @access private
 	 * @var string
 	 */
-	var $permalink_structure;
+	var $author_base = 'author';
 	/**
-	 * Whether to add trailing slashes.
+	 * Permalink structure for author archives.
-	 *
-	 * @since 2.2.0
-	 * @access private
-	 * @var bool
-	 */
-	var $use_trailing_slashes;
-	/**
-	 * Base for the author permalink structure (example.com/$author_base/authorname).
 	 *
 	 * @since 1.5.0
 	 * @access private
 	 * @var string
 	 */
-	var $author_base = 'author';
+	var $author_structure;
 	/**
-	 * Permalink structure for author archives.
+	 * Permalink structure for date archives.
 	 *
 	 * @since 1.5.0
 	 * @access private
 	 * @var string
 	 */
-	var $author_structure;
+	var $date_structure;
 	/**
-	 * Permalink structure for date archives.
+	 * Permalink structure for pages.
 	 *
 	 * @since 1.5.0
 	 * @access private
 	 * @var string
 	 */
-	var $date_structure;
+	var $page_structure;
 	/**
-	 * Permalink structure for pages.
+	 * Base of the search permalink structure (example.com/$search_base/query).
 	 *
 	 * @since 1.5.0
 	 * @access private
 	 * @var string
 	 */
-	var $page_structure;
+	var $search_base = 'search';
 	/**
-	 * Base of the search permalink structure (example.com/$search_base/query).
+	 * Permalink structure for searches.
 	 *
 	 * @since 1.5.0
 	 * @access private
 	 * @var string
 	 */
-	var $search_base = 'search';
+	var $search_structure;
 	/**
-	 * Permalink structure for searches.
+	 * Comments permalink base.
 	 *
 	 * @since 1.5.0
 	 * @access private
 	 * @var string
 	 */
-	var $search_structure;
+	var $comments_base = 'comments';
 	/**
-	 * Comments permalink base.
+	 * Pagination permalink base.
 	 *
-	 * @since 1.5.0
+	 * @since 3.1.0
+	 * @var string
+	 */
+	public $pagination_base = 'page';
+	/**
+	 * Comments pagination permalink base.
+	 *
+	 * @since 4.2.0
 	 * @access private
 	 * @var string
 	 */
-	var $comments_base = 'comments';
+	var $comments_pagination_base = 'comment-page';
 	/**
-	 * Pagination permalink base.
+	 * Feed permalink base.
 	 *
-	 * @since 3.1.0
+	 * @since 1.5.0
 	 * @access private
 	 * @var string
 	 */
-	var $pagination_base = 'page';
+	var $feed_base = 'feed';
 	/**
-	 * Feed permalink base.
+	 * Comments feed permalink structure.
 	 *
 	 * @since 1.5.0
 	 * @access private
 	 * @var string
 	 */
-	var $feed_base = 'feed';
+	var $comment_feed_structure;
-	/**
-	 * Comments feed permalink structure.
-	 *
-	 * @since 1.5.0
-	 * @access private
-	 * @var string
-	 */
-	var $comments_feed_structure;
 	/**
 	 * Feed request permalink structure.
 	 *
 	 * @since 1.5.0
 	 * is "/archive/". If the permalink structure is "/%year%/%postname%/"
 	 * then the front is "/".
 	 *
 	 * @see WP_Rewrite::init()
 	 * @since 1.5.0
-	 * @access private
 	 * @var string
 	 */
-	var $front;
+	public $front;
 	/**
 	 * The prefix for all permalink structures.
 	 *
 	 * If PATHINFO/index permalinks are in use then the root is the value of
 	 * the root will be empty.
 	 *
 	 * @see WP_Rewrite::init()
 	 * @see WP_Rewrite::using_index_permalinks()
 	 * @since 1.5.0
-	 * @access private
 	 * @var string
 	 */
-	var $root = '';
+	public $root = '';
 	/**
 	 * The name of the index file which is the entry point to all requests.
 	 *
 	 * @since 1.5.0
 	 * @access public
 	 * @var string
 	 */
-	var $index = 'index.php';
+	public $index = 'index.php';
 	/**
 	 * Variable name to use for regex matches in the rewritten query.
 	 *
 	 * @since 1.5.0
 	 * @see WP_Rewrite::mod_rewrite_rules()
 	 * @since 2.0.0
 	 * @access public
 	 * @var bool
 	 */
-	var $use_verbose_rules = false;
+	public $use_verbose_rules = false;
 	/**
 	 * Could post permalinks be confused with those of pages?
 	 *
 	 * If the first rewrite tag in the post permalink structure is one that could
 	 * set to true. Prior to WordPress 3.3 this flag indicated that every page
 	 * would have a set of rules added to the top of the rewrite rules array.
 	 * Now it tells {@link WP::parse_request()} to check if a URL matching the
 	 * page permastruct is actually a page before accepting it.
 	 *
-	 * @link http://core.trac.wordpress.org/ticket/16687
+	 * @link https://core.trac.wordpress.org/ticket/16687
 	 * @see WP_Rewrite::init()
 	 * @since 2.5.0
 	 * @access public
 	 * @var bool
 	 */
-	var $use_verbose_page_rules = true;
+	public $use_verbose_page_rules = true;
 	/**
 	 * Rewrite tags that can be used in permalink structures.
 	 *
 	 * These are translated into the regular expressions stored in
 	/**
 	 * Supported default feeds.
 	 *
 	 * @since 1.5.0
-	 * @access private
 	 * @var array
 	 */
-	var $feeds = array( 'feed', 'rdf', 'rss', 'rss2', 'atom' );
+	public $feeds = array( 'feed', 'rdf', 'rss', 'rss2', 'atom' );
 	/**
 	 * Whether permalinks are being used.
 	 *
 	 * This can be either rewrite module or permalink in the HTTP query string.
 	 * @since 1.5.0
 	 * @access public
 	 *
 	 * @return bool True, if permalinks are enabled.
 	 */
-	function using_permalinks() {
+	public function using_permalinks() {
 		return ! empty($this->permalink_structure);
 	}
 	/**
 	 * Whether permalinks are being used and rewrite module is not enabled.
 	 * @since 1.5.0
 	 * @access public
 	 *
 	 * @return bool
 	 */
-	function using_index_permalinks() {
+	public function using_index_permalinks() {
 		if ( empty($this->permalink_structure) )
 			return false;
 		// If the index is not in the permalink, we're using mod_rewrite.
 		if ( preg_match('#^/*' . $this->index . '#', $this->permalink_structure) )
 	 * @since 1.5.0
 	 * @access public
 	 *
 	 * @return bool
 	 */
-	function using_mod_rewrite_permalinks() {
+	public function using_mod_rewrite_permalinks() {
 		if ( $this->using_permalinks() && ! $this->using_index_permalinks() )
 			return true;
 		else
 			return false;
 	}
 	 * @access public
 	 *
 	 * @param int $number Index number.
 	 * @return string
 	 */
-	function preg_index($number) {
+	public function preg_index($number) {
 		$match_prefix = '$';
 		$match_suffix = '';
 		if ( ! empty($this->matches) ) {
 			$match_prefix = '$' . $this->matches . '[';
 	 * @since 2.5.0
 	 * @access public
 	 *
 	 * @return array Array of page URIs as first element and attachment URIs as second element.
 	 */
-	function page_uri_index() {
+	public function page_uri_index() {
 		global $wpdb;
 		//get pages in order of hierarchy, i.e. children after parents
 		$pages = $wpdb->get_results("SELECT ID, post_name, post_parent FROM $wpdb->posts WHERE post_type = 'page' AND post_status != 'auto-draft'");
 		$posts = get_page_hierarchy( $pages );
 	 * @since 1.5.0
 	 * @access public
 	 *
 	 * @return array
 	 */
-	function page_rewrite_rules() {
+	public function page_rewrite_rules() {
 		// the extra .? at the beginning prevents clashes with other regular expressions in the rules array
 		$this->add_rewrite_tag( '%pagename%', '(.?.+?)', 'pagename=' );
 		return $this->generate_rewrite_rules( $this->get_page_permastruct(), EP_PAGES, true, true, false, false );
 	}
 	 * structure.
 	 *
 	 * @since 1.5.0
 	 * @access public
 	 *
-	 * @return bool|string False on no permalink structure. Date permalink structure.
+	 * @return string|false False on no permalink structure. Date permalink structure.
 	 */
-	function get_date_permastruct() {
+	public function get_date_permastruct() {
 		if ( isset($this->date_structure) )
 			return $this->date_structure;
 		if ( empty($this->permalink_structure) ) {
 			$this->date_structure = '';
 	 * permalink structures.
 	 *
 	 * @since 1.5.0
 	 * @access public
 	 *
-	 * @return bool|string False on failure. Year structure on success.
+	 * @return false|string False on failure. Year structure on success.
 	 */
-	function get_year_permastruct() {
+	public function get_year_permastruct() {
 		$structure = $this->get_date_permastruct();
 		if ( empty($structure) )
 			return false;
 	 * structures. Keeps the year permalink structure.
 	 *
 	 * @since 1.5.0
 	 * @access public
 	 *
-	 * @return bool|string False on failure. Year/Month structure on success.
+	 * @return false|string False on failure. Year/Month structure on success.
 	 */
-	function get_month_permastruct() {
+	public function get_month_permastruct() {
 		$structure = $this->get_date_permastruct();
 		if ( empty($structure) )
 			return false;
 	 * Keeps date permalink structure with all year, month, and day.
 	 *
 	 * @since 1.5.0
 	 * @access public
 	 *
-	 * @return bool|string False on failure. Year/Month/Day structure on success.
+	 * @return string|false False on failure. Year/Month/Day structure on success.
 	 */
-	function get_day_permastruct() {
+	public function get_day_permastruct() {
 		return $this->get_date_permastruct();
 	}
 	/**
 	 * Retrieve the permalink structure for categories.
 	 * @since 1.5.0
 	 * @access public
 	 *
 	 * @return bool|string False on failure. Category permalink structure.
 	 */
-	function get_category_permastruct() {
+	public function get_category_permastruct() {
 		return $this->get_extra_permastruct('category');
 	}
 	/**
 	 * Retrieve the permalink structure for tags.
 	 * @since 2.3.0
 	 * @access public
 	 *
 	 * @return bool|string False on failure. Tag permalink structure.
 	 */
-	function get_tag_permastruct() {
+	public function get_tag_permastruct() {
 		return $this->get_extra_permastruct('post_tag');
 	}
 	/**
 	 * Retrieve extra permalink structure by name.
 	 * @access public
 	 *
 	 * @param string $name Permalink structure name.
 	 * @return string|bool False if not found. Permalink structure string.
 	 */
-	function get_extra_permastruct($name) {
+	public function get_extra_permastruct($name) {
 		if ( empty($this->permalink_structure) )
 			return false;
 		if ( isset($this->extra_permastructs[$name]) )
 			return $this->extra_permastructs[$name]['struct'];
 	 * without attempting to set the value again.
 	 *
 	 * @since 1.5.0
 	 * @access public
 	 *
-	 * @return string|bool False if not found. Permalink structure string.
+	 * @return string|false False if not found. Permalink structure string.
 	 */
-	function get_author_permastruct() {
+	public function get_author_permastruct() {
 		if ( isset($this->author_structure) )
 			return $this->author_structure;
 		if ( empty($this->permalink_structure) ) {
 			$this->author_structure = '';
 	 * without attempting to set the value again.
 	 *
 	 * @since 1.5.0
 	 * @access public
 	 *
-	 * @return string|bool False if not found. Permalink structure string.
+	 * @return string|false False if not found. Permalink structure string.
 	 */
-	function get_search_permastruct() {
+	public function get_search_permastruct() {
 		if ( isset($this->search_structure) )
 			return $this->search_structure;
 		if ( empty($this->permalink_structure) ) {
 			$this->search_structure = '';
 	 * value again.
 	 *
 	 * @since 1.5.0
 	 * @access public
 	 *
-	 * @return string|bool False if not found. Permalink structure string.
+	 * @return string|false False if not found. Permalink structure string.
 	 */
-	function get_page_permastruct() {
+	public function get_page_permastruct() {
 		if ( isset($this->page_structure) )
 			return $this->page_structure;
 		if (empty($this->permalink_structure)) {
 			$this->page_structure = '';
 	 * without attempting to set the value again.
 	 *
 	 * @since 1.5.0
 	 * @access public
 	 *
-	 * @return string|bool False if not found. Permalink structure string.
+	 * @return string|false False if not found. Permalink structure string.
 	 */
-	function get_feed_permastruct() {
+	public function get_feed_permastruct() {
 		if ( isset($this->feed_structure) )
 			return $this->feed_structure;
 		if ( empty($this->permalink_structure) ) {
 			$this->feed_structure = '';
 	 * @since 1.5.0
 	 * @access public
 	 *
 	 * @return string|bool False if not found. Permalink structure string.
 	 */
-	function get_comment_feed_permastruct() {
+	public function get_comment_feed_permastruct() {
 		if ( isset($this->comment_feed_structure) )
 			return $this->comment_feed_structure;
 		if (empty($this->permalink_structure)) {
 			$this->comment_feed_structure = '';
 	 *
 	 * @param string $tag Name of the rewrite tag to add or update.
 	 * @param string $regex Regular expression to substitute the tag for in rewrite rules.
 	 * @param string $query String to append to the rewritten query. Must end in '='.
 	 */
-	function add_rewrite_tag( $tag, $regex, $query ) {
+	public function add_rewrite_tag( $tag, $regex, $query ) {
 		$position = array_search( $tag, $this->rewritecode );
 		if ( false !== $position && null !== $position ) {
 			$this->rewritereplace[ $position ] = $regex;
 			$this->queryreplace[ $position ] = $query;
 		} else {
 	 * @param bool $walk_dirs Should the 'directories' making up the structure be walked over and rewrite rules
 	 *                        built for each in turn? Default is true.
 	 * @param bool $endpoints Should endpoints be applied to the generated rewrite rules? Default is true.
 	 * @return array Rewrite rule list.
 	 */
-	function generate_rewrite_rules($permalink_structure, $ep_mask = EP_NONE, $paged = true, $feed = true, $forcomments = false, $walk_dirs = true, $endpoints = true) {
+	public function generate_rewrite_rules($permalink_structure, $ep_mask = EP_NONE, $paged = true, $feed = true, $forcomments = false, $walk_dirs = true, $endpoints = true) {
 		//build a regex to match the feed section of URLs, something like (feed|atom|rss|rss2)/?
 		$feedregex2 = '';
 		foreach ( (array) $this->feeds as $feed_name)
 			$feedregex2 .= $feed_name . '|';
 		$feedregex2 = '(' . trim($feedregex2, '|') . ')/?$';
 		$feedregex = $this->feed_base . '/' . $feedregex2;
 		//build a regex to match the trackback and page/xx parts of URLs
 		$trackbackregex = 'trackback/?$';
 		$pageregex = $this->pagination_base . '/?([0-9]{1,})/?$';
-		$commentregex = 'comment-page-([0-9]{1,})/?$';
+		$commentregex = $this->comments_pagination_base . '-([0-9]{1,})/?$';
 		//build up an array of endpoint regexes to append => queries to append
 		if ( $endpoints ) {
 			$ep_query_append = array ();
 			foreach ( (array) $this->endpoints as $endpoint) {
 				//match everything after the endpoint name, but allow for nothing to appear there
 				$epmatch = $endpoint[1] . '(/(.*))?/?$';
 				//this will be appended on to the rest of the query for each dir
-				$epquery = '&' . $endpoint[1] . '=';
+				$epquery = '&' . $endpoint[2] . '=';
 				$ep_query_append[$epmatch] = array ( $endpoint[0], $epquery );
 			}
 		}
 		//get everything up to the first rewrite tag
 		$index = $this->index; //probably 'index.php'
 		$feedindex = $index;
 		$trackbackindex = $index;
 		//build a list from the rewritecode and queryreplace arrays, that will look something like
 		//tagname=$matches[i] where i is the current $i
+		$queries = array();
 		for ( $i = 0; $i < $num_tokens; ++$i ) {
 			if ( 0 < $i )
 				$queries[$i] = $queries[$i - 1] . '&';
 			else
 				$queries[$i] = '';
 			//make a list of tags, and store how many there are in $num_toks
 			$num_toks = preg_match_all('/%.+?%/', $struct, $toks);
 			//get the 'tagname=$matches[i]'
-			$query = ( isset($queries) && is_array($queries) && !empty($num_toks) ) ? $queries[$num_toks - 1] : '';
+			$query = ( ! empty( $num_toks ) && isset( $queries[$num_toks - 1] ) ) ? $queries[$num_toks - 1] : '';
 			//set up $ep_mask_specific which is used to match more specific URL types
 			switch ( $dirs[$j] ) {
 				case '%year%':
 					$ep_mask_specific = EP_YEAR;
 				$rewrite = array($feedmatch => $feedquery, $feedmatch2 => $feedquery2);
 			if ( $paged ) //...and /page/xx ones
 				$rewrite = array_merge($rewrite, array($pagematch => $pagequery));
 			//only on pages with comments add ../comment-page-xx/
-			if ( EP_PAGES & $ep_mask || EP_PERMALINK & $ep_mask )
+			if ( EP_PAGES & $ep_mask || EP_PERMALINK & $ep_mask ) {
 				$rewrite = array_merge($rewrite, array($commentmatch => $commentquery));
-			else if ( EP_ROOT & $ep_mask && get_option('page_on_front') )
+			} elseif ( EP_ROOT & $ep_mask && get_option('page_on_front') ) {
 				$rewrite = array_merge($rewrite, array($rootcommentmatch => $rootcommentquery));
+			}
 			//do endpoints
 			if ( $endpoints ) {
 				foreach ( (array) $ep_query_append as $regex => $ep) {
 					//add the endpoints on if the mask fits
 					if ( $ep[0] & $ep_mask || $ep[0] & $ep_mask_specific )
 	 *
 	 * @param string $permalink_structure The permalink structure to generate rules.
 	 * @param bool $walk_dirs Optional, default is false. Whether to create list of directories to walk over.
 	 * @return array
 	 */
-	function generate_rewrite_rule($permalink_structure, $walk_dirs = false) {
+	public function generate_rewrite_rule($permalink_structure, $walk_dirs = false) {
 		return $this->generate_rewrite_rules($permalink_structure, EP_NONE, false, false, false, $walk_dirs);
 	}
 	/**
 	 * Construct rewrite matches and queries from permalink structure.
 	 * @since 1.5.0
 	 * @access public
 	 *
 	 * @return array An associate array of matches and queries.
 	 */
-	function rewrite_rules() {
+	public function rewrite_rules() {
 		$rewrite = array();
 		if ( empty($this->permalink_structure) )
 			return $rewrite;
 			$registration_pages['.*wp-signup.php$'] = $this->index . '?signup=true';
 			$registration_pages['.*wp-activate.php$'] = $this->index . '?activate=true';
 		}
 		$registration_pages['.*wp-register.php$'] = $this->index . '?register=true'; // Deprecated
-		// Post
+		// Post rewrite rules.
 		$post_rewrite = $this->generate_rewrite_rules( $this->permalink_structure, EP_PERMALINK );
-		$post_rewrite = apply_filters('post_rewrite_rules', $post_rewrite);
+		/**
-		// Date
+		 * Filter rewrite rules used for "post" archives.
+		 *
+		 * @since 1.5.0
+		 *
+		 * @param array $post_rewrite The rewrite rules for posts.
+		 */
+		$post_rewrite = apply_filters( 'post_rewrite_rules', $post_rewrite );
+		// Date rewrite rules.
 		$date_rewrite = $this->generate_rewrite_rules($this->get_date_permastruct(), EP_DATE);
-		$date_rewrite = apply_filters('date_rewrite_rules', $date_rewrite);
+		/**
-		// Root
+		 * Filter rewrite rules used for date archives.
+		 *
+		 * Likely date archives would include /yyyy/, /yyyy/mm/, and /yyyy/mm/dd/.
+		 *
+		 * @since 1.5.0
+		 *
+		 * @param array $date_rewrite The rewrite rules for date archives.
+		 */
+		$date_rewrite = apply_filters( 'date_rewrite_rules', $date_rewrite );
+		// Root-level rewrite rules.
 		$root_rewrite = $this->generate_rewrite_rules($this->root . '/', EP_ROOT);
-		$root_rewrite = apply_filters('root_rewrite_rules', $root_rewrite);
+		/**
-		// Comments
+		 * Filter rewrite rules used for root-level archives.
+		 *
+		 * Likely root-level archives would include pagination rules for the homepage
+		 * as well as site-wide post feeds (e.g. /feed/, and /feed/atom/).
+		 *
+		 * @since 1.5.0
+		 *
+		 * @param array $root_rewrite The root-level rewrite rules.
+		 */
+		$root_rewrite = apply_filters( 'root_rewrite_rules', $root_rewrite );
+		// Comments rewrite rules.
 		$comments_rewrite = $this->generate_rewrite_rules($this->root . $this->comments_base, EP_COMMENTS, false, true, true, false);
-		$comments_rewrite = apply_filters('comments_rewrite_rules', $comments_rewrite);
+		/**
-		// Search
+		 * Filter rewrite rules used for comment feed archives.
+		 *
+		 * Likely comments feed archives include /comments/feed/, and /comments/feed/atom/.
+		 *
+		 * @since 1.5.0
+		 *
+		 * @param array $comments_rewrite The rewrite rules for the site-wide comments feeds.
+		 */
+		$comments_rewrite = apply_filters( 'comments_rewrite_rules', $comments_rewrite );
+		// Search rewrite rules.
 		$search_structure = $this->get_search_permastruct();
 		$search_rewrite = $this->generate_rewrite_rules($search_structure, EP_SEARCH);
-		$search_rewrite = apply_filters('search_rewrite_rules', $search_rewrite);
+		/**
-		// Authors
+		 * Filter rewrite rules used for search archives.
+		 *
+		 * Likely search-related archives include /search/search+query/ as well as
+		 * pagination and feed paths for a search.
+		 *
+		 * @since 1.5.0
+		 *
+		 * @param array $search_rewrite The rewrite rules for search queries.
+		 */
+		$search_rewrite = apply_filters( 'search_rewrite_rules', $search_rewrite );
+		// Author rewrite rules.
 		$author_rewrite = $this->generate_rewrite_rules($this->get_author_permastruct(), EP_AUTHORS);
-		$author_rewrite = apply_filters('author_rewrite_rules', $author_rewrite);
+		/**
-		// Pages
+		 * Filter rewrite rules used for author archives.
+		 *
+		 * Likely author archives would include /author/author-name/, as well as
+		 * pagination and feed paths for author archives.
+		 *
+		 * @since 1.5.0
+		 *
+		 * @param array $author_rewrite The rewrite rules for author archives.
+		 */
+		$author_rewrite = apply_filters( 'author_rewrite_rules', $author_rewrite );
+		// Pages rewrite rules.
 		$page_rewrite = $this->page_rewrite_rules();
-		$page_rewrite = apply_filters('page_rewrite_rules', $page_rewrite);
+		/**
-		// Extra permastructs
+		 * Filter rewrite rules used for "page" post type archives.
+		 *
+		 * @since 1.5.0
+		 *
+		 * @param array $page_rewrite The rewrite rules for the "page" post type.
+		 */
+		$page_rewrite = apply_filters( 'page_rewrite_rules', $page_rewrite );
+		// Extra permastructs.
 		foreach ( $this->extra_permastructs as $permastructname => $struct ) {
 			if ( is_array( $struct ) ) {
 				if ( count( $struct ) == 2 )
 					$rules = $this->generate_rewrite_rules( $struct[0], $struct[1] );
 				else
 					$rules = $this->generate_rewrite_rules( $struct['struct'], $struct['ep_mask'], $struct['paged'], $struct['feed'], $struct['forcomments'], $struct['walk_dirs'], $struct['endpoints'] );
 			} else {
 				$rules = $this->generate_rewrite_rules( $struct );
 			}
-			$rules = apply_filters($permastructname . '_rewrite_rules', $rules);
+			/**
-			if ( 'post_tag' == $permastructname )
+			 * Filter rewrite rules used for individual permastructs.
-				$rules = apply_filters('tag_rewrite_rules', $rules);
+			 *
+			 * The dynamic portion of the hook name, `$permastructname`, refers
+			 * to the name of the registered permastruct, e.g. 'post_tag' (tags),
+			 * 'category' (categories), etc.
+			 *
+			 * @since 3.1.0
+			 *
+			 * @param array $rules The rewrite rules generated for the current permastruct.
+			 */
+			$rules = apply_filters( $permastructname . '_rewrite_rules', $rules );
+			if ( 'post_tag' == $permastructname ) {
+				/**
+				 * Filter rewrite rules used specifically for Tags.
+				 *
+				 * @since 2.3.0
+				 * @deprecated 3.1.0 Use 'post_tag_rewrite_rules' instead
+				 *
+				 * @param array $rules The rewrite rules generated for tags.
+				 */
+				$rules = apply_filters( 'tag_rewrite_rules', $rules );
+			}
 			$this->extra_rules_top = array_merge($this->extra_rules_top, $rules);
 		}
 		// Put them together.
 		if ( $this->use_verbose_page_rules )
 			$this->rules = array_merge($this->extra_rules_top, $robots_rewrite, $deprecated_files, $registration_pages, $root_rewrite, $comments_rewrite, $search_rewrite,  $author_rewrite, $date_rewrite, $page_rewrite, $post_rewrite, $this->extra_rules);
 		else
 			$this->rules = array_merge($this->extra_rules_top, $robots_rewrite, $deprecated_files, $registration_pages, $root_rewrite, $comments_rewrite, $search_rewrite,  $author_rewrite, $date_rewrite, $post_rewrite, $page_rewrite, $this->extra_rules);
-		do_action_ref_array('generate_rewrite_rules', array(&$this));
+		/**
-		$this->rules = apply_filters('rewrite_rules_array', $this->rules);
+		 * Fires after the rewrite rules are generated.
+		 *
+		 * @since 1.5.0
+		 *
+		 * @param WP_Rewrite $this Current WP_Rewrite instance, passed by reference.
+		 */
+		do_action_ref_array( 'generate_rewrite_rules', array( &$this ) );
+		/**
+		 * Filter the full set of generated rewrite rules.
+		 *
+		 * @since 1.5.0
+		 *
+		 * @param array $this->rules The compiled array of rewrite rules.
+		 */
+		$this->rules = apply_filters( 'rewrite_rules_array', $this->rules );
 		return $this->rules;
 	}
 	/**
 	 * @since 1.5.0
 	 * @access public
 	 *
 	 * @return array Rewrite rules.
 	 */
-	function wp_rewrite_rules() {
+	public function wp_rewrite_rules() {
 		$this->rules = get_option('rewrite_rules');
 		if ( empty($this->rules) ) {
 			$this->matches = 'matches';
 			$this->rewrite_rules();
 			update_option('rewrite_rules', $this->rules);
 	 * @since 1.5.0
 	 * @access public
 	 *
 	 * @return string
 	 */
-	function mod_rewrite_rules() {
+	public function mod_rewrite_rules() {
 		if ( ! $this->using_permalinks() )
 			return '';
 		$site_root = parse_url( site_url() );
 		if ( isset( $site_root['path'] ) )
 				"RewriteRule . {$home_root}{$this->index} [L]\n";
 		}
 		$rules .= "</IfModule>\n";
-		$rules = apply_filters('mod_rewrite_rules', $rules);
+		/**
-		$rules = apply_filters('rewrite_rules', $rules);  // Deprecated
+		 *
+		 * Filter the list of rewrite rules formatted for output to an .htaccess file.
+		 *
+		 * @since 1.5.0
+		 *
+		 * @param string $rules mod_rewrite Rewrite rules formatted for .htaccess.
+		 */
+		$rules = apply_filters( 'mod_rewrite_rules', $rules );
+		/**
+		 * Filter the list of rewrite rules formatted for output to an .htaccess file.
+		 *
+		 * @since 1.5.0
+		 * @deprecated 1.5.0 Use the mod_rewrite_rules filter instead.
+		 *
+		 * @param string $rules mod_rewrite Rewrite rules formatted for .htaccess.
+		 */
+		$rules = apply_filters( 'rewrite_rules', $rules );  // Deprecated
 		return $rules;
 	}
 	/**
 	 * @since 2.8.0
 	 * @access public
 	 *
 	 * @return string
 	 */
-	function iis7_url_rewrite_rules( $add_parent_tags = false ) {
+	public function iis7_url_rewrite_rules( $add_parent_tags = false ) {
 		if ( ! $this->using_permalinks() )
 			return '';
 		$rules = '';
 		if ( $add_parent_tags ) {
 		</rewrite>
 	</system.webServer>
 </configuration>';
 		}
-		$rules = apply_filters('iis7_url_rewrite_rules', $rules);
+		/**
+		 * Filter the list of rewrite rules formatted for output to a web.config.
+		 *
+		 * @since 2.8.0
+		 *
+		 * @param string $rules Rewrite rules formatted for IIS web.config.
+		 */
+		$rules = apply_filters( 'iis7_url_rewrite_rules', $rules );
 		return $rules;
 	}
 	/**
 	 *
 	 * @param string $regex Regular expression to match against request.
 	 * @param string $redirect URL regex redirects to when regex matches request.
 	 * @param string $after Optional, default is bottom. Location to place rule.
 	 */
-	function add_rule($regex, $redirect, $after = 'bottom') {
+	public function add_rule($regex, $redirect, $after = 'bottom') {
 		//get everything up to the first ?
 		$index = (strpos($redirect, '?') == false ? strlen($redirect) : strpos($redirect, '?'));
 		$front = substr($redirect, 0, $index);
 		if ( $front != $this->index ) { //it doesn't redirect to WP's index.php
 			$this->add_external_rule($regex, $redirect);
 	 * @access public
 	 *
 	 * @param string $regex Regular expression to match against request.
 	 * @param string $redirect URL regex redirects to when regex matches request.
 	 */
-	function add_external_rule($regex, $redirect) {
+	public function add_external_rule($regex, $redirect) {
 		$this->non_wp_rules[$regex] = $redirect;
 	}
 	/**
 	 * Add an endpoint, like /trackback/.
 	 *
-	 * See {@link add_rewrite_endpoint()} for full documentation.
-	 *
-	 * @see add_rewrite_endpoint()
 	 * @since 2.1.0
-	 * @access public
+	 * @since 3.9.0 $query_var parameter added.
+	 * @access public
+	 *
+	 * @see add_rewrite_endpoint() for full documentation.
 	 * @uses WP::add_query_var()
 	 *
-	 * @param string $name Name of the endpoint.
+	 * @param string $name      Name of the endpoint.
-	 * @param int $places Endpoint mask describing the places the endpoint should be added.
+	 * @param int    $places    Endpoint mask describing the places the endpoint should be added.
-	 */
+	 * @param string $query_var Name of the corresponding query variable. Default is value of $name.
-	function add_endpoint($name, $places) {
+	 */
+	public function add_endpoint( $name, $places, $query_var = null ) {
 		global $wp;
-		$this->endpoints[] = array ( $places, $name );
+		if ( null === $query_var ) {
-		$wp->add_query_var($name);
+			$query_var = $name;
+		}
+		$this->endpoints[] = array( $places, $name, $query_var );
+		$wp->add_query_var( $query_var );
 	}
 	/**
 	 * Add a new permalink structure.
 	 *
 	 *     - forcomments (bool) - Should the feed rules be a query for a comments feed? Default is false.
 	 *     - walk_dirs (bool) - Should the 'directories' making up the structure be walked over and rewrite
 	 *                          rules built for each in turn? Default is true.
 	 *     - endpoints (bool) - Should endpoints be applied to the generated rewrite rules? Default is true.
 	 */
-	function add_permastruct( $name, $struct, $args = array() ) {
+	public function add_permastruct( $name, $struct, $args = array() ) {
 		// backwards compatibility 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 );
 	 *
 	 * @since 2.0.1
 	 * @access public
 	 * @param bool $hard Whether to update .htaccess (hard flush) or just update rewrite_rules option (soft flush). Default is true (hard).
 	 */
-	function flush_rules($hard = true) {
+	public function flush_rules( $hard = true ) {
+		static $do_hard_later;
+		// Prevent this action from running before everyone has registered their rewrites
+		if ( ! did_action( 'wp_loaded' ) ) {
+			add_action( 'wp_loaded', array( $this, 'flush_rules' ) );
+			$do_hard_later = ( isset( $do_hard_later ) ) ? $do_hard_later || $hard : $hard;
+			return;
+		}
+		if ( isset( $do_hard_later ) ) {
+			$hard = $do_hard_later;
+			unset( $do_hard_later );
+		}
 		delete_option('rewrite_rules');
 		$this->wp_rewrite_rules();
 		/**
 		 * Filter whether a "hard" rewrite rule flush should be performed when requested.
 		 *
 		 * A "hard" flush updates .htaccess (Apache) or web.config (IIS).
 		 *
 		 * @since 3.7.0
-		 * @param bool $hard Defaults to true.
+		 *
+		 * @param bool $hard Whether to flush rewrite rules "hard". Default true.
 		 */
-		if ( ! $hard || ! apply_filters( 'flush_rewrite_rules_hard', true ) )
+		if ( ! $hard || ! apply_filters( 'flush_rewrite_rules_hard', true ) ) {
 			return;
+		}
 		if ( function_exists( 'save_mod_rewrite_rules' ) )
 			save_mod_rewrite_rules();
 		if ( function_exists( 'iis7_save_url_rewrite_rules' ) )
 			iis7_save_url_rewrite_rules();
 	}
 	 * '%tag%', or '%author%'.
 	 *
 	 * @since 1.5.0
 	 * @access public
 	 */
-	function init() {
+	public function init() {
 		$this->extra_rules = $this->non_wp_rules = $this->endpoints = array();
 		$this->permalink_structure = get_option('permalink_structure');
 		$this->front = substr($this->permalink_structure, 0, strpos($this->permalink_structure, '%'));
 		$this->root = '';
 		if ( $this->using_index_permalinks() )
 	 * @since 1.5.0
 	 * @access public
 	 *
 	 * @param string $permalink_structure Permalink structure.
 	 */
-	function set_permalink_structure($permalink_structure) {
+	public function set_permalink_structure($permalink_structure) {
 		if ( $permalink_structure != $this->permalink_structure ) {
 			$old_permalink_structure = $this->permalink_structure;
 			update_option('permalink_structure', $permalink_structure);
 			$this->init();
-			do_action('permalink_structure_changed', $old_permalink_structure, $permalink_structure);
+			/**
+			 * Fires after the permalink structure is updated.
+			 *
+			 * @since 2.8.0
+			 *
+			 * @param string $old_permalink_structure The previous permalink structure.
+			 * @param string $permalink_structure     The new permalink structure.
+			 */
+			do_action( 'permalink_structure_changed', $old_permalink_structure, $permalink_structure );
 		}
 	}
 	/**
 	 * Set the category base for the category permalink.
 	 * @since 1.5.0
 	 * @access public
 	 *
 	 * @param string $category_base Category permalink structure base.
 	 */
-	function set_category_base($category_base) {
+	public function set_category_base($category_base) {
 		if ( $category_base != get_option('category_base') ) {
 			update_option('category_base', $category_base);
 			$this->init();
 		}
 	}
 	 * @since 2.3.0
 	 * @access public
 	 *
 	 * @param string $tag_base Tag permalink structure base.
 	 */
-	function set_tag_base( $tag_base ) {
+	public function set_tag_base( $tag_base ) {
 		if ( $tag_base != get_option( 'tag_base') ) {
 			update_option( 'tag_base', $tag_base );
 			$this->init();
 		}
 	}
 	 * Constructor - Calls init(), which runs setup.
 	 *
 	 * @since 1.5.0
 	 * @access public
 	 *
-	 * @return WP_Rewrite
+	 */
-	 */
+	public function __construct() {
-	function __construct() {
 		$this->init();
 	}
 }

changeset 5	5e2f62d02dcd
parent 0	d970ebf37754
child 7	cf61fcea0001