Changeset 27341

Timestamp:

03/01/2014 09:30:55 AM (10 years ago)

Author:

DrewAPicture

Message:

Inline documentation for hooks in wp-includes/rewrite.php.

Props mboynes for the initial patch.
Fixes #26095.

File:

• trunk/src/wp-includes/rewrite.php (modified) (8 diffs)

trunk/src/wp-includes/rewrite.php

@@ -290 +290 @@
     global $wp_rewrite;
 
-    $url = apply_filters('url_to_postid', $url);
+    /**
+     * Filter the URL to derive the post ID from.
+     *
+     * @since 2.2.0
+     *
+     * @param string $url The URL to derive the post ID from.
+     */
+    $url = apply_filters( 'url_to_postid', $url );
 
     // First, check to see if there is a 'p=N' or 'page_id=N' to match against
@@ -1560 +1567 @@
         $registration_pages['.*wp-register.php$'] = $this->index . '?register=true'; // Deprecated
 
-        // Post
+        // Post rewrite rules.
         $post_rewrite = $this->generate_rewrite_rules( $this->permalink_structure, EP_PERMALINK );
-        $post_rewrite = apply_filters('post_rewrite_rules', $post_rewrite);
-
-        // Date
+
+        /**
+         * Filter rewrite rules used for "post" archives.
+         *
+         * @since 1.5.0
+         *
+         * @param array $post_rewrite The rewrite rules for posts.
+         */
+        $post_rewrite = apply_filters( 'post_rewrite_rules', $post_rewrite );
+
+        // Date rewrite rules.
         $date_rewrite = $this->generate_rewrite_rules($this->get_date_permastruct(), EP_DATE);
-        $date_rewrite = apply_filters('date_rewrite_rules', $date_rewrite);
-
-        // Root
+
+        /**
+         * Filter rewrite rules used for date archives.
+         *
+         * Likely date archives would include /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-level rewrite rules.
         $root_rewrite = $this->generate_rewrite_rules($this->root . '/', EP_ROOT);
-        $root_rewrite = apply_filters('root_rewrite_rules', $root_rewrite);
-
-        // Comments
+
+        /**
+         * Filter rewrite rules used for root-level archives.
+         *
+         * Likely root-level archives would 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 rewrite rules.
         $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);
-
-        // Search
+
+        /**
+         * Filter rewrite rules used for comment feed archives.
+         *
+         * Likely comments feed archives include /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 rewrite rules.
         $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);
-
-        // Authors
+
+        /**
+         * Filter rewrite rules used for search archives.
+         *
+         * Likely search-related archives include /search/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 );
+
+        // Author rewrite rules.
         $author_rewrite = $this->generate_rewrite_rules($this->get_author_permastruct(), EP_AUTHORS);
-        $author_rewrite = apply_filters('author_rewrite_rules', $author_rewrite);
-
-        // Pages
+
+        /**
+         * Filter rewrite rules used for author archives.
+         *
+         * Likely author archives would inlcude /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 rewrite rules.
         $page_rewrite = $this->page_rewrite_rules();
-        $page_rewrite = apply_filters('page_rewrite_rules', $page_rewrite);
-
-        // Extra permastructs
+
+        /**
+         * Filter rewrite rules used for "page" post type archives.
+         *
+         * @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 ) {
             if ( is_array( $struct ) ) {
@@ -1600 +1676 @@
             }
 
-            $rules = apply_filters($permastructname . '_rewrite_rules', $rules);
-            if ( 'post_tag' == $permastructname )
-                $rules = apply_filters('tag_rewrite_rules', $rules);
+            /**
+             * Filter rewrite rules used for individual permastructs.
+             *
+             * The dynamic portion of the hook name, $permastructname, refers
+             * to the name of the registered permastruct, e.g. 'post_tag' (tags),
+             * 'category' (categories), etc.
+             *
+             * @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 rewrite rules used specifically for Tags.
+                 *
+                 * @since 2.3.0
+                 * @deprecated 3.1.0 Use 'post_tag_rewrite_rules' instead
+                 *
+                 * @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);
@@ -1613 +1710 @@
             $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;
@@ -1722 +1834 @@
         $rules .= "</IfModule>\n";
 
-        $rules = apply_filters('mod_rewrite_rules', $rules);
-        $rules = apply_filters('rewrite_rules', $rules);  // Deprecated
+        /**
+         *
+         * Filter the list of rewrite rules formatted for output to an .htaccess file.
+         *
+         * @since 1.5.0
+         *
+         * @param string $rules mod_rewrite Rewrite rules formatted for .htaccess.
+         */
+        $rules = apply_filters( 'mod_rewrite_rules', $rules );
+
+        /**
+         * Filter the list of rewrite rules formatted for output to an .htaccess file.
+         *
+         * @since 1.5.0
+         * @deprecated 1.5.0 Use the mod_rewrite_rules filter instead.
+         *
+         * @param string $rules mod_rewrite Rewrite rules formatted for .htaccess.
+         */
+        $rules = apply_filters( 'rewrite_rules', $rules );  // Deprecated
 
         return $rules;
@@ -1769 +1898 @@
         }
 
-        $rules = apply_filters('iis7_url_rewrite_rules', $rules);
+        /**
+         * Filter the list of rewrite rules formatted for output to a web.config.
+         *
+         * @since 2.8.0
+         *
+         * @param string $rules Rewrite rules formatted for IIS web.config.
+         */
+        $rules = apply_filters( 'iis7_url_rewrite_rules', $rules );
 
         return $rules;
@@ -1917 +2053 @@
          *
          * @since 3.7.0
-         * @param bool $hard Defaults to true.
+         *
+         * @param bool $hard Whether to flush rewrite rules "hard". Default true.
          */
-        if ( ! $hard || ! apply_filters( 'flush_rewrite_rules_hard', true ) )
+        if ( ! $hard || ! apply_filters( 'flush_rewrite_rules_hard', true ) ) {
             return;
+        }
         if ( function_exists( 'save_mod_rewrite_rules' ) )
             save_mod_rewrite_rules();
@@ -1979 +2117 @@
             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 );
         }
     }