WordPress.org
Get WordPress

Make WordPress Core

Changeset 34957


Ignore:
Timestamp:
10/08/2015 09:17:14 PM (9 years ago)
Author:
DrewAPicture
Message:

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.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/class-wp-rewrite.php

    r34955 r34957  
    457457        global $wpdb;
    458458
    459         //get pages in order of hierarchy, i.e. children after parents
     459        // Get pages in order of hierarchy, i.e. children after parents.
    460460        $pages = $wpdb->get_results("SELECT ID, post_name, post_parent FROM $wpdb->posts WHERE post_type = 'page' AND post_status != 'auto-draft'");
    461461        $posts = get_page_hierarchy( $pages );
    462462
    463         // If we have no pages get out quick
     463        // If we have no pages get out quick.
    464464        if ( !$posts )
    465465            return array( array(), array() );
    466466
    467         //now reverse it, because we need parents after children for rewrite rules to work properly
     467        // Now reverse it, because we need parents after children for rewrite rules to work properly.
    468468        $posts = array_reverse($posts, true);
    469469
    … …  
    497497     */
    498498    public function page_rewrite_rules() {
    499         // the extra .? at the beginning prevents clashes with other regular expressions in the rules array
     499        // The extra .? at the beginning prevents clashes with other regular expressions in the rules array.
    500500        $this->add_rewrite_tag( '%pagename%', '(.?.+?)', 'pagename=' );
    501501
    … …  
    548548            $date_endian = '%year%/%monthnum%/%day%';
    549549
    550         // Do not allow the date tags and %post_id% to overlap in the permalink
    551         // structure. If they do, move the date tags to $front/date/.
     550        /*
     551         * Do not allow the date tags and %post_id% to overlap in the permalink
     552         * structure. If they do, move the date tags to $front/date/.
     553         */
    552554        $front = $this->front;
    553555        preg_match_all('/%.+?%/', $this->permalink_structure, $tokens);
    … …  
    860862     */
    861863    public function generate_rewrite_rules($permalink_structure, $ep_mask = EP_NONE, $paged = true, $feed = true, $forcomments = false, $walk_dirs = true, $endpoints = true) {
    862         //build a regex to match the feed section of URLs, something like (feed|atom|rss|rss2)/?
     864        // Build a regex to match the feed section of URLs, something like (feed|atom|rss|rss2)/?
    863865        $feedregex2 = '';
    864866        foreach ( (array) $this->feeds as $feed_name)
    … …  
    866868        $feedregex2 = '(' . trim($feedregex2, '|') . ')/?$';
    867869
    868         //$feedregex is identical but with /feed/ added on as well, so URLs like <permalink>/feed/atom
    869         //and <permalink>/atom are both possible
     870        /*
     871         * $feedregex is identical but with /feed/ added on as well, so URLs like <permalink>/feed/atom
     872         * and <permalink>/atom are both possible
     873         */
    870874        $feedregex = $this->feed_base . '/' . $feedregex2;
    871875
    872         //build a regex to match the trackback and page/xx parts of URLs
     876        // Build a regex to match the trackback and page/xx parts of URLs.
    873877        $trackbackregex = 'trackback/?$';
    874878        $pageregex = $this->pagination_base . '/?([0-9]{1,})/?$';
    … …  
    876880        $embedregex = 'embed/?$';
    877881
    878         //build up an array of endpoint regexes to append => queries to append
     882        // Build up an array of endpoint regexes to append => queries to append.
    879883        if ( $endpoints ) {
    880884            $ep_query_append = array ();
    881885            foreach ( (array) $this->endpoints as $endpoint) {
    882                 //match everything after the endpoint name, but allow for nothing to appear there
     886                // Match everything after the endpoint name, but allow for nothing to appear there.
    883887                $epmatch = $endpoint[1] . '(/(.*))?/?$';
    884                 //this will be appended on to the rest of the query for each dir
     888
     889                // This will be appended on to the rest of the query for each dir.
    885890                $epquery = '&' . $endpoint[2] . '=';
    886891                $ep_query_append[$epmatch] = array ( $endpoint[0], $epquery );
    … …  
    888893        }
    889894
    890         //get everything up to the first rewrite tag
     895        // Get everything up to the first rewrite tag.
    891896        $front = substr($permalink_structure, 0, strpos($permalink_structure, '%'));
    892         //build an array of the tags (note that said array ends up being in $tokens[0])
     897
     898        // Build an array of the tags (note that said array ends up being in $tokens[0]).
    893899        preg_match_all('/%.+?%/', $permalink_structure, $tokens);
    894900
    … …  
    900906        $embedindex = $index;
    901907
    902         //build a list from the rewritecode and queryreplace arrays, that will look something like
    903         //tagname=$matches[i] where i is the current $i
     908        /*
     909         * Build a list from the rewritecode and queryreplace arrays, that will look something
     910         * like tagname=$matches[i] where i is the current $i.
     911         */
    904912        $queries = array();
    905913        for ( $i = 0; $i < $num_tokens; ++$i ) {
    … …  
    913921        }
    914922
    915         //get the structure, minus any cruft (stuff that isn't tags) at the front
     923        // Get the structure, minus any cruft (stuff that isn't tags) at the front.
    916924        $structure = $permalink_structure;
    917925        if ( $front != '/' )
    918926            $structure = str_replace($front, '', $structure);
    919927
    920         //create a list of dirs to walk over, making rewrite rules for each level
    921         //so for example, a $structure of /%year%/%monthnum%/%postname% would create
    922         //rewrite rules for /%year%/, /%year%/%monthnum%/ and /%year%/%monthnum%/%postname%
     928        /*
     929         * Create a list of dirs to walk over, making rewrite rules for each level
     930         * so for example, a $structure of /%year%/%monthnum%/%postname% would create
     931         * rewrite rules for /%year%/, /%year%/%monthnum%/ and /%year%/%monthnum%/%postname%
     932         */
    923933        $structure = trim($structure, '/');
    924934        $dirs = $walk_dirs ? explode('/', $structure) : array( $structure );
    925935        $num_dirs = count($dirs);
    926936
    927         //strip slashes from the front of $front
     937        // Strip slashes from the front of $front.
    928938        $front = preg_replace('|^/+|', '', $front);
    929939
    930         //the main workhorse loop
     940        // The main workhorse loop.
    931941        $post_rewrite = array();
    932942        $struct = $front;
    933943        for ( $j = 0; $j < $num_dirs; ++$j ) {
    934             //get the struct for this dir, and trim slashes off the front
    935             $struct .= $dirs[$j] . '/'; //accumulate. see comment near explode('/', $structure) above
     944            // Get the struct for this dir, and trim slashes off the front.
     945            $struct .= $dirs[$j] . '/'; // Accumulate. see comment near explode('/', $structure) above.
    936946            $struct = ltrim($struct, '/');
    937947
    938             //replace tags with regexes
     948            // Replace tags with regexes.
    939949            $match = str_replace($this->rewritecode, $this->rewritereplace, $struct);
    940950
    941             //make a list of tags, and store how many there are in $num_toks
     951            // Make a list of tags, and store how many there are in $num_toks.
    942952            $num_toks = preg_match_all('/%.+?%/', $struct, $toks);
    943953
    944             //get the 'tagname=$matches[i]'
     954            // Get the 'tagname=$matches[i]'.
    945955            $query = ( ! empty( $num_toks ) && isset( $queries[$num_toks - 1] ) ) ? $queries[$num_toks - 1] : '';
    946956
    947             //set up $ep_mask_specific which is used to match more specific URL types
     957            // Set up $ep_mask_specific which is used to match more specific URL types.
    948958            switch ( $dirs[$j] ) {
    949959                case '%year%':
    … …  
    960970            }
    961971
    962             //create query for /page/xx
     972            // Create query for /page/xx.
    963973            $pagematch = $match . $pageregex;
    964974            $pagequery = $index . '?' . $query . '&paged=' . $this->preg_index($num_toks + 1);
    965975
    966             //create query for /comment-page-xx
     976            // Create query for /comment-page-xx.
    967977            $commentmatch = $match . $commentregex;
    968978            $commentquery = $index . '?' . $query . '&cpage=' . $this->preg_index($num_toks + 1);
    969979
    970980            if ( get_option('page_on_front') ) {
    971                 //create query for Root /comment-page-xx
     981                // Create query for Root /comment-page-xx.
    972982                $rootcommentmatch = $match . $commentregex;
    973983                $rootcommentquery = $index . '?' . $query . '&page_id=' . get_option('page_on_front') . '&cpage=' . $this->preg_index($num_toks + 1);
    974984            }
    975985
    976             //create query for /feed/(feed|atom|rss|rss2|rdf)
     986            // Create query for /feed/(feed|atom|rss|rss2|rdf).
    977987            $feedmatch = $match . $feedregex;
    978988            $feedquery = $feedindex . '?' . $query . '&feed=' . $this->preg_index($num_toks + 1);
    979989
    980             //create query for /(feed|atom|rss|rss2|rdf) (see comment near creation of $feedregex)
     990            // Create query for /(feed|atom|rss|rss2|rdf) (see comment near creation of $feedregex).
    981991            $feedmatch2 = $match . $feedregex2;
    982992            $feedquery2 = $feedindex . '?' . $query . '&feed=' . $this->preg_index($num_toks + 1);
    983993
    984             //if asked to, turn the feed queries into comment feed ones
     994            // If asked to, turn the feed queries into comment feed ones.
    985995            if ( $forcomments ) {
    986996                $feedquery .= '&withcomments=1';
    … …  
    988998            }
    989999
    990             //start creating the array of rewrites for this dir
     1000            // Start creating the array of rewrites for this dir.
    9911001            $rewrite = array();
    992             if ( $feed ) //...adding on /feed/ regexes => queries
    993                 $rewrite = array($feedmatch => $feedquery, $feedmatch2 => $feedquery2);
    994             if ( $paged ) //...and /page/xx ones
    995                 $rewrite = array_merge($rewrite, array($pagematch => $pagequery));
    996 
    997             //only on pages with comments add ../comment-page-xx/
     1002
     1003            // ...adding on /feed/ regexes => queries
     1004            if ( $feed ) {
     1005                $rewrite = array( $feedmatch => $feedquery, $feedmatch2 => $feedquery2 );
     1006            }
     1007
     1008            //...and /page/xx ones
     1009            if ( $paged ) {
     1010                $rewrite = array_merge( $rewrite, array( $pagematch => $pagequery ) );
     1011            }
     1012
     1013            // Only on pages with comments add ../comment-page-xx/.
    9981014            if ( EP_PAGES & $ep_mask || EP_PERMALINK & $ep_mask ) {
    9991015                $rewrite = array_merge($rewrite, array($commentmatch => $commentquery));
    … …  
    10011017                $rewrite = array_merge($rewrite, array($rootcommentmatch => $rootcommentquery));
    10021018            }
    1003             //do endpoints
     1019
     1020            // Do endpoints.
    10041021            if ( $endpoints ) {
    10051022                foreach ( (array) $ep_query_append as $regex => $ep) {
    1006                     //add the endpoints on if the mask fits
     1023                    // Add the endpoints on if the mask fits.
    10071024                    if ( $ep[0] & $ep_mask || $ep[0] & $ep_mask_specific )
    10081025                        $rewrite[$match . $regex] = $index . '?' . $query . $ep[1] . $this->preg_index($num_toks + 2);
    … …  
    10101027            }
    10111028
    1012             //if we've got some tags in this dir
     1029            // If we've got some tags in this dir.
    10131030            if ( $num_toks ) {
    10141031                $post = false;
    10151032                $page = false;
    10161033
    1017                 //check to see if this dir is permalink-level: i.e. the structure specifies an
    1018                 //individual post. Do this by checking it contains at least one of 1) post name,
    1019                 //2) post ID, 3) page name, 4) timestamp (year, month, day, hour, second and
    1020                 //minute all present). Set these flags now as we need them for the endpoints.
     1034                /*
     1035                 * Check to see if this dir is permalink-level: i.e. the structure specifies an
     1036                 * individual post. Do this by checking it contains at least one of 1) post name,
     1037                 * 2) post ID, 3) page name, 4) timestamp (year, month, day, hour, second and
     1038                 * minute all present). Set these flags now as we need them for the endpoints.
     1039                 */
    10211040                if ( strpos($struct, '%postname%') !== false
    10221041                        || strpos($struct, '%post_id%') !== false
    … …  
    10341053                        if ( strpos($struct, "%$ptype%") !== false ) {
    10351054                            $post = true;
    1036                             $page = is_post_type_hierarchical( $ptype ); // This is for page style attachment url's
     1055
     1056                            // This is for page style attachment URLs.
     1057                            $page = is_post_type_hierarchical( $ptype );
    10371058                            break;
    10381059                        }
    … …  
    10401061                }
    10411062
    1042                 //if we're creating rules for a permalink, do all the endpoints like attachments etc
     1063                // If creating rules for a permalink, do all the endpoints like attachments etc.
    10431064                if ( $post ) {
    1044                     //create query and regex for trackback
     1065                    // Create query and regex for trackback.
    10451066                    $trackbackmatch = $match . $trackbackregex;
    10461067                    $trackbackquery = $trackbackindex . '?' . $query . '&tb=1';
    … …  
    10501071                    $embedquery = $embedindex . '?' . $query . '&embed=true';
    10511072
    1052                     //trim slashes from the end of the regex for this dir
     1073                    // Trim slashes from the end of the regex for this dir.
    10531074                    $match = rtrim($match, '/');
    10541075
    1055                     //get rid of brackets
     1076                    // Get rid of brackets.
    10561077                    $submatchbase = str_replace( array('(', ')'), '', $match);
    10571078
    1058                     //add a rule for at attachments, which take the form of <permalink>/some-text
     1079                    // Add a rule for at attachments, which take the form of <permalink>/some-text.
    10591080                    $sub1 = $submatchbase . '/([^/]+)/';
    1060                     $sub1tb = $sub1 . $trackbackregex; //add trackback regex <permalink>/trackback/...
    1061                     $sub1feed = $sub1 . $feedregex; //and <permalink>/feed/(atom|...)
    1062                     $sub1feed2 = $sub1 . $feedregex2; //and <permalink>/(feed|atom...)
    1063                     $sub1comment = $sub1 . $commentregex; //and <permalink>/comment-page-xx
    1064                     $sub1embed = $sub1 . $embedregex; //and <permalink>/embed/...
    1065 
    1066                     //add another rule to match attachments in the explicit form:
    1067                     //<permalink>/attachment/some-text
     1081
     1082                    // Add trackback regex <permalink>/trackback/...
     1083                    $sub1tb = $sub1 . $trackbackregex;
     1084
     1085                    // And <permalink>/feed/(atom|...)
     1086                    $sub1feed = $sub1 . $feedregex;
     1087
     1088                    // And <permalink>/(feed|atom...)
     1089                    $sub1feed2 = $sub1 . $feedregex2;
     1090
     1091                    // And <permalink>/comment-page-xx
     1092                    $sub1comment = $sub1 . $commentregex;
     1093
     1094                    // And <permalink>/embed/...
     1095                    $sub1embed = $sub1 . $embedregex;
     1096
     1097                    /*
     1098                     * Add another rule to match attachments in the explicit form:
     1099                     * <permalink>/attachment/some-text
     1100                     */
    10681101                    $sub2 = $submatchbase . '/attachment/([^/]+)/';
    1069                     $sub2tb = $sub2 . $trackbackregex; //and add trackbacks <permalink>/attachment/trackback
    1070                     $sub2feed = $sub2 . $feedregex;    //feeds, <permalink>/attachment/feed/(atom|...)
    1071                     $sub2feed2 = $sub2 . $feedregex2;  //and feeds again on to this <permalink>/attachment/(feed|atom...)
    1072                     $sub2comment = $sub2 . $commentregex; //and <permalink>/comment-page-xx
    1073                     $sub2embed = $sub2 . $embedregex; //and <permalink>/embed/...
    1074 
    1075                     //create queries for these extra tag-ons we've just dealt with
     1102
     1103                    // And add trackbacks <permalink>/attachment/trackback.
     1104                    $sub2tb = $sub2 . $trackbackregex;
     1105
     1106                    // Feeds, <permalink>/attachment/feed/(atom|...)
     1107                    $sub2feed = $sub2 . $feedregex;
     1108
     1109                    // And feeds again on to this <permalink>/attachment/(feed|atom...)
     1110                    $sub2feed2 = $sub2 . $feedregex2;
     1111
     1112                    // And <permalink>/comment-page-xx
     1113                    $sub2comment = $sub2 . $commentregex;
     1114
     1115                    // And <permalink>/embed/...
     1116                    $sub2embed = $sub2 . $embedregex;
     1117
     1118                    // Create queries for these extra tag-ons we've just dealt with.
    10761119                    $subquery = $index . '?attachment=' . $this->preg_index(1);
    10771120                    $subtbquery = $subquery . '&tb=1';
    … …  
    10801123                    $subembedquery = $subquery . '&embed=true';
    10811124
    1082                     //do endpoints for attachments
     1125                    // Do endpoints for attachments.
    10831126                    if ( !empty($endpoints) ) {
    10841127                        foreach ( (array) $ep_query_append as $regex => $ep ) {
    … …  
    10901133                    }
    10911134
    1092                     //now we've finished with endpoints, finish off the $sub1 and $sub2 matches
    1093                     //add a ? as we don't have to match that last slash, and finally a $ so we
    1094                     //match to the end of the URL
     1135                    /*
     1136                     * Now we've finished with endpoints, finish off the $sub1 and $sub2 matches
     1137                     * add a ? as we don't have to match that last slash, and finally a $ so we
     1138                     * match to the end of the URL
     1139                     */
    10951140                    $sub1 .= '?$';
    10961141                    $sub2 .= '?$';
    10971142
    1098                     // Post pagination, e.g. <permalink>/2/
    1099                     // Previously: '(/[0-9]+)?/?$', which produced '/2' for page.
    1100                     // When cast to int, returned 0.
     1143                    /*
     1144                     * Post pagination, e.g. <permalink>/2/
     1145                     * Previously: '(/[0-9]+)?/?$', which produced '/2' for page.
     1146                     * When cast to int, returned 0.
     1147                     */
    11011148                    $match = $match . '(?:/([0-9]+))?/?$';
    11021149                    $query = $index . '?' . $query . '&page=' . $this->preg_index($num_toks + 1);
    1103                 } else { //not matching a permalink so this is a lot simpler
    1104                     //close the match and finalise the query
     1150
     1151                // Not matching a permalink so this is a lot simpler.
     1152                } else {
     1153                    // Close the match and finalise the query.
    11051154                    $match .= '?$';
    11061155                    $query = $index . '?' . $query;
    11071156                }
    11081157
    1109                 //create the final array for this dir by joining the $rewrite array (which currently
    1110                 //only contains rules/queries for trackback, pages etc) to the main regex/query for
    1111                 //this dir
     1158                /*
     1159                 * Create the final array for this dir by joining the $rewrite array (which currently
     1160                 * only contains rules/queries for trackback, pages etc) to the main regex/query for
     1161                 * this dir
     1162                 */
    11121163                $rewrite = array_merge($rewrite, array($match => $query));
    11131164
    1114                 //if we're matching a permalink, add those extras (attachments etc) on
     1165                // If we're matching a permalink, add those extras (attachments etc) on.
    11151166                if ( $post ) {
    1116                     //add trackback
     1167                    // Add trackback.
    11171168                    $rewrite = array_merge(array($trackbackmatch => $trackbackquery), $rewrite);
    11181169
    1119                     // add embed
     1170                    // Add embed.
    11201171                    $rewrite = array_merge( array( $embedmatch => $embedquery ), $rewrite );
    11211172
    1122                     //add regexes/queries for attachments, attachment trackbacks and so on
     1173                    // Add regexes/queries for attachments, attachment trackbacks and so on.
    11231174                    if ( ! $page ) {
    1124                         //require <permalink>/attachment/stuff form for pages because of confusion with subpages
     1175                        // Require <permalink>/attachment/stuff form for pages because of confusion with subpages.
    11251176                        $rewrite = array_merge( $rewrite, array(
    11261177                            $sub1        => $subquery,
    … …  
    11351186                    $rewrite = array_merge( array( $sub2 => $subquery, $sub2tb => $subtbquery, $sub2feed => $subfeedquery, $sub2feed2 => $subfeedquery, $sub2comment => $subcommentquery, $sub2embed => $subembedquery ), $rewrite );
    11361187                }
    1137             } //if($num_toks)
    1138             //add the rules for this dir to the accumulating $post_rewrite
     1188            }
     1189            // Add the rules for this dir to the accumulating $post_rewrite.
    11391190            $post_rewrite = array_merge($rewrite, $post_rewrite);
    1140         } //foreach ($dir)
    1141         return $post_rewrite; //the finished rules. phew!
     1191        }
     1192
     1193        // The finished rules. phew!
     1194        return $post_rewrite;
    11421195    }
    11431196
Note: See TracChangeset for help on using the changeset viewer.