WordPress.org

Make WordPress Core

Changeset 19752


Ignore:
Timestamp:
01/25/2012 09:44:02 PM (8 years ago)
Author:
duck_
Message:

Improve documentation of WP_Rewrite. Fixes #19897.

In particular WP_Rewrite::$front, WP_Rewrite::$root, WP_Rewrite::$use_verbose_page_rules and WP_Rewrite::generate_rewrite_rules(). As well as some code indentation prettification.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/rewrite.php

    r19743 r19752  
    373373class WP_Rewrite {
    374374    /**
    375      * Default permalink structure for WordPress.
     375     * Permalink structure for posts.
    376376     *
    377377     * @since 1.5.0
     
    391391
    392392    /**
    393      * Permalink author request base ( example.com/author/authorname ).
     393     * Base for the author permalink structure (example.com/$author_base/authorname).
    394394     *
    395395     * @since 1.5.0
     
    400400
    401401    /**
    402      * Permalink request structure for author pages.
     402     * Permalink structure for author archives.
    403403     *
    404404     * @since 1.5.0
     
    409409
    410410    /**
    411      * Permalink request structure for dates.
     411     * Permalink structure for date archives.
    412412     *
    413413     * @since 1.5.0
     
    418418
    419419    /**
    420      * Permalink request structure for pages.
     420     * Permalink structure for pages.
    421421     *
    422422     * @since 1.5.0
     
    427427
    428428    /**
    429      * Search permalink base ( example.com/search/query ).
     429     * Base of the search permalink structure (example.com/$search_base/query).
    430430     *
    431431     * @since 1.5.0
     
    436436
    437437    /**
    438      * Permalink request structure for searches.
     438     * Permalink structure for searches.
    439439     *
    440440     * @since 1.5.0
     
    472472
    473473    /**
    474      * Comments feed request structure permalink.
     474     * Comments feed permalink structure.
    475475     *
    476476     * @since 1.5.0
     
    481481
    482482    /**
    483      * Feed request structure permalink.
     483     * Feed request permalink structure.
    484484     *
    485485     * @since 1.5.0
     
    490490
    491491    /**
    492      * Front URL path.
    493      *
    494      * The difference between the root property is that WordPress might be
    495      * located at example/WordPress/index.php, if permalinks are turned off. The
    496      * WordPress/index.php will be the front portion. If permalinks are turned
    497      * on, this will most likely be empty or not set.
    498      *
     492     * The static portion of the post permalink structure.
     493     *
     494     * If the permalink structure is "/archive/%post_id%" then the front
     495     * is "/archive/". If the permalink structure is "/%year%/%postname%/"
     496     * then the front is "/".
     497     *
     498     * @see WP_Rewrite::init()
    499499     * @since 1.5.0
    500500     * @access private
     
    504504
    505505    /**
    506      * Root URL path to WordPress (without domain).
    507      *
    508      * The difference between front property is that WordPress might be located
    509      * at example.com/WordPress/. The root is the 'WordPress/' portion.
    510      *
     506     * The prefix for all permalink structures.
     507     *
     508     * If PATHINFO/index permalinks are in use then the root is the value of
     509     * {@link WP_Rewrite::$index} with a trailing slash appended. Otherwise
     510     * the root will be empty.
     511     *
     512     * @see WP_Rewrite::init()
     513     * @see WP_Rewrite::using_index_permalinks()
    511514     * @since 1.5.0
    512515     * @access private
     
    516519
    517520    /**
    518      * Permalink to the home page.
     521     * The name of the index file which is the entry point to all requests.
    519522     *
    520523     * @since 1.5.0
     
    525528
    526529    /**
    527      * Request match string.
     530     * Variable name to use for regex matches in the rewritten query.
    528531     *
    529532     * @since 1.5.0
     
    551554     * @var array
    552555     */
    553     var $extra_rules = array(); //
     556    var $extra_rules = array();
    554557
    555558    /**
     
    562565     * @var array
    563566     */
    564     var $extra_rules_top = array(); //
    565 
    566     /**
    567      * Rules that don't redirect to WP's index.php.
    568      *
    569      * These rules are written to the mod_rewrite portion of the .htaccess.
     567    var $extra_rules_top = array();
     568
     569    /**
     570     * Rules that don't redirect to WordPress' index.php.
     571     *
     572     * These rules are written to the mod_rewrite portion of the .htaccess,
     573     * and are added by {@link add_external_rule()}.
    570574     *
    571575     * @since 2.1.0
     
    573577     * @var array
    574578     */
    575     var $non_wp_rules = array(); //
    576 
    577     /**
    578      * Extra permalink structures.
     579    var $non_wp_rules = array();
     580
     581    /**
     582     * Extra permalink structures, e.g. categories, added by {@link add_permastruct()}.
    579583     *
    580584     * @since 2.1.0
     
    585589
    586590    /**
    587      * Endpoints permalinks
     591     * Endpoints (like /trackback/) added by {@link add_rewrite_endpoint()}.
    588592     *
    589593     * @since 2.1.0
     
    594598
    595599    /**
    596      * Whether to write every mod_rewrite rule for WordPress.
     600     * Whether to write every mod_rewrite rule for WordPress into the .htaccess file.
    597601     *
    598602     * This is off by default, turning it on might print a lot of rewrite rules
    599603     * to the .htaccess file.
    600604     *
     605     * @see WP_Rewrite::mod_rewrite_rules()
    601606     * @since 2.0.0
    602607     * @access public
     
    606611
    607612    /**
    608      * Whether to write every mod_rewrite rule for WordPress pages.
    609      *
     613     * Could post permalinks be confused with those of pages?
     614     *
     615     * If the first rewrite tag in the post permalink structure is one that could
     616     * also match a page name (e.g. %postname% or %author%) then this flag is
     617     * set to true. Prior to WordPress 3.3 this flag indicated that every page
     618     * would have a set of rules added to the top of the rewrite rules array.
     619     * Now it tells {@link WP::parse_request()} to check if a URL matching the
     620     * page permastruct is actually a page before accepting it.
     621     *
     622     * @link http://core.trac.wordpress.org/ticket/16687
     623     * @see WP_Rewrite::init()
    610624     * @since 2.5.0
    611625     * @access public
     
    615629
    616630    /**
    617      * Permalink structure search for preg_replace.
     631     * Rewrite tags that can be used in permalink structures.
     632     *
     633     * These are translated into the regular expressions stored in
     634     * {@link WP_Rewrite::$rewritereplace} and are rewritten to the
     635     * query variables listed in {@link WP_Rewrite::$queryreplace}.
     636     *
     637     * Additional tags can be added with {@link add_rewrite_tag()}.
    618638     *
    619639     * @since 1.5.0
     
    621641     * @var array
    622642     */
    623     var $rewritecode =
    624         array(
    625                     '%year%',
    626                     '%monthnum%',
    627                     '%day%',
    628                     '%hour%',
    629                     '%minute%',
    630                     '%second%',
    631                     '%postname%',
    632                     '%post_id%',
    633                     '%author%',
    634                     '%pagename%',
    635                     '%search%'
    636                     );
    637 
    638     /**
    639      * Preg_replace values for the search, see {@link WP_Rewrite::$rewritecode}.
     643    var $rewritecode = array(
     644        '%year%',
     645        '%monthnum%',
     646        '%day%',
     647        '%hour%',
     648        '%minute%',
     649        '%second%',
     650        '%postname%',
     651        '%post_id%',
     652        '%author%',
     653        '%pagename%',
     654        '%search%'
     655    );
     656
     657    /**
     658     * Regular expressions to be substituted into rewrite rules in place
     659     * of rewrite tags, see {@link WP_Rewrite::$rewritecode}.
    640660     *
    641661     * @since 1.5.0
     
    643663     * @var array
    644664     */
    645     var $rewritereplace =
    646         array(
    647                     '([0-9]{4})',
    648                     '([0-9]{1,2})',
    649                     '([0-9]{1,2})',
    650                     '([0-9]{1,2})',
    651                     '([0-9]{1,2})',
    652                     '([0-9]{1,2})',
    653                     '([^/]+)',
    654                     '([0-9]+)',
    655                     '([^/]+)',
    656                     '([^/]+?)',
    657                     '(.+)'
    658                     );
    659 
    660     /**
    661      * Search for the query to look for replacing.
     665    var $rewritereplace = array(
     666        '([0-9]{4})',
     667        '([0-9]{1,2})',
     668        '([0-9]{1,2})',
     669        '([0-9]{1,2})',
     670        '([0-9]{1,2})',
     671        '([0-9]{1,2})',
     672        '([^/]+)',
     673        '([0-9]+)',
     674        '([^/]+)',
     675        '([^/]+?)',
     676        '(.+)'
     677    );
     678
     679    /**
     680     * Query variables that rewrite tags map to, see {@link WP_Rewrite::$rewritecode}.
    662681     *
    663682     * @since 1.5.0
     
    665684     * @var array
    666685     */
    667     var $queryreplace =
    668         array (
    669                     'year=',
    670                     'monthnum=',
    671                     'day=',
    672                     'hour=',
    673                     'minute=',
    674                     'second=',
    675                     'name=',
    676                     'p=',
    677                     'author_name=',
    678                     'pagename=',
    679                     's='
    680                     );
     686    var $queryreplace = array(
     687        'year=',
     688        'monthnum=',
     689        'day=',
     690        'hour=',
     691        'minute=',
     692        'second=',
     693        'name=',
     694        'p=',
     695        'author_name=',
     696        'pagename=',
     697        's='
     698    );
    681699
    682700    /**
     
    687705     * @var array
    688706     */
    689     var $feeds = array ( 'feed', 'rdf', 'rss', 'rss2', 'atom' );
     707    var $feeds = array( 'feed', 'rdf', 'rss', 'rss2', 'atom' );
    690708
    691709    /**
     
    903921     */
    904922    function get_year_permastruct() {
    905         $structure = $this->get_date_permastruct($this->permalink_structure);
     923        $structure = $this->get_date_permastruct();
    906924
    907925        if ( empty($structure) )
     
    928946     */
    929947    function get_month_permastruct() {
    930         $structure = $this->get_date_permastruct($this->permalink_structure);
     948        $structure = $this->get_date_permastruct();
    931949
    932950        if ( empty($structure) )
     
    951969     */
    952970    function get_day_permastruct() {
    953         return $this->get_date_permastruct($this->permalink_structure);
     971        return $this->get_date_permastruct();
    954972    }
    955973
     
    11671185
    11681186    /**
    1169      * Generate the rules from permalink structure.
     1187     * Generate rewrite rules from a permalink structure.
    11701188     *
    11711189     * The main WP_Rewrite function for building the rewrite rule list. The
     
    11771195     *
    11781196     * @param string $permalink_structure The permalink structure.
    1179      * @param int $ep_mask Optional, default is EP_NONE. Endpoint constant, see EP_* constants.
    1180      * @param bool $paged Optional, default is true. Whether permalink request is paged.
    1181      * @param bool $feed Optional, default is true. Whether for feed.
    1182      * @param bool $forcomments Optional, default is false. Whether for comments.
    1183      * @param bool $walk_dirs Optional, default is true. Whether to create list of directories to walk over.
    1184      * @param bool $endpoints Optional, default is true. Whether endpoints are enabled.
     1197     * @param int $ep_mask Endpoint mask defining what endpoints are added to the structure. Default is EP_NONE.
     1198     * @param bool $paged Should archive pagination rules be added for the structure? Default is true.
     1199     * @param bool $feed Should feed rewrite rules be added for the structure? Default is true.
     1200     * @param bool $forcomments Should the feed rules be a query for a comments feed? Default is false.
     1201     * @param bool $walk_dirs Should the 'directories' making up the structure be walked over and rewrite rules
     1202     *                        built for each in turn? Default is true.
     1203     * @param bool $endpoints Should endpoints be applied to the generated rewrite rules? Default is true.
    11851204     * @return array Rewrite rule list.
    11861205     */
     
    12411260
    12421261        //create a list of dirs to walk over, making rewrite rules for each level
    1243         //so for example, a $structure of /%year%/%month%/%postname% would create
    1244         //rewrite rules for /%year%/, /%year%/%month%/ and /%year%/%month%/%postname%
     1262        //so for example, a $structure of /%year%/%monthnum%/%postname% would create
     1263        //rewrite rules for /%year%/, /%year%/%monthnum%/ and /%year%/%monthnum%/%postname%
    12451264        $structure = trim($structure, '/');
    12461265        $dirs = $walk_dirs ? explode('/', $structure) : array( $structure );
     
    13781397                    $sub1feed2 = $sub1 . $feedregex2; //and <permalink>/(feed|atom...)
    13791398                    $sub1comment = $sub1 . $commentregex; //and <permalink>/comment-page-xx
    1380                     //add an ? as we don't have to match that last slash, and finally a $ so we
    1381                     //match to the end of the URL
    13821399
    13831400                    //add another rule to match attachments in the explicit form:
     
    14061423
    14071424                    //now we've finished with endpoints, finish off the $sub1 and $sub2 matches
     1425                    //add a ? as we don't have to match that last slash, and finally a $ so we
     1426                    //match to the end of the URL
    14081427                    $sub1 .= '?$';
    14091428                    $sub2 .= '?$';
    14101429
    1411                     //allow URLs like <permalink>/2 for <permalink>/page/2
     1430                    //post pagination, e.g. <permalink>/2/
    14121431                    $match = $match . '(/[0-9]+)?/?$';
    14131432                    $query = $index . '?' . $query . '&page=' . $this->preg_index($num_toks + 1);
     
    15871606     * the process that will.
    15881607     *
    1589      * Will add  the non_wp_rules property rules to the .htaccess file before
     1608     * Will add the non_wp_rules property rules to the .htaccess file before
    15901609     * the WordPress rewrite rules one.
    15911610     *
Note: See TracChangeset for help on using the changeset viewer.