WordPress.org

Make WordPress Core

Ticket #26095: rewrite.php.diff

File rewrite.php.diff, 11.1 KB (added by mboynes, 8 years ago)

Adding inline docs for hooks in wp-includes/rewrite.php

  • wp-includes/rewrite.php

     
    288288function url_to_postid($url) {
    289289        global $wp_rewrite;
    290290
    291         $url = apply_filters('url_to_postid', $url);
     291        /**
     292         * Filter the URL prior to using it to find the post ID.
     293         *
     294         * This filter fires before the URL is used to find the post ID.
     295         * If a hook returns a "default permalink" URL, the ID in the URL
     296         * will be returned by the parent function. For instance, returning
     297         * '/?p=12345' means that the function will return 12345.
     298         *
     299         * @since 2.2.0
     300         *
     301         * @param string $url The URL which will be searched.
     302         */
     303        $url = apply_filters( 'url_to_postid', $url );
    292304
    293305        // First, check to see if there is a 'p=N' or 'page_id=N' to match against
    294306        if ( preg_match('#[?&](p|page_id|attachment_id)=(\d+)#', $url, $values) )       {
     
    15601572
    15611573                // Post
    15621574                $post_rewrite = $this->generate_rewrite_rules( $this->permalink_structure, EP_PERMALINK );
    1563                 $post_rewrite = apply_filters('post_rewrite_rules', $post_rewrite);
     1575                /**
     1576                 * Filters the "post" post type rewrite rules before they're added to the rewrite rules array.
     1577                 *
     1578                 * This array should include all rewrite rules that were generated for accessing the
     1579                 * "post" post types paths, archive paths, etc. This does not include date-based paths.
     1580                 *
     1581                 * @since 1.5.0
     1582                 *
     1583                 * @param array $post_rewrite The rewrite rules for the "post" post type.
     1584                 */
     1585                $post_rewrite = apply_filters( 'post_rewrite_rules', $post_rewrite );
    15641586
    15651587                // Date
    1566                 $date_rewrite = $this->generate_rewrite_rules($this->get_date_permastruct(), EP_DATE);
    1567                 $date_rewrite = apply_filters('date_rewrite_rules', $date_rewrite);
     1588                $date_rewrite = $this->generate_rewrite_rules( $this->get_date_permastruct(), EP_DATE );
     1589                /**
     1590                 * Filters the date-based rewrite rules before they're added to the rewrite rules array.
     1591                 *
     1592                 * This array should include all rewrite rules that were generated for listing posts
     1593                 * by date, e.g. /yyyy/, /yyyy/mm/, and /yyyy/mm/dd/.
     1594                 *
     1595                 * @since 1.5.0
     1596                 *
     1597                 * @param array $date_rewrite The rewrite rules for date archives.
     1598                 */
     1599                $date_rewrite = apply_filters( 'date_rewrite_rules', $date_rewrite );
    15681600
    15691601                // Root
    1570                 $root_rewrite = $this->generate_rewrite_rules($this->root . '/', EP_ROOT);
    1571                 $root_rewrite = apply_filters('root_rewrite_rules', $root_rewrite);
     1602                $root_rewrite = $this->generate_rewrite_rules( $this->root . '/', EP_ROOT );
     1603                /**
     1604                 * Filters the root-level rewrite rules before they're added to the rewrite rules array.
     1605                 *
     1606                 * The root-level rewrite rules include pagination rules for the homepage as well as
     1607                 * site-wide post feeds (e.g. /feed/ and /feed/atom/).
     1608                 *
     1609                 * @since 1.5.0
     1610                 *
     1611                 * @param array $root_rewrite The root-level rewrite rules.
     1612                 */
     1613                $root_rewrite = apply_filters( 'root_rewrite_rules', $root_rewrite );
    15721614
    15731615                // Comments
    1574                 $comments_rewrite = $this->generate_rewrite_rules($this->root . $this->comments_base, EP_COMMENTS, false, true, true, false);
    1575                 $comments_rewrite = apply_filters('comments_rewrite_rules', $comments_rewrite);
     1616                $comments_rewrite = $this->generate_rewrite_rules( $this->root . $this->comments_base, EP_COMMENTS, false, true, true, false );
     1617                /**
     1618                 * Filters the comments feed rewrite rules before they're added to the rewrite rules array.
     1619                 *
     1620                 * The comments rewrite rules include the paths for accessing the comments feeds,
     1621                 * for instance /comments/feed/ and /comments/feed/atom/.
     1622                 *
     1623                 * @since 1.5.0
     1624                 *
     1625                 * @param array $comments_rewrite The rewrite rules for the site-wide comments feeds.
     1626                 */
     1627                $comments_rewrite = apply_filters( 'comments_rewrite_rules', $comments_rewrite );
    15761628
    15771629                // Search
    15781630                $search_structure = $this->get_search_permastruct();
    1579                 $search_rewrite = $this->generate_rewrite_rules($search_structure, EP_SEARCH);
    1580                 $search_rewrite = apply_filters('search_rewrite_rules', $search_rewrite);
     1631                $search_rewrite = $this->generate_rewrite_rules( $search_structure, EP_SEARCH );
     1632                /**
     1633                 * Filters the search rewrite rules before they're added to the rewrite rules array.
     1634                 *
     1635                 * The search-related rewrite rules include /search/some+search+query/ as well as
     1636                 * pagination and feed paths for a search.
     1637                 *
     1638                 * @since 1.5.0
     1639                 *
     1640                 * @param array $search_rewrite The rewrite rules for search queries.
     1641                 */
     1642                $search_rewrite = apply_filters( 'search_rewrite_rules', $search_rewrite );
    15811643
    15821644                // Authors
    1583                 $author_rewrite = $this->generate_rewrite_rules($this->get_author_permastruct(), EP_AUTHORS);
    1584                 $author_rewrite = apply_filters('author_rewrite_rules', $author_rewrite);
     1645                $author_rewrite = $this->generate_rewrite_rules( $this->get_author_permastruct(), EP_AUTHORS );
     1646                /**
     1647                 * Filters the author rewrite rules before they're added to the rewrite rules array.
     1648                 *
     1649                 * The author rewrite rules include /author/author-name/ as well as pagination and
     1650                 * feed paths for author archives.
     1651                 *
     1652                 * @since 1.5.0
     1653                 *
     1654                 * @param array $author_rewrite The rewrite rules for author archives.
     1655                 */
     1656                $author_rewrite = apply_filters( 'author_rewrite_rules', $author_rewrite );
    15851657
    15861658                // Pages
    15871659                $page_rewrite = $this->page_rewrite_rules();
    1588                 $page_rewrite = apply_filters('page_rewrite_rules', $page_rewrite);
     1660                /**
     1661                 * Filters the "page" post type rewrite rules before they're added to the rewrite rules array.
     1662                 *
     1663                 * @since 1.5.0
     1664                 *
     1665                 * @param array $page_rewrite The rewrite rules for the "page" post type.
     1666                 */
     1667                $page_rewrite = apply_filters( 'page_rewrite_rules', $page_rewrite );
    15891668
    15901669                // Extra permastructs
    15911670                foreach ( $this->extra_permastructs as $permastructname => $struct ) {
     
    15981677                                $rules = $this->generate_rewrite_rules( $struct );
    15991678                        }
    16001679
    1601                         $rules = apply_filters($permastructname . '_rewrite_rules', $rules);
    1602                         if ( 'post_tag' == $permastructname )
    1603                                 $rules = apply_filters('tag_rewrite_rules', $rules);
     1680                        /**
     1681                         * Filters the rewrite rules for individual extra permalink structures.
     1682                         *
     1683                         * Extra permalink structures are typically added via add_permastruct() (used
     1684                         * by both register_post_type and register_taxonomy). For instance, the
     1685                         * 'category' taxonomy adds the 'category' permastruct, and this will apply
     1686                         * the filter 'category_rewrite_rules' to the generated rewrite rules.
     1687                         *
     1688                         * @since 3.1.0
     1689                         *
     1690                         * @param array $rules The rewrite rules generated for the current permastruct.
     1691                         */
     1692                        $rules = apply_filters( $permastructname . '_rewrite_rules', $rules );
     1693                        if ( 'post_tag' == $permastructname ) {
     1694                                /**
     1695                                 * Filter the generated rewrite rules for tags.
     1696                                 *
     1697                                 * This filter exists for backwards compatibility. The permastruct for
     1698                                 * tags is "post_tag", so the generated rules can also be filtered via
     1699                                 * post_tag_rewrite_rules.
     1700                                 *
     1701                                 * @since 2.3.0
     1702                                 *
     1703                                 * @param array $rules The rewrite rules generated for tags.
     1704                                 */
     1705                                $rules = apply_filters( 'tag_rewrite_rules', $rules );
     1706                        }
    16041707
    1605                         $this->extra_rules_top = array_merge($this->extra_rules_top, $rules);
     1708                        $this->extra_rules_top = array_merge( $this->extra_rules_top, $rules );
    16061709                }
    16071710
    16081711                // Put them together.
    16091712                if ( $this->use_verbose_page_rules )
    1610                         $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);
     1713                        $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 );
    16111714                else
    1612                         $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);
     1715                        $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 );
    16131716
    1614                 do_action_ref_array('generate_rewrite_rules', array(&$this));
    1615                 $this->rules = apply_filters('rewrite_rules_array', $this->rules);
    16161717
     1718                /**
     1719                 * Fires after the rewrite rules are generated.
     1720                 *
     1721                 * @since 1.5.0
     1722                 *
     1723                 * @param WP_Rewrite $this Current WP_Rewrite instance, passed by reference.
     1724                 */
     1725                do_action_ref_array( 'generate_rewrite_rules', array( &$this ) );
     1726
     1727                /**
     1728                 * Filter the full set of generated rewrite rules.
     1729                 *
     1730                 * @since 1.5.0
     1731                 *
     1732                 * @param array $this->rules The compiled array of rewrite rules.
     1733                 */
     1734                $this->rules = apply_filters( 'rewrite_rules_array', $this->rules );
     1735
    16171736                return $this->rules;
    16181737        }
    16191738
     
    17201839
    17211840                $rules .= "</IfModule>\n";
    17221841
    1723                 $rules = apply_filters('mod_rewrite_rules', $rules);
    1724                 $rules = apply_filters('rewrite_rules', $rules);  // Deprecated
     1842                /**
     1843                 * Filter the mod_rewrite formatted .htaccess rewrite rules.
     1844                 *
     1845                 * @since 1.5.0
     1846                 *
     1847                 * @param string $rules mod_rewrite formatted rewrite rules for a .htaccess file.
     1848                 */
     1849                $rules = apply_filters( 'mod_rewrite_rules', $rules );
    17251850
     1851                /**
     1852                 * Filter the mod_rewrite formatted .htaccess rewrite rules.
     1853                 *
     1854                 * @since 1.5.0
     1855                 * @deprecated 1.5.0 Use the mod_rewrite_rules filter instead.
     1856                 *
     1857                 * @param string $rules mod_rewrite formatted rewrite rules for a .htaccess file.
     1858                 */
     1859                $rules = apply_filters( 'rewrite_rules', $rules );  // Deprecated
     1860
    17261861                return $rules;
    17271862        }
    17281863
     
    17671902</configuration>';
    17681903                }
    17691904
    1770                 $rules = apply_filters('iis7_url_rewrite_rules', $rules);
     1905                /**
     1906                 * Filter the IIS7 URL Rewrite formatted rewrite rules for a web.config file.
     1907                 *
     1908                 * @since 2.8.0
     1909                 *
     1910                 * @param string $rules IIS7 URL Rewrite formatted rewrite rules.
     1911                 */
     1912                $rules = apply_filters( 'iis7_url_rewrite_rules', $rules );
    17711913
    17721914                return $rules;
    17731915        }
     
    19102052                 * A "hard" flush updates .htaccess (Apache) or web.config (IIS).
    19112053                 *
    19122054                 * @since 3.7.0
     2055                 *
    19132056                 * @param bool $hard Defaults to true.
    19142057                 */
    19152058                if ( ! $hard || ! apply_filters( 'flush_rewrite_rules_hard', true ) )
     
    19672110         *
    19682111         * @param string $permalink_structure Permalink structure.
    19692112         */
    1970         function set_permalink_structure($permalink_structure) {
     2113        function set_permalink_structure( $permalink_structure ) {
    19712114                if ( $permalink_structure != $this->permalink_structure ) {
    19722115                        $old_permalink_structure = $this->permalink_structure;
    1973                         update_option('permalink_structure', $permalink_structure);
     2116                        update_option( 'permalink_structure', $permalink_structure );
    19742117                        $this->init();
    1975                         do_action('permalink_structure_changed', $old_permalink_structure, $permalink_structure);
     2118
     2119                        /**
     2120                         * Fires after the permalink structure is updated.
     2121                         *
     2122                         * @since 2.8.0
     2123                         *
     2124                         * @param string $old_permalink_structure The previous permalink structure.
     2125                         * @param string $permalink_structure The new permalink structure.
     2126                         */
     2127                        do_action( 'permalink_structure_changed', $old_permalink_structure, $permalink_structure );
    19762128                }
    19772129        }
    19782130