From 17010f97c7c8c4e4ffb4f51ca552eb20a313b00c Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Thu, 8 Oct 2015 21:18:25 +0000 Subject: [PATCH] Docs: Add saner formatting and make readability improvements to a variety of inline comments in `WP_Rewrite` and `WP_Rewrite::generate_rewrite_rules()`. See #34218. Built from https://develop.svn.wordpress.org/trunk@34957 git-svn-id: http://core.svn.wordpress.org/trunk@34922 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/class-wp-rewrite.php | 229 +++++++++++++++++++------------ wp-includes/version.php | 2 +- 2 files changed, 142 insertions(+), 89 deletions(-) diff --git a/wp-includes/class-wp-rewrite.php b/wp-includes/class-wp-rewrite.php index c6896a6aaa..bb31514938 100644 --- a/wp-includes/class-wp-rewrite.php +++ b/wp-includes/class-wp-rewrite.php @@ -456,15 +456,15 @@ class WP_Rewrite { public function page_uri_index() { global $wpdb; - //get pages in order of hierarchy, i.e. children after parents + // 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 ); - // If we have no pages get out quick + // If we have no pages get out quick. if ( !$posts ) return array( array(), array() ); - //now reverse it, because we need parents after children for rewrite rules to work properly + // Now reverse it, because we need parents after children for rewrite rules to work properly. $posts = array_reverse($posts, true); $page_uris = array(); @@ -496,7 +496,7 @@ class WP_Rewrite { * @return array Page rewrite rules. */ public function page_rewrite_rules() { - // the extra .? at the beginning prevents clashes with other regular expressions in the rules array + // 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 ); @@ -547,8 +547,10 @@ class WP_Rewrite { if ( empty($date_endian) ) $date_endian = '%year%/%monthnum%/%day%'; - // Do not allow the date tags and %post_id% to overlap in the permalink - // structure. If they do, move the date tags to $front/date/. + /* + * Do not allow the date tags and %post_id% to overlap in the permalink + * structure. If they do, move the date tags to $front/date/. + */ $front = $this->front; preg_match_all('/%.+?%/', $this->permalink_structure, $tokens); $tok_index = 1; @@ -859,37 +861,41 @@ class WP_Rewrite { * @return array Rewrite rule list. */ 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)/? + // 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 is identical but with /feed/ added on as well, so URLs like /feed/atom - //and /atom are both possible + /* + * $feedregex is identical but with /feed/ added on as well, so URLs like /feed/atom + * and /atom are both possible + */ $feedregex = $this->feed_base . '/' . $feedregex2; - //build a regex to match the trackback and page/xx parts of URLs + // Build a regex to match the trackback and page/xx parts of URLs. $trackbackregex = 'trackback/?$'; $pageregex = $this->pagination_base . '/?([0-9]{1,})/?$'; $commentregex = $this->comments_pagination_base . '-([0-9]{1,})/?$'; $embedregex = 'embed/?$'; - //build up an array of endpoint regexes to append => queries to append + // 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 + // 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 + + // This will be appended on to the rest of the query for each dir. $epquery = '&' . $endpoint[2] . '='; $ep_query_append[$epmatch] = array ( $endpoint[0], $epquery ); } } - //get everything up to the first rewrite tag + // Get everything up to the first rewrite tag. $front = substr($permalink_structure, 0, strpos($permalink_structure, '%')); - //build an array of the tags (note that said array ends up being in $tokens[0]) + + // Build an array of the tags (note that said array ends up being in $tokens[0]). preg_match_all('/%.+?%/', $permalink_structure, $tokens); $num_tokens = count($tokens[0]); @@ -899,8 +905,10 @@ class WP_Rewrite { $trackbackindex = $index; $embedindex = $index; - //build a list from the rewritecode and queryreplace arrays, that will look something like - //tagname=$matches[i] where i is the current $i + /* + * 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 ) @@ -912,39 +920,41 @@ class WP_Rewrite { $queries[$i] .= $query_token; } - //get the structure, minus any cruft (stuff that isn't tags) at the front + // Get the structure, minus any cruft (stuff that isn't tags) at the front. $structure = $permalink_structure; if ( $front != '/' ) $structure = str_replace($front, '', $structure); - //create a list of dirs to walk over, making rewrite rules for each level - //so for example, a $structure of /%year%/%monthnum%/%postname% would create - //rewrite rules for /%year%/, /%year%/%monthnum%/ and /%year%/%monthnum%/%postname% + /* + * Create a list of dirs to walk over, making rewrite rules for each level + * so for example, a $structure of /%year%/%monthnum%/%postname% would create + * rewrite rules for /%year%/, /%year%/%monthnum%/ and /%year%/%monthnum%/%postname% + */ $structure = trim($structure, '/'); $dirs = $walk_dirs ? explode('/', $structure) : array( $structure ); $num_dirs = count($dirs); - //strip slashes from the front of $front + // Strip slashes from the front of $front. $front = preg_replace('|^/+|', '', $front); - //the main workhorse loop + // The main workhorse loop. $post_rewrite = array(); $struct = $front; for ( $j = 0; $j < $num_dirs; ++$j ) { - //get the struct for this dir, and trim slashes off the front - $struct .= $dirs[$j] . '/'; //accumulate. see comment near explode('/', $structure) above + // Get the struct for this dir, and trim slashes off the front. + $struct .= $dirs[$j] . '/'; // Accumulate. see comment near explode('/', $structure) above. $struct = ltrim($struct, '/'); - //replace tags with regexes + // Replace tags with regexes. $match = str_replace($this->rewritecode, $this->rewritereplace, $struct); - //make a list of tags, and store how many there are in $num_toks + // 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]' + // Get the 'tagname=$matches[i]'. $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 + // Set up $ep_mask_specific which is used to match more specific URL types. switch ( $dirs[$j] ) { case '%year%': $ep_mask_specific = EP_YEAR; @@ -959,65 +969,74 @@ class WP_Rewrite { $ep_mask_specific = EP_NONE; } - //create query for /page/xx + // Create query for /page/xx. $pagematch = $match . $pageregex; $pagequery = $index . '?' . $query . '&paged=' . $this->preg_index($num_toks + 1); - //create query for /comment-page-xx + // Create query for /comment-page-xx. $commentmatch = $match . $commentregex; $commentquery = $index . '?' . $query . '&cpage=' . $this->preg_index($num_toks + 1); if ( get_option('page_on_front') ) { - //create query for Root /comment-page-xx + // Create query for Root /comment-page-xx. $rootcommentmatch = $match . $commentregex; $rootcommentquery = $index . '?' . $query . '&page_id=' . get_option('page_on_front') . '&cpage=' . $this->preg_index($num_toks + 1); } - //create query for /feed/(feed|atom|rss|rss2|rdf) + // Create query for /feed/(feed|atom|rss|rss2|rdf). $feedmatch = $match . $feedregex; $feedquery = $feedindex . '?' . $query . '&feed=' . $this->preg_index($num_toks + 1); - //create query for /(feed|atom|rss|rss2|rdf) (see comment near creation of $feedregex) + // Create query for /(feed|atom|rss|rss2|rdf) (see comment near creation of $feedregex). $feedmatch2 = $match . $feedregex2; $feedquery2 = $feedindex . '?' . $query . '&feed=' . $this->preg_index($num_toks + 1); - //if asked to, turn the feed queries into comment feed ones + // If asked to, turn the feed queries into comment feed ones. if ( $forcomments ) { $feedquery .= '&withcomments=1'; $feedquery2 .= '&withcomments=1'; } - //start creating the array of rewrites for this dir + // Start creating the array of rewrites for this dir. $rewrite = array(); - if ( $feed ) //...adding on /feed/ regexes => queries - $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/ + // ...adding on /feed/ regexes => queries + if ( $feed ) { + $rewrite = array( $feedmatch => $feedquery, $feedmatch2 => $feedquery2 ); + } + + //...and /page/xx ones + if ( $paged ) { + $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 ) { $rewrite = array_merge($rewrite, array($commentmatch => $commentquery)); } elseif ( EP_ROOT & $ep_mask && get_option('page_on_front') ) { $rewrite = array_merge($rewrite, array($rootcommentmatch => $rootcommentquery)); } - //do endpoints + + // Do endpoints. if ( $endpoints ) { foreach ( (array) $ep_query_append as $regex => $ep) { - //add the endpoints on if the mask fits + // Add the endpoints on if the mask fits. if ( $ep[0] & $ep_mask || $ep[0] & $ep_mask_specific ) $rewrite[$match . $regex] = $index . '?' . $query . $ep[1] . $this->preg_index($num_toks + 2); } } - //if we've got some tags in this dir + // If we've got some tags in this dir. if ( $num_toks ) { $post = false; $page = false; - //check to see if this dir is permalink-level: i.e. the structure specifies an - //individual post. Do this by checking it contains at least one of 1) post name, - //2) post ID, 3) page name, 4) timestamp (year, month, day, hour, second and - //minute all present). Set these flags now as we need them for the endpoints. + /* + * Check to see if this dir is permalink-level: i.e. the structure specifies an + * individual post. Do this by checking it contains at least one of 1) post name, + * 2) post ID, 3) page name, 4) timestamp (year, month, day, hour, second and + * minute all present). Set these flags now as we need them for the endpoints. + */ if ( strpos($struct, '%postname%') !== false || strpos($struct, '%post_id%') !== false || strpos($struct, '%pagename%') !== false @@ -1033,15 +1052,17 @@ class WP_Rewrite { foreach ( get_post_types( array('_builtin' => false ) ) as $ptype ) { if ( strpos($struct, "%$ptype%") !== false ) { $post = true; - $page = is_post_type_hierarchical( $ptype ); // This is for page style attachment url's + + // This is for page style attachment URLs. + $page = is_post_type_hierarchical( $ptype ); break; } } } - //if we're creating rules for a permalink, do all the endpoints like attachments etc + // If creating rules for a permalink, do all the endpoints like attachments etc. if ( $post ) { - //create query and regex for trackback + // Create query and regex for trackback. $trackbackmatch = $match . $trackbackregex; $trackbackquery = $trackbackindex . '?' . $query . '&tb=1'; @@ -1049,37 +1070,59 @@ class WP_Rewrite { $embedmatch = $match . $embedregex; $embedquery = $embedindex . '?' . $query . '&embed=true'; - //trim slashes from the end of the regex for this dir + // Trim slashes from the end of the regex for this dir. $match = rtrim($match, '/'); - //get rid of brackets + // Get rid of brackets. $submatchbase = str_replace( array('(', ')'), '', $match); - //add a rule for at attachments, which take the form of /some-text + // Add a rule for at attachments, which take the form of /some-text. $sub1 = $submatchbase . '/([^/]+)/'; - $sub1tb = $sub1 . $trackbackregex; //add trackback regex /trackback/... - $sub1feed = $sub1 . $feedregex; //and /feed/(atom|...) - $sub1feed2 = $sub1 . $feedregex2; //and /(feed|atom...) - $sub1comment = $sub1 . $commentregex; //and /comment-page-xx - $sub1embed = $sub1 . $embedregex; //and /embed/... - //add another rule to match attachments in the explicit form: - ///attachment/some-text + // Add trackback regex /trackback/... + $sub1tb = $sub1 . $trackbackregex; + + // And /feed/(atom|...) + $sub1feed = $sub1 . $feedregex; + + // And /(feed|atom...) + $sub1feed2 = $sub1 . $feedregex2; + + // And /comment-page-xx + $sub1comment = $sub1 . $commentregex; + + // And /embed/... + $sub1embed = $sub1 . $embedregex; + + /* + * Add another rule to match attachments in the explicit form: + * /attachment/some-text + */ $sub2 = $submatchbase . '/attachment/([^/]+)/'; - $sub2tb = $sub2 . $trackbackregex; //and add trackbacks /attachment/trackback - $sub2feed = $sub2 . $feedregex; //feeds, /attachment/feed/(atom|...) - $sub2feed2 = $sub2 . $feedregex2; //and feeds again on to this /attachment/(feed|atom...) - $sub2comment = $sub2 . $commentregex; //and /comment-page-xx - $sub2embed = $sub2 . $embedregex; //and /embed/... - //create queries for these extra tag-ons we've just dealt with + // And add trackbacks /attachment/trackback. + $sub2tb = $sub2 . $trackbackregex; + + // Feeds, /attachment/feed/(atom|...) + $sub2feed = $sub2 . $feedregex; + + // And feeds again on to this /attachment/(feed|atom...) + $sub2feed2 = $sub2 . $feedregex2; + + // And /comment-page-xx + $sub2comment = $sub2 . $commentregex; + + // And /embed/... + $sub2embed = $sub2 . $embedregex; + + // Create queries for these extra tag-ons we've just dealt with. $subquery = $index . '?attachment=' . $this->preg_index(1); $subtbquery = $subquery . '&tb=1'; $subfeedquery = $subquery . '&feed=' . $this->preg_index(2); $subcommentquery = $subquery . '&cpage=' . $this->preg_index(2); $subembedquery = $subquery . '&embed=true'; - //do endpoints for attachments + // Do endpoints for attachments. if ( !empty($endpoints) ) { foreach ( (array) $ep_query_append as $regex => $ep ) { if ( $ep[0] & EP_ATTACHMENT ) { @@ -1089,39 +1132,47 @@ class WP_Rewrite { } } - //now we've finished with endpoints, finish off the $sub1 and $sub2 matches - //add a ? as we don't have to match that last slash, and finally a $ so we - //match to the end of the URL + /* + * Now we've finished with endpoints, finish off the $sub1 and $sub2 matches + * add a ? as we don't have to match that last slash, and finally a $ so we + * match to the end of the URL + */ $sub1 .= '?$'; $sub2 .= '?$'; - // Post pagination, e.g. /2/ - // Previously: '(/[0-9]+)?/?$', which produced '/2' for page. - // When cast to int, returned 0. + /* + * Post pagination, e.g. /2/ + * Previously: '(/[0-9]+)?/?$', which produced '/2' for page. + * When cast to int, returned 0. + */ $match = $match . '(?:/([0-9]+))?/?$'; $query = $index . '?' . $query . '&page=' . $this->preg_index($num_toks + 1); - } else { //not matching a permalink so this is a lot simpler - //close the match and finalise the query + + // Not matching a permalink so this is a lot simpler. + } else { + // Close the match and finalise the query. $match .= '?$'; $query = $index . '?' . $query; } - //create the final array for this dir by joining the $rewrite array (which currently - //only contains rules/queries for trackback, pages etc) to the main regex/query for - //this dir + /* + * Create the final array for this dir by joining the $rewrite array (which currently + * only contains rules/queries for trackback, pages etc) to the main regex/query for + * this dir + */ $rewrite = array_merge($rewrite, array($match => $query)); - //if we're matching a permalink, add those extras (attachments etc) on + // If we're matching a permalink, add those extras (attachments etc) on. if ( $post ) { - //add trackback + // Add trackback. $rewrite = array_merge(array($trackbackmatch => $trackbackquery), $rewrite); - // add embed + // Add embed. $rewrite = array_merge( array( $embedmatch => $embedquery ), $rewrite ); - //add regexes/queries for attachments, attachment trackbacks and so on + // Add regexes/queries for attachments, attachment trackbacks and so on. if ( ! $page ) { - //require /attachment/stuff form for pages because of confusion with subpages + // Require /attachment/stuff form for pages because of confusion with subpages. $rewrite = array_merge( $rewrite, array( $sub1 => $subquery, $sub1tb => $subtbquery, @@ -1134,11 +1185,13 @@ class WP_Rewrite { $rewrite = array_merge( array( $sub2 => $subquery, $sub2tb => $subtbquery, $sub2feed => $subfeedquery, $sub2feed2 => $subfeedquery, $sub2comment => $subcommentquery, $sub2embed => $subembedquery ), $rewrite ); } - } //if($num_toks) - //add the rules for this dir to the accumulating $post_rewrite + } + // Add the rules for this dir to the accumulating $post_rewrite. $post_rewrite = array_merge($rewrite, $post_rewrite); - } //foreach ($dir) - return $post_rewrite; //the finished rules. phew! + } + + // The finished rules. phew! + return $post_rewrite; } /** diff --git a/wp-includes/version.php b/wp-includes/version.php index 3e873ea653..f37e0c143a 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -4,7 +4,7 @@ * * @global string $wp_version */ -$wp_version = '4.4-alpha-34956'; +$wp_version = '4.4-alpha-34957'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.