Ticket #26095: rewrite.php.diff

wp-includes/rewrite.php

@@ -288 +288 @@
 function url_to_postid($url) {
         global $wp_rewrite;
 
-        $url = apply_filters('url_to_postid', $url);
+        /**
+         * Filter the URL prior to using it to find the post ID.
+         *
+         * This filter fires before the URL is used to find the post ID.
+         * If a hook returns a "default permalink" URL, the ID in the URL
+         * will be returned by the parent function. For instance, returning
+         * '/?p=12345' means that the function will return 12345.
+         *
+         * @since 2.2.0
+         *
+         * @param string $url The URL which will be searched.
+         */
+        $url = apply_filters( 'url_to_postid', $url );
 
         // First, check to see if there is a 'p=N' or 'page_id=N' to match against
         if ( preg_match('#[?&](p|page_id|attachment_id)=(\d+)#', $url, $values) )       {
@@ -1560 +1572 @@
 
                 // Post
                 $post_rewrite = $this->generate_rewrite_rules( $this->permalink_structure, EP_PERMALINK );
-                $post_rewrite = apply_filters('post_rewrite_rules', $post_rewrite);
+                /**
+                 * Filters the "post" post type rewrite rules before they're added to the rewrite rules array.
+                 *
+                 * This array should include all rewrite rules that were generated for accessing the
+                 * "post" post types paths, archive paths, etc. This does not include date-based paths.
+                 *
+                 * @since 1.5.0
+                 *
+                 * @param array $post_rewrite The rewrite rules for the "post" post type.
+                 */
+                $post_rewrite = apply_filters( 'post_rewrite_rules', $post_rewrite );
 
                 // Date
-                $date_rewrite = $this->generate_rewrite_rules($this->get_date_permastruct(), EP_DATE);
-                $date_rewrite = apply_filters('date_rewrite_rules', $date_rewrite);
+                $date_rewrite = $this->generate_rewrite_rules( $this->get_date_permastruct(), EP_DATE );
+                /**
+                 * Filters the date-based rewrite rules before they're added to the rewrite rules array.
+                 *
+                 * This array should include all rewrite rules that were generated for listing posts
+                 * by date, e.g. /yyyy/, /yyyy/mm/, and /yyyy/mm/dd/.
+                 *
+                 * @since 1.5.0
+                 *
+                 * @param array $date_rewrite The rewrite rules for date archives.
+                 */
+                $date_rewrite = apply_filters( 'date_rewrite_rules', $date_rewrite );
 
                 // Root
-                $root_rewrite = $this->generate_rewrite_rules($this->root . '/', EP_ROOT);
-                $root_rewrite = apply_filters('root_rewrite_rules', $root_rewrite);
+                $root_rewrite = $this->generate_rewrite_rules( $this->root . '/', EP_ROOT );
+                /**
+                 * Filters the root-level rewrite rules before they're added to the rewrite rules array.
+                 *
+                 * The root-level rewrite rules include pagination rules for the homepage as well as
+                 * site-wide post feeds (e.g. /feed/ and /feed/atom/).
+                 *
+                 * @since 1.5.0
+                 *
+                 * @param array $root_rewrite The root-level rewrite rules.
+                 */
+                $root_rewrite = apply_filters( 'root_rewrite_rules', $root_rewrite );
 
                 // Comments
-                $comments_rewrite = $this->generate_rewrite_rules($this->root . $this->comments_base, EP_COMMENTS, false, true, true, false);
-                $comments_rewrite = apply_filters('comments_rewrite_rules', $comments_rewrite);
+                $comments_rewrite = $this->generate_rewrite_rules( $this->root . $this->comments_base, EP_COMMENTS, false, true, true, false );
+                /**
+                 * Filters the comments feed rewrite rules before they're added to the rewrite rules array.
+                 *
+                 * The comments rewrite rules include the paths for accessing the comments feeds,
+                 * for instance /comments/feed/ and /comments/feed/atom/.
+                 *
+                 * @since 1.5.0
+                 *
+                 * @param array $comments_rewrite The rewrite rules for the site-wide comments feeds.
+                 */
+                $comments_rewrite = apply_filters( 'comments_rewrite_rules', $comments_rewrite );
 
                 // Search
                 $search_structure = $this->get_search_permastruct();
-                $search_rewrite = $this->generate_rewrite_rules($search_structure, EP_SEARCH);
-                $search_rewrite = apply_filters('search_rewrite_rules', $search_rewrite);
+                $search_rewrite = $this->generate_rewrite_rules( $search_structure, EP_SEARCH );
+                /**
+                 * Filters the search rewrite rules before they're added to the rewrite rules array.
+                 *
+                 * The search-related rewrite rules include /search/some+search+query/ as well as
+                 * pagination and feed paths for a search.
+                 *
+                 * @since 1.5.0
+                 *
+                 * @param array $search_rewrite The rewrite rules for search queries.
+                 */
+                $search_rewrite = apply_filters( 'search_rewrite_rules', $search_rewrite );
 
                 // Authors
-                $author_rewrite = $this->generate_rewrite_rules($this->get_author_permastruct(), EP_AUTHORS);
-                $author_rewrite = apply_filters('author_rewrite_rules', $author_rewrite);
+                $author_rewrite = $this->generate_rewrite_rules( $this->get_author_permastruct(), EP_AUTHORS );
+                /**
+                 * Filters the author rewrite rules before they're added to the rewrite rules array.
+                 *
+                 * The author rewrite rules include /author/author-name/ as well as pagination and
+                 * feed paths for author archives.
+                 *
+                 * @since 1.5.0
+                 *
+                 * @param array $author_rewrite The rewrite rules for author archives.
+                 */
+                $author_rewrite = apply_filters( 'author_rewrite_rules', $author_rewrite );
 
                 // Pages
                 $page_rewrite = $this->page_rewrite_rules();
-                $page_rewrite = apply_filters('page_rewrite_rules', $page_rewrite);
+                /**
+                 * Filters the "page" post type rewrite rules before they're added to the rewrite rules array.
+                 *
+                 * @since 1.5.0
+                 *
+                 * @param array $page_rewrite The rewrite rules for the "page" post type.
+                 */
+                $page_rewrite = apply_filters( 'page_rewrite_rules', $page_rewrite );
 
                 // Extra permastructs
                 foreach ( $this->extra_permastructs as $permastructname => $struct ) {
@@ -1598 +1677 @@
                                 $rules = $this->generate_rewrite_rules( $struct );
                         }
 
-                        $rules = apply_filters($permastructname . '_rewrite_rules', $rules);
-                        if ( 'post_tag' == $permastructname )
-                                $rules = apply_filters('tag_rewrite_rules', $rules);
+                        /**
+                         * Filters the rewrite rules for individual extra permalink structures.
+                         *
+                         * Extra permalink structures are typically added via add_permastruct() (used
+                         * by both register_post_type and register_taxonomy). For instance, the
+                         * 'category' taxonomy adds the 'category' permastruct, and this will apply
+                         * the filter 'category_rewrite_rules' to the generated rewrite rules.
+                         *
+                         * @since 3.1.0
+                         *
+                         * @param array $rules The rewrite rules generated for the current permastruct.
+                         */
+                        $rules = apply_filters( $permastructname . '_rewrite_rules', $rules );
+                        if ( 'post_tag' == $permastructname ) {
+                                /**
+                                 * Filter the generated rewrite rules for tags.
+                                 *
+                                 * This filter exists for backwards compatibility. The permastruct for
+                                 * tags is "post_tag", so the generated rules can also be filtered via
+                                 * post_tag_rewrite_rules.
+                                 *
+                                 * @since 2.3.0
+                                 *
+                                 * @param array $rules The rewrite rules generated for tags.
+                                 */
+                                $rules = apply_filters( 'tag_rewrite_rules', $rules );
+                        }
 
-                        $this->extra_rules_top = array_merge($this->extra_rules_top, $rules);
+                        $this->extra_rules_top = array_merge( $this->extra_rules_top, $rules );
                 }
 
                 // Put them together.
                 if ( $this->use_verbose_page_rules )
-                        $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);
+                        $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 );
                 else
-                        $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);
+                        $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 );
 
-                do_action_ref_array('generate_rewrite_rules', array(&$this));
-                $this->rules = apply_filters('rewrite_rules_array', $this->rules);
 
+                /**
+                 * Fires after the rewrite rules are generated.
+                 *
+                 * @since 1.5.0
+                 *
+                 * @param WP_Rewrite $this Current WP_Rewrite instance, passed by reference.
+                 */
+                do_action_ref_array( 'generate_rewrite_rules', array( &$this ) );
+
+                /**
+                 * Filter the full set of generated rewrite rules.
+                 *
+                 * @since 1.5.0
+                 *
+                 * @param array $this->rules The compiled array of rewrite rules.
+                 */
+                $this->rules = apply_filters( 'rewrite_rules_array', $this->rules );
+
                 return $this->rules;
         }
 
@@ -1720 +1839 @@
 
                 $rules .= "</IfModule>\n";
 
-                $rules = apply_filters('mod_rewrite_rules', $rules);
-                $rules = apply_filters('rewrite_rules', $rules);  // Deprecated
+                /**
+                 * Filter the mod_rewrite formatted .htaccess rewrite rules.
+                 *
+                 * @since 1.5.0
+                 *
+                 * @param string $rules mod_rewrite formatted rewrite rules for a .htaccess file.
+                 */
+                $rules = apply_filters( 'mod_rewrite_rules', $rules );
 
+                /**
+                 * Filter the mod_rewrite formatted .htaccess rewrite rules.
+                 *
+                 * @since 1.5.0
+                 * @deprecated 1.5.0 Use the mod_rewrite_rules filter instead.
+                 *
+                 * @param string $rules mod_rewrite formatted rewrite rules for a .htaccess file.
+                 */
+                $rules = apply_filters( 'rewrite_rules', $rules );  // Deprecated
+
                 return $rules;
         }
 
@@ -1767 +1902 @@
 </configuration>';
                 }
 
-                $rules = apply_filters('iis7_url_rewrite_rules', $rules);
+                /**
+                 * Filter the IIS7 URL Rewrite formatted rewrite rules for a web.config file.
+                 *
+                 * @since 2.8.0
+                 *
+                 * @param string $rules IIS7 URL Rewrite formatted rewrite rules.
+                 */
+                $rules = apply_filters( 'iis7_url_rewrite_rules', $rules );
 
                 return $rules;
         }
@@ -1910 +2052 @@
                  * A "hard" flush updates .htaccess (Apache) or web.config (IIS).
                  *
                  * @since 3.7.0
+                 *
                  * @param bool $hard Defaults to true.
                  */
                 if ( ! $hard || ! apply_filters( 'flush_rewrite_rules_hard', true ) )
@@ -1967 +2110 @@
          *
          * @param string $permalink_structure Permalink structure.
          */
-        function set_permalink_structure($permalink_structure) {
+        function set_permalink_structure( $permalink_structure ) {
                 if ( $permalink_structure != $this->permalink_structure ) {
                         $old_permalink_structure = $this->permalink_structure;
-                        update_option('permalink_structure', $permalink_structure);
+                        update_option( 'permalink_structure', $permalink_structure );
                         $this->init();
-                        do_action('permalink_structure_changed', $old_permalink_structure, $permalink_structure);
+
+                        /**
+                         * Fires after the permalink structure is updated.
+                         *
+                         * @since 2.8.0
+                         *
+                         * @param string $old_permalink_structure The previous permalink structure.
+                         * @param string $permalink_structure The new permalink structure.
+                         */
+                        do_action( 'permalink_structure_changed', $old_permalink_structure, $permalink_structure );
                 }
         }