Make WordPress Core

Ticket #7660: 7660.r8904.diff

File 7660.r8904.diff, 15.1 KB (added by jacobsantos, 16 years ago)

Complete inline documentation for rewrite.php based off of r8904

  • rewrite.php

     
    191191}
    192192
    193193/**
    194   * Filter the URL base for taxonomies.
    195   *
    196   * To remove any manually prepended /index.php/.
    197   *
    198   * @access private
    199   * @since unknown (2.3.0?)
    200   * @author Mark Jaquith
    201   *
    202   * @param string $base The taxonomy base that we're going to filter
    203   * @return string
    204   */
     194 * Filter the URL base for taxonomies.
     195 *
     196 * To remove any manually prepended /index.php/.
     197 *
     198 * @access private
     199 * @since 2.6.0
     200 * @author Mark Jaquith
     201 *
     202 * @param string $base The taxonomy base that we're going to filter
     203 * @return string
     204 */
    205205function _wp_filter_taxonomy_base( $base ) {
    206206        if ( !empty( $base ) ) {
    207207                $base = preg_replace( '|^/index\.php/|', '', $base );
     
    481481         *
    482482         * The difference between the root property is that WordPress might be
    483483         * located at example/WordPress/index.php, if permalinks are turned off. The
    484          * index.php will be the front portion. If permalinks are turned on, this
    485          * will most likely be empty or not set.
     484         * WordPress/index.php will be the front portion. If permalinks are turned
     485         * on, this will most likely be empty or not set.
    486486         *
    487487         * @since 1.5.0
    488488         * @access private
     
    512512        var $index = 'index.php';
    513513
    514514        /**
    515          * {@internal Missing Description}}
     515         * Request match string.
    516516         *
    517517         * @since 1.5.0
    518518         * @access private
     
    552552        var $extra_rules_top = array(); //
    553553
    554554        /**
    555          * Rules that don't redirect to WP's index.php
     555         * Rules that don't redirect to WP's index.php.
    556556         *
     557         * These rules are written to the mod_rewrite portion of the .htaccess.
     558         *
    557559         * @since 2.1.0
    558560         * @access private
    559561         * @var array
     
    561563        var $non_wp_rules = array(); //
    562564
    563565        /**
    564          * {@internal Missing Description}}
     566         * Extra permalink structures.
    565567         *
    566568         * @since 2.1.0
    567569         * @access private
     
    579581        var $endpoints;
    580582
    581583        /**
    582          * {@internal Missing Description}}
     584         * Whether to write every mod_rewrite rule for WordPress.
    583585         *
     586         * This is off by default, turning it on might print a lot of rewrite rules
     587         * to the .htaccess file.
     588         *
    584589         * @since 2.0.0
    585590         * @access public
    586591         * @var bool
     
    588593        var $use_verbose_rules = false;
    589594
    590595        /**
    591          * {@internal Missing Description}}
     596         * Whether to write every mod_rewrite rule for WordPress pages.
    592597         *
    593598         * @since 2.5.0
    594599         * @access public
     
    597602        var $use_verbose_page_rules = true;
    598603
    599604        /**
    600          * {@internal Missing Description}}
     605         * Permalink structure search for preg_replace.
    601606         *
    602607         * @since 1.5.0
    603608         * @access private
     
    621626                                        );
    622627
    623628        /**
    624          * {@internal Missing Description}}
     629         * Preg_replace values for the search, see {@link WP_Rewrite::$rewritecode}.
    625630         *
    626631         * @since 1.5.0
    627632         * @access private
     
    645650                                        );
    646651
    647652        /**
    648          * {@internal Missing Description}}
     653         * Search for the query to look for replacing.
    649654         *
    650655         * @since 1.5.0
    651656         * @access private
     
    735740        }
    736741
    737742        /**
    738          * {@internal Missing Short Description}}
     743         * Index for matches for usage in preg_*() functions.
    739744         *
    740          * {@internal Missing Long Description}}
     745         * The format of the string is, with empty matches property value, '$NUM'.
     746         * The 'NUM' will be replaced with the value in the $number parameter. With
     747         * the matches property not empty, the value of the returned string will
     748         * contain that value of the matches property. The format then will be
     749         * '$MATCHES[NUM]', with MATCHES as the value in the property and NUM the
     750         * value of the $number parameter.
    741751         *
    742752         * @since 1.5.0
    743753         * @access public
     
    749759                $match_prefix = '$';
    750760                $match_suffix = '';
    751761
    752                 if (! empty($this->matches)) {
     762                if ( ! empty($this->matches) ) {
    753763                        $match_prefix = '$' . $this->matches . '[';
    754764                        $match_suffix = ']';
    755765                }
     
    758768        }
    759769
    760770        /**
    761          * {@internal Missing Short Description}}
     771         * Retrieve all page and attachments for pages URIs.
    762772         *
    763          * {@internal Missing Long Description}}
     773         * The attachments are for those that have pages as parents and will be
     774         * retrieved.
    764775         *
    765776         * @since 2.5.0
    766777         * @access public
    767778         *
    768          * @return unknown
     779         * @return array Array of page URIs as first element and attachment URIs as second element.
    769780         */
    770781        function page_uri_index() {
    771782                global $wpdb;
     
    781792                if ( !$posts )
    782793                        return array( array(), array() );
    783794
    784 
    785795                foreach ($posts as $id => $post) {
    786796                        // URL => page name
    787797                        $uri = get_page_uri($id);
     
    800810        }
    801811
    802812        /**
    803          * {@internal Missing Short Description}}
     813         * Retrieve all of the rewrite rules for pages.
    804814         *
    805          * {@internal Missing Long Description}}
     815         * If the 'use_verbose_page_rules' property is false, then there will only
     816         * be a single rewrite rule for pages for those matching '%pagename%'. With
     817         * the property set to true, the attachments and the pages will be added for
     818         * each individual attachment URI and page URI, respectively.
    806819         *
    807820         * @since 1.5.0
    808821         * @access public
    809822         *
    810          * @return unknown
     823         * @return array
    811824         */
    812825        function page_rewrite_rules() {
    813826                $rewrite_rules = array();
     
    823836                $uris = $page_uris[0];
    824837                $attachment_uris = $page_uris[1];
    825838
    826 
    827839                if( is_array( $attachment_uris ) ) {
    828840                        foreach ($attachment_uris as $uri => $pagename) {
    829841                                $this->add_rewrite_tag('%pagename%', "($uri)", 'attachment=');
     
    972984        /**
    973985         * Retrieve the permalink structure for categories.
    974986         *
    975          * {@internal Missing Long Description}}
     987         * If the category_base property has no value, then the category structure
     988         * will have the front property value, followed by 'category', and finally
     989         * '%category%'. If it does, then the root property will be used, along with
     990         * the category_base property value.
    976991         *
    977992         * @since 1.5.0
    978993         * @access public
     
    10021017        /**
    10031018         * Retrieve the permalink structure for tags.
    10041019         *
    1005          * {@internal Missing Long Description}}
     1020         * If the tag_base property has no value, then the tag structure will have
     1021         * the front property value, followed by 'tag', and finally '%tag%'. If it
     1022         * does, then the root property will be used, along with the tag_base
     1023         * property value.
    10061024         *
    10071025         * @since 2.3.0
    10081026         * @access public
     
    11801198        }
    11811199
    11821200        /**
    1183          * {@internal Missing Short Description}}
     1201         * Append or update tag, pattern, and query for replacement.
    11841202         *
    1185          * {@internal Missing Long Description}}
     1203         * If the tag already exists, replace the existing pattern and query for
     1204         * that tag, otherwise add the new tag, pattern, and query to the end of the
     1205         * arrays.
    11861206         *
     1207         * @internal What is the purpose of this function again? Need to finish long
     1208         *           description.
     1209         *
    11871210         * @since 1.5.0
    11881211         * @access public
    11891212         *
    1190          * @param unknown_type $tag
    1191          * @param unknown_type $pattern
    1192          * @param unknown_type $query
     1213         * @param string $tag Append tag to rewritecode property array.
     1214         * @param string $pattern Append pattern to rewritereplace property array.
     1215         * @param string $query Append query to queryreplace property array.
    11931216         */
    11941217        function add_rewrite_tag($tag, $pattern, $query) {
    1195                 // If the tag already exists, replace the existing pattern and query for
    1196                 // that tag, otherwise add the new tag, pattern, and query to the end of
    1197                 // the arrays.
    11981218                $position = array_search($tag, $this->rewritecode);
    1199                 if (FALSE !== $position && NULL !== $position) {
     1219                if ( false !== $position && null !== $position ) {
    12001220                        $this->rewritereplace[$position] = $pattern;
    12011221                        $this->queryreplace[$position] = $query;
    12021222                } else {
     
    12091229        /**
    12101230         * Generate the rules from permalink structure.
    12111231         *
    1212          * {@internal Missing Long Description}}
     1232         * The main WP_Rewrite function for building the rewrite rule list. The
     1233         * contents of the function is a mix of black magic and regular expressions,
     1234         * so best just ignore the contents and move to the parameters.
    12131235         *
    1214          * The main WP_Rewrite function.
    1215          *
    12161236         * @since 1.5.0
    12171237         * @access public
    12181238         *
    1219          * @param unknown_type $permalink_structure
    1220          * @param unknown_type $ep_mask
    1221          * @param unknown_type $paged
    1222          * @param unknown_type $feed
    1223          * @param unknown_type $forcomments
    1224          * @param unknown_type $walk_dirs
    1225          * @param unknown_type $endpoints
    1226          * @return unknown
     1239         * @param string $permalink_structure The permalink structure.
     1240         * @param int $ep_mask Optional, default is EP_NONE. Endpoint constant, see EP_* constants.
     1241         * @param bool $paged Optional, default is true. Whether permalink request is paged.
     1242         * @param bool $feed Optional, default is true. Whether for feed.
     1243         * @param bool $forcomments Optional, default is false. Whether for comments.
     1244         * @param bool $walk_dirs Optional, default is true. Whether to create list of directories to walk over.
     1245         * @param bool $endpoints Optional, default is true. Whether endpoints are enabled.
     1246         * @return array Rewrite rule list.
    12271247         */
    12281248        function generate_rewrite_rules($permalink_structure, $ep_mask = EP_NONE, $paged = true, $feed = true, $forcomments = false, $walk_dirs = true, $endpoints = true) {
    12291249                //build a regex to match the feed section of URLs, something like (feed|atom|rss|rss2)/?
     
    14421462        }
    14431463
    14441464        /**
    1445          * {@internal Missing Short Description}}
     1465         * Generate Rewrite rules with permalink structure and walking directory only.
    14461466         *
    1447          * {@internal Missing Long Description}}
     1467         * Shorten version of {@link WP_Rewrite::generate_rewrite_rules()} that
     1468         * allows for shorter list of parameters. See the method for longer
     1469         * description of what generating rewrite rules does.
    14481470         *
     1471         * @uses WP_Rewrite::generate_rewrite_rules() See for long description and rest of parameters.
    14491472         * @since 1.5.0
    14501473         * @access public
    14511474         *
    1452          * @param unknown_type $permalink_structure
    1453          * @param unknown_type $walk_dirs
    1454          * @return unknown
     1475         * @param string $permalink_structure The permalink structure to generate rules.
     1476         * @param bool $walk_dirs Optional, default is false. Whether to create list of directories to walk over.
     1477         * @return array
    14551478         */
    14561479        function generate_rewrite_rule($permalink_structure, $walk_dirs = false) {
    14571480                return $this->generate_rewrite_rules($permalink_structure, EP_NONE, false, false, false, $walk_dirs);
    14581481        }
    14591482
    14601483        /**
    1461          * Construct rewrite matches and queries from permalink structure
     1484         * Construct rewrite matches and queries from permalink structure.
    14621485         *
    1463          * {@internal Missing Long Description}}
     1486         * Runs the action 'generate_rewrite_rules' with the parameter that is an
     1487         * reference to the current WP_Rewrite instance to further manipulate the
     1488         * permalink structures and rewrite rules. Runs the 'rewrite_rules_array'
     1489         * filter on the full rewrite rule array.
    14641490         *
     1491         * There are two ways to manipulate the rewrite rules, one by hooking into
     1492         * the 'generate_rewrite_rules' action and gaining full control of the
     1493         * object or just manipulating the rewrite rule array before it is passed
     1494         * from the function.
     1495         *
    14651496         * @since 1.5.0
    14661497         * @access public
    14671498         *
    1468          * @return array an associate array of matches and queries
     1499         * @return array An associate array of matches and queries.
    14691500         */
    14701501        function rewrite_rules() {
    14711502                $rewrite = array();
     
    15391570        }
    15401571
    15411572        /**
    1542          * {@internal Missing Short Description}}
     1573         * Retrieve the rewrite rules.
    15431574         *
    1544          * {@internal Missing Long Description}}
     1575         * The difference between this method and {@link
     1576         * WP_Rewrite::rewrite_rules()} is that this method stores the rewrite rules
     1577         * in the 'rewrite_rules' option and retrieves it. This prevents having to
     1578         * process all of the permalinks to get the rewrite rules in the form of
     1579         * caching.
    15451580         *
    15461581         * @since 1.5.0
    15471582         * @access public
    15481583         *
    1549          * @return unknown
     1584         * @return array Rewrite rules.
    15501585         */
    15511586        function wp_rewrite_rules() {
    15521587                $this->rules = get_option('rewrite_rules');
     
    15601595        }
    15611596
    15621597        /**
    1563          * {@internal Missing Short Description}}
     1598         * Retrieve mod_rewrite formatted rewrite rules to write to .htaccess.
    15641599         *
    1565          * {@internal Missing Long Description}}
     1600         * Does not actually write to the .htaccess file, but creates the rules for
     1601         * the process that will.
    15661602         *
     1603         * Will add  the non_wp_rules property rules to the .htaccess file before
     1604         * the WordPress rewrite rules one.
     1605         *
    15671606         * @since 1.5.0
    15681607         * @access public
    15691608         *
    1570          * @return unknown
     1609         * @return string
    15711610         */
    15721611        function mod_rewrite_rules() {
    15731612                if ( ! $this->using_permalinks()) {
     
    16371676        }
    16381677
    16391678        /**
    1640          * Add a straight rewrite rule
     1679         * Add a straight rewrite rule.
    16411680         *
    1642          * {@internal Missing Long Description}}
     1681         * Any value in the $after parameter that isn't 'bottom' will be placed at
     1682         * the top of the rules.
    16431683         *
    16441684         * @since 2.1.0
    16451685         * @access public
    16461686         *
    1647          * @param unknown_type $regex
    1648          * @param unknown_type $redirect
    1649          * @param unknown_type $after
     1687         * @param string $regex Regular expression to match against request.
     1688         * @param string $redirect URL regex redirects to when regex matches request.
     1689         * @param string $after Optional, default is bottom. Location to place rule.
    16501690         */
    16511691        function add_rule($regex, $redirect, $after = 'bottom') {
    16521692                //get everything up to the first ?
     
    16641704        }
    16651705
    16661706        /**
    1667          * Add a rule that doesn't redirect to index.php
     1707         * Add a rule that doesn't redirect to index.php.
    16681708         *
    1669          * {@internal Missing Long Description}}
     1709         * Can redirect to any place.
    16701710         *
    16711711         * @since 2.1.0
    16721712         * @access public
    16731713         *
    1674          * @param unknown_type $regex
    1675          * @param unknown_type $redirect
     1714         * @param string $regex Regular expression to match against request.
     1715         * @param string $redirect URL regex redirects to when regex matches request.
    16761716         */
    16771717        function add_external_rule($regex, $redirect) {
    16781718                $this->non_wp_rules[$regex] = $redirect;
    16791719        }
    16801720
    16811721        /**
    1682          * Add an endpoint, like /trackback/
     1722         * Add an endpoint, like /trackback/.
    16831723         *
    1684          * {@internal Missing Long Description}}
     1724         * To be inserted after certain URL types (specified in $places).
    16851725         *
    1686          * To be inserted after certain URL types (specified in $places)
    1687          *
    16881726         * @since 2.1.0
    16891727         * @access public
    16901728         *
    1691          * @param unknown_type $name
    1692          * @param unknown_type $places
     1729         * @param string $name Name of endpoint.
     1730         * @param array $places URL types that endpoint can be used.
    16931731         */
    16941732        function add_endpoint($name, $places) {
    16951733                global $wp;
     
    16981736        }
    16991737
    17001738        /**
    1701          * {@internal Missing Short Description}}
     1739         * Add permalink structure.
    17021740         *
    1703          * {@internal Missing Long Description}}
     1741         * These are added along with the extra rewrite rules that are merged to the
     1742         * top.
    17041743         *
    17051744         * @since unknown
    17061745         * @access public
    17071746         *
    1708          * @param unknown_type $name
    1709          * @param unknown_type $struct
    1710          * @param unknown_type $with_front
     1747         * @param string $name Name for permalink structure.
     1748         * @param string $struct Permalink structure.
     1749         * @param bool $with_front Prepend front base to permalink structure.
    17111750         */
    17121751        function add_permastruct($name, $struct, $with_front = true) {
    17131752                if ( $with_front )
     
    17331772        }
    17341773
    17351774        /**
    1736          * {@internal Missing Short Description}}
     1775         * Sets up the object's properties.
    17371776         *
    1738          * {@internal Missing Long Description}}
     1777         * The 'use_verbose_page_rules' object property will be turned on, if the
     1778         * permalink structure includes the following: '%postname%', '%category%',
     1779         * '%tag%', or '%author%'.
    17391780         *
    17401781         * @since 1.5.0
    17411782         * @access public