WordPress 4.3
[autoinstalls/wordpress.git] / wp-includes / author-template.php
index 2280487d09dd8ed4c055f3a58abe09e01a8c11f1..36d08bc81e9efafcda5825eba6ee4a7d25184a21 100644 (file)
@@ -4,7 +4,7 @@
  *
  * These functions must be used within the WordPress Loop.
  *
- * @link http://codex.wordpress.org/Author_Templates
+ * @link https://codex.wordpress.org/Author_Templates
  *
  * @package WordPress
  * @subpackage Template
  *
  * @since 1.5.0
  *
- * @uses $authordata The current author's DB object.
+ * @global object $authordata The current author's DB object.
  *
  * @param string $deprecated Deprecated.
- * @return string The author's display name.
+ * @return string|null The author's display name.
  */
 function get_the_author($deprecated = '') {
        global $authordata;
@@ -49,11 +49,11 @@ function get_the_author($deprecated = '') {
  *
  * @since 0.71
  * @see get_the_author()
- * @link http://codex.wordpress.org/Template_Tags/the_author
+ * @link https://codex.wordpress.org/Template_Tags/the_author
  *
  * @param string $deprecated Deprecated.
  * @param string $deprecated_echo Deprecated. Use get_the_author(). Echo the string or return it.
- * @return string The author's display name, from get_the_author().
+ * @return string|null The author's display name, from get_the_author().
  */
 function the_author( $deprecated = '', $deprecated_echo = true ) {
        if ( !empty( $deprecated ) )
@@ -70,7 +70,7 @@ function the_author( $deprecated = '', $deprecated_echo = true ) {
  *
  * @since 2.8.0
  *
- * @return string The author's display name.
+ * @return string|void The author's display name.
  */
 function get_the_modified_author() {
        if ( $last_id = get_post_meta( get_post()->ID, '_edit_last', true) ) {
@@ -88,12 +88,12 @@ function get_the_modified_author() {
 }
 
 /**
- * Display the name of the author who last edited the current post.
+ * Display the name of the author who last edited the current post,
+ * if the author's ID is available.
  *
  * @since 2.8.0
  *
  * @see get_the_author()
- * @return string The author's display name, from get_the_modified_author().
  */
 function the_modified_author() {
        echo get_the_modified_author();
@@ -101,13 +101,18 @@ function the_modified_author() {
 
 /**
  * Retrieve the requested data of the author of the current post.
- * @link http://codex.wordpress.org/Template_Tags/the_author_meta
+ * @link https://codex.wordpress.org/Template_Tags/the_author_meta
  * @since 2.8.0
+ *
+ * @global object $authordata The current author's DB object.
+ *
  * @param string $field selects the field of the users record.
  * @param int $user_id Optional. User ID.
  * @return string The author's field from the current author's DB object.
  */
 function get_the_author_meta( $field = '', $user_id = false ) {
+       $original_user_id = $user_id;
+
        if ( ! $user_id ) {
                global $authordata;
                $user_id = isset( $authordata->ID ) ? $authordata->ID : 0;
@@ -126,20 +131,24 @@ function get_the_author_meta( $field = '', $user_id = false ) {
         * The filter name is dynamic and depends on the $field parameter of the function.
         *
         * @since 2.8.0
+        * @since 4.3.0 The `$original_user_id` parameter was added.
         *
-        * @param string $value   The value of the metadata.
-        * @param int    $user_id The user ID.
+        * @param string   $value            The value of the metadata.
+        * @param int      $user_id          The user ID for the value.
+        * @param int|bool $original_user_id The original user ID, as passed to the function.
         */
-       return apply_filters( 'get_the_author_' . $field, $value, $user_id );
+       return apply_filters( 'get_the_author_' . $field, $value, $user_id, $original_user_id );
 }
 
 /**
- * Retrieve the requested data of the author of the current post.
- * @link http://codex.wordpress.org/Template_Tags/the_author_meta
+ * Outputs the field from the user's DB object. Defaults to current post's author.
+ *
+ * @link https://codex.wordpress.org/Template_Tags/the_author_meta
+ *
  * @since 2.8.0
+ *
  * @param string $field selects the field of the users record.
  * @param int $user_id Optional. User ID.
- * @echo string The author's field from the current author's DB object.
  */
 function the_author_meta( $field = '', $user_id = false ) {
        $author_meta = get_the_author_meta( $field, $user_id );
@@ -162,6 +171,9 @@ function the_author_meta( $field = '', $user_id = false ) {
  *
  * If the author has a home page set, return an HTML link, otherwise just return the
  * author's name.
+ *
+ * @return string|null An HTML link if the author's url exist in user meta,
+ *                     else the result of get_the_author().
  */
 function get_the_author_link() {
        if ( get_the_author_meta('url') ) {
@@ -177,7 +189,7 @@ function get_the_author_link() {
  * If the author has a home page set, echo an HTML link, otherwise just echo the
  * author's name.
  *
- * @link http://codex.wordpress.org/Template_Tags/the_author_link
+ * @link https://codex.wordpress.org/Template_Tags/the_author_link
  *
  * @since 2.1.0
  */
@@ -197,13 +209,13 @@ function get_the_author_posts() {
        if ( ! $post ) {
                return 0;
        }
-       return count_user_posts( $post->post_author );
+       return count_user_posts( $post->post_author, $post->post_type );
 }
 
 /**
  * Display the number of posts by the author of the current post.
  *
- * @link http://codex.wordpress.org/Template_Tags/the_author_posts
+ * @link https://codex.wordpress.org/Template_Tags/the_author_posts
  * @since 0.71
  */
 function the_author_posts() {
@@ -217,8 +229,11 @@ function the_author_posts() {
  * reason for this, is that another function is used to help in printing the
  * link to the author's posts.
  *
- * @link http://codex.wordpress.org/Template_Tags/the_author_posts_link
+ * @link https://codex.wordpress.org/Template_Tags/the_author_posts_link
  * @since 1.2.0
+ *
+ * @global object $authordata The current author's DB object.
+ *
  * @param string $deprecated Deprecated.
  */
 function the_author_posts_link($deprecated = '') {
@@ -226,8 +241,10 @@ function the_author_posts_link($deprecated = '') {
                _deprecated_argument( __FUNCTION__, '2.1' );
 
        global $authordata;
-       if ( !is_object( $authordata ) )
-               return false;
+       if ( ! is_object( $authordata ) ) {
+               return;
+       }
+
        $link = sprintf(
                '<a href="%1$s" title="%2$s" rel="author">%3$s</a>',
                esc_url( get_author_posts_url( $authordata->ID, $authordata->user_nicename ) ),
@@ -249,7 +266,9 @@ function the_author_posts_link($deprecated = '') {
  * Retrieve the URL to the author page for the user with the ID provided.
  *
  * @since 2.1.0
- * @uses $wp_rewrite WP_Rewrite
+ *
+ * @global WP_Rewrite $wp_rewrite
+ *
  * @return string The URL to the author's page.
  */
 function get_author_posts_url($author_id, $author_nicename = '') {
@@ -287,10 +306,12 @@ function get_author_posts_url($author_id, $author_nicename = '') {
 /**
  * List all the authors of the blog, with several options available.
  *
- * @link http://codex.wordpress.org/Template_Tags/wp_list_authors
+ * @link https://codex.wordpress.org/Template_Tags/wp_list_authors
  *
  * @since 1.2.0
  *
+ * @global wpdb $wpdb
+ *
  * @param string|array $args {
  *     Optional. Array or string of default arguments.
  *
@@ -315,7 +336,7 @@ function get_author_posts_url($author_id, $author_nicename = '') {
  *     @type string $exclude       An array, comma-, or space-separated list of author IDs to exclude. Default empty.
  *     @type string $exclude       An array, comma-, or space-separated list of author IDs to include. Default empty.
  * }
- * @return null|string The output, if echo is set to false. Otherwise null.
+ * @return string|void The output, if echo is set to false.
  */
 function wp_list_authors( $args = '' ) {
        global $wpdb;
@@ -337,7 +358,7 @@ function wp_list_authors( $args = '' ) {
        $authors = get_users( $query_args );
 
        $author_count = array();
-       foreach ( (array) $wpdb->get_results( "SELECT DISTINCT post_author, COUNT(ID) AS count FROM $wpdb->posts WHERE post_type = 'post' AND " . get_private_posts_cap_sql( 'post' ) . " GROUP BY post_author" ) as $row ) {
+       foreach ( (array) $wpdb->get_results( "SELECT DISTINCT post_author, COUNT(ID) AS count FROM $wpdb->posts WHERE " . get_private_posts_cap_sql( 'post' ) . " GROUP BY post_author" ) as $row ) {
                $author_count[$row->post_author] = $row->count;
        }
        foreach ( $authors as $author_id ) {
@@ -422,6 +443,9 @@ function wp_list_authors( $args = '' ) {
  * Checks to see if more than one author has published posts.
  *
  * @since 3.2.0
+ *
+ * @global wpdb $wpdb
+ *
  * @return bool Whether or not we have more than one author
  */
 function is_multi_author() {
@@ -451,4 +475,3 @@ function is_multi_author() {
 function __clear_multi_author_cache() {
        delete_transient( 'is_multi_author' );
 }
-add_action('transition_post_status', '__clear_multi_author_cache');