1<?php
2/**
3 * Author Template functions for use in themes.
4 *
5 * These functions must be used within the WordPress Loop.
6 *
7 * @link https://codex.wordpress.org/Author_Templates
8 *
9 * @package WordPress
10 * @subpackage Template
11 */
12
13/**
14 * Retrieves the author of the current post.
15 *
16 * @since 1.5.0
17 * @since 6.3.0 Returns an empty string if the author's display name is unknown.
18 *
19 * @global WP_User $authordata The current author's data.
20 *
21 * @param string $deprecated Deprecated.
22 * @return string The author's display name, empty string if unknown.
23 */
24function get_the_author( $deprecated = '' ) {
25 global $authordata;
26
27 if ( ! empty( $deprecated ) ) {
28 _deprecated_argument( __FUNCTION__, '2.1.0' );
29 }
30
31 /**
32 * Filters the display name of the current post's author.
33 *
34 * @since 2.9.0
35 *
36 * @param string $display_name The author's display name.
37 */
38 return apply_filters( 'the_author', is_object( $authordata ) ? $authordata->display_name : '' );
39}
40
41/**
42 * Displays the name of the author of the current post.
43 *
44 * The behavior of this function is based off of old functionality predating
45 * get_the_author(). This function is not deprecated, but is designed to echo
46 * the value from get_the_author() and as an result of any old theme that might
47 * still use the old behavior will also pass the value from get_the_author().
48 *
49 * The normal, expected behavior of this function is to echo the author and not
50 * return it. However, backward compatibility has to be maintained.
51 *
52 * @since 0.71
53 *
54 * @see get_the_author()
55 * @link https://developer.wordpress.org/reference/functions/the_author/
56 *
57 * @param string $deprecated Deprecated.
58 * @param bool $deprecated_echo Deprecated. Use get_the_author(). Echo the string or return it.
59 * @return string The author's display name, from get_the_author().
60 */
61function the_author( $deprecated = '', $deprecated_echo = true ) {
62 if ( ! empty( $deprecated ) ) {
63 _deprecated_argument( __FUNCTION__, '2.1.0' );
64 }
65
66 if ( true !== $deprecated_echo ) {
67 _deprecated_argument(
68 __FUNCTION__,
69 '1.5.0',
70 sprintf(
71 /* translators: %s: get_the_author() */
72 __( 'Use %s instead if you do not want the value echoed.' ),
73 '<code>get_the_author()</code>'
74 )
75 );
76 }
77
78 if ( $deprecated_echo ) {
79 echo get_the_author();
80 }
81
82 return get_the_author();
83}
84
85/**
86 * Retrieves the author who last edited the current post.
87 *
88 * @since 2.8.0
89 * @since 6.9.0 Added the `$post` parameter. Unknown return value is now explicitly null instead of void.
90 *
91 * @param int|WP_Post|null $post Optional. Post ID or post object. Default is global `$post` object.
92 * @return string|null The author's display name. Empty string if user is unavailable. Null if there was no last editor or the post is invalid.
93 */
94function get_the_modified_author( $post = null ) {
95 $post = get_post( $post );
96 if ( ! $post ) {
97 return null;
98 }
99
100 $last_id = get_post_meta( $post->ID, '_edit_last', true );
101 if ( ! $last_id ) {
102 return null;
103 }
104 $last_user = get_userdata( $last_id );
105
106 /**
107 * Filters the display name of the author who last edited the current post.
108 *
109 * @since 2.8.0
110 *
111 * @param string $display_name The author's display name, empty string if user is unavailable.
112 */
113 return apply_filters( 'the_modified_author', $last_user ? $last_user->display_name : '' );
114}
115
116/**
117 * Displays the name of the author who last edited the current post,
118 * if the author's ID is available.
119 *
120 * @since 2.8.0
121 *
122 * @see get_the_author()
123 */
124function the_modified_author() {
125 echo get_the_modified_author();
126}
127
128/**
129 * Retrieves the requested data of the author of the current post.
130 *
131 * Valid values for the `$field` parameter include:
132 *
133 * - admin_color
134 * - comment_shortcuts
135 * - description
136 * - display_name
137 * - first_name
138 * - ID
139 * - last_name
140 * - nickname
141 * - plugins_last_view
142 * - plugins_per_page
143 * - rich_editing
144 * - syntax_highlighting
145 * - user_activation_key
146 * - user_description
147 * - user_email
148 * - user_firstname
149 * - user_lastname
150 * - user_level
151 * - user_login
152 * - user_nicename
153 * - user_pass
154 * - user_registered
155 * - user_status
156 * - user_url
157 *
158 * @since 2.8.0
159 * @since 6.9.0 Removed `aim`, `jabber`, and `yim` as valid values for the `$field` parameter.
160 *
161 * @global WP_User $authordata The current author's data.
162 *
163 * @param string $field Optional. The user field to retrieve. Default empty.
164 * @param int|false $user_id Optional. User ID. Defaults to the current post author.
165 * @return string The author's field from the current author's DB object, otherwise an empty string.
166 */
167function get_the_author_meta( $field = '', $user_id = false ) {
168 $original_user_id = $user_id;
169
170 if ( ! $user_id ) {
171 global $authordata;
172 $user_id = isset( $authordata->ID ) ? $authordata->ID : 0;
173 } else {
174 $authordata = get_userdata( $user_id );
175 }
176
177 if ( in_array( $field, array( 'login', 'pass', 'nicename', 'email', 'url', 'registered', 'activation_key', 'status' ), true ) ) {
178 $field = 'user_' . $field;
179 }
180
181 $value = isset( $authordata->$field ) ? $authordata->$field : '';
182
183 /**
184 * Filters the value of the requested user metadata.
185 *
186 * The filter name is dynamic and depends on the $field parameter of the function.
187 *
188 * @since 2.8.0
189 * @since 4.3.0 The `$original_user_id` parameter was added.
190 *
191 * @param string $value The value of the metadata.
192 * @param int $user_id The user ID for the value.
193 * @param int|false $original_user_id The original user ID, as passed to the function.
194 */
195 return apply_filters( "get_the_author_{$field}", $value, $user_id, $original_user_id );
196}
197
198/**
199 * Outputs the field from the user's DB object. Defaults to current post's author.
200 *
201 * @since 2.8.0
202 *
203 * @param string $field Selects the field of the users record. See get_the_author_meta()
204 * for the list of possible fields.
205 * @param int|false $user_id Optional. User ID. Defaults to the current post author.
206 *
207 * @see get_the_author_meta()
208 */
209function the_author_meta( $field = '', $user_id = false ) {
210 $author_meta = get_the_author_meta( $field, $user_id );
211
212 /**
213 * Filters the value of the requested user metadata.
214 *
215 * The filter name is dynamic and depends on the $field parameter of the function.
216 *
217 * @since 2.8.0
218 *
219 * @param string $author_meta The value of the metadata.
220 * @param int|false $user_id The user ID.
221 */
222 echo apply_filters( "the_author_{$field}", $author_meta, $user_id );
223}
224
225/**
226 * Retrieves either author's link or author's name.
227 *
228 * If the author has a home page set, return an HTML link, otherwise just return
229 * the author's name.
230 *
231 * @since 3.0.0
232 *
233 * @global WP_User $authordata The current author's data.
234 *
235 * @return string An HTML link if the author's URL exists in user meta,
236 * otherwise the result of get_the_author().
237 */
238function get_the_author_link() {
239 if ( get_the_author_meta( 'url' ) ) {
240 global $authordata;
241
242 $author_url = get_the_author_meta( 'url' );
243 $author_display_name = get_the_author();
244
245 $link = sprintf(
246 '<a href="%1$s" title="%2$s" rel="author external">%3$s</a>',
247 esc_url( $author_url ),
248 /* translators: %s: Author's display name. */
249 esc_attr( sprintf( __( 'Visit %s’s website' ), $author_display_name ) ),
250 $author_display_name
251 );
252
253 /**
254 * Filters the author URL link HTML.
255 *
256 * @since 6.0.0
257 *
258 * @param string $link The default rendered author HTML link.
259 * @param string $author_url Author's URL.
260 * @param WP_User $authordata Author user data.
261 */
262 return apply_filters( 'the_author_link', $link, $author_url, $authordata );
263 } else {
264 return get_the_author();
265 }
266}
267
268/**
269 * Displays either author's link or author's name.
270 *
271 * If the author has a home page set, echo an HTML link, otherwise just echo the
272 * author's name.
273 *
274 * @link https://developer.wordpress.org/reference/functions/the_author_link/
275 *
276 * @since 2.1.0
277 */
278function the_author_link() {
279 echo get_the_author_link();
280}
281
282/**
283 * Retrieves the number of posts by the author of the current post.
284 *
285 * @since 1.5.0
286 *
287 * @return int The number of posts by the author.
288 */
289function get_the_author_posts() {
290 $post = get_post();
291 if ( ! $post ) {
292 return 0;
293 }
294 return (int) count_user_posts( $post->post_author, $post->post_type );
295}
296
297/**
298 * Displays the number of posts by the author of the current post.
299 *
300 * @link https://developer.wordpress.org/reference/functions/the_author_posts/
301 * @since 0.71
302 */
303function the_author_posts() {
304 echo get_the_author_posts();
305}
306
307/**
308 * Retrieves an HTML link to the author page of the current post's author.
309 *
310 * Returns an HTML-formatted link using get_author_posts_url().
311 *
312 * @since 4.4.0
313 *
314 * @global WP_User $authordata The current author's data.
315 *
316 * @return string An HTML link to the author page, or an empty string if $authordata is not set.
317 */
318function get_the_author_posts_link() {
319 global $authordata;
320
321 if ( ! is_object( $authordata ) ) {
322 return '';
323 }
324
325 $link = sprintf(
326 '<a href="%1$s" title="%2$s" rel="author">%3$s</a>',
327 esc_url( get_author_posts_url( $authordata->ID, $authordata->user_nicename ) ),
328 /* translators: %s: Author's display name. */
329 esc_attr( sprintf( __( 'Posts by %s' ), get_the_author() ) ),
330 get_the_author()
331 );
332
333 /**
334 * Filters the link to the author page of the author of the current post.
335 *
336 * @since 2.9.0
337 *
338 * @param string $link HTML link.
339 */
340 return apply_filters( 'the_author_posts_link', $link );
341}
342
343/**
344 * Displays an HTML link to the author page of the current post's author.
345 *
346 * @since 1.2.0
347 * @since 4.4.0 Converted into a wrapper for get_the_author_posts_link()
348 *
349 * @param string $deprecated Unused.
350 */
351function the_author_posts_link( $deprecated = '' ) {
352 if ( ! empty( $deprecated ) ) {
353 _deprecated_argument( __FUNCTION__, '2.1.0' );
354 }
355 echo get_the_author_posts_link();
356}
357
358/**
359 * Retrieves the URL to the author page for the user with the ID provided.
360 *
361 * @since 2.1.0
362 *
363 * @global WP_Rewrite $wp_rewrite WordPress rewrite component.
364 *
365 * @param int $author_id Author ID.
366 * @param string $author_nicename Optional. The author's nicename (slug). Default empty.
367 * @return string The URL to the author's page.
368 */
369function get_author_posts_url( $author_id, $author_nicename = '' ) {
370 global $wp_rewrite;
371
372 $author_id = (int) $author_id;
373 $link = $wp_rewrite->get_author_permastruct();
374
375 if ( empty( $link ) ) {
376 $file = home_url( '/' );
377 $link = $file . '?author=' . $author_id;
378 } else {
379 if ( '' === $author_nicename ) {
380 $user = get_userdata( $author_id );
381 if ( ! empty( $user->user_nicename ) ) {
382 $author_nicename = $user->user_nicename;
383 }
384 }
385 $link = str_replace( '%author%', $author_nicename, $link );
386 $link = home_url( user_trailingslashit( $link ) );
387 }
388
389 /**
390 * Filters the URL to the author's page.
391 *
392 * @since 2.1.0
393 *
394 * @param string $link The URL to the author's page.
395 * @param int $author_id The author's ID.
396 * @param string $author_nicename The author's nice name.
397 */
398 $link = apply_filters( 'author_link', $link, $author_id, $author_nicename );
399
400 return $link;
401}
402
403/**
404 * Lists all the authors of the site, with several options available.
405 *
406 * @link https://developer.wordpress.org/reference/functions/wp_list_authors/
407 *
408 * @since 1.2.0
409 *
410 * @global wpdb $wpdb WordPress database abstraction object.
411 *
412 * @param string|array $args {
413 * Optional. Array or string of default arguments.
414 *
415 * @type string $orderby How to sort the authors. Accepts 'nicename', 'email', 'url', 'registered',
416 * 'user_nicename', 'user_email', 'user_url', 'user_registered', 'name',
417 * 'display_name', 'post_count', 'ID', 'meta_value', 'user_login'. Default 'name'.
418 * @type string $order Sorting direction for $orderby. Accepts 'ASC', 'DESC'. Default 'ASC'.
419 * @type int $number Maximum authors to return or display. Default empty (all authors).
420 * @type bool $optioncount Show the count in parenthesis next to the author's name. Default false.
421 * @type bool $exclude_admin Whether to exclude the 'admin' account, if it exists. Default true.
422 * @type bool $show_fullname Whether to show the author's full name. Default false.
423 * @type bool $hide_empty Whether to hide any authors with no posts. Default true.
424 * @type string $feed If not empty, show a link to the author's feed and use this text as the alt
425 * parameter of the link. Default empty.
426 * @type string $feed_image If not empty, show a link to the author's feed and use this image URL as
427 * clickable anchor. Default empty.
428 * @type string $feed_type The feed type to link to. Possible values include 'rss2', 'atom'.
429 * Default is the value of get_default_feed().
430 * @type bool $echo Whether to output the result or instead return it. Default true.
431 * @type string $style If 'list', each author is wrapped in an `<li>` element, otherwise the authors
432 * will be separated by commas.
433 * @type bool $html Whether to list the items in HTML form or plaintext. Default true.
434 * @type int[]|string $exclude Array or comma/space-separated list of author IDs to exclude. Default empty.
435 * @type int[]|string $include Array or comma/space-separated list of author IDs to include. Default empty.
436 * }
437 * @return void|string Void if 'echo' argument is true, list of authors if 'echo' is false.
438 */
439function wp_list_authors( $args = '' ) {
440 global $wpdb;
441
442 $defaults = array(
443 'orderby' => 'name',
444 'order' => 'ASC',
445 'number' => '',
446 'optioncount' => false,
447 'exclude_admin' => true,
448 'show_fullname' => false,
449 'hide_empty' => true,
450 'feed' => '',
451 'feed_image' => '',
452 'feed_type' => '',
453 'echo' => true,
454 'style' => 'list',
455 'html' => true,
456 'exclude' => '',
457 'include' => '',
458 );
459
460 $parsed_args = wp_parse_args( $args, $defaults );
461
462 $return = '';
463
464 $query_args = wp_array_slice_assoc( $parsed_args, array( 'orderby', 'order', 'number', 'exclude', 'include' ) );
465 $query_args['fields'] = 'ids';
466
467 /**
468 * Filters the query arguments for the list of all authors of the site.
469 *
470 * @since 6.1.0
471 *
472 * @param array $query_args The query arguments for get_users().
473 * @param array $parsed_args The arguments passed to wp_list_authors() combined with the defaults.
474 */
475 $query_args = apply_filters( 'wp_list_authors_args', $query_args, $parsed_args );
476
477 $authors = get_users( $query_args );
478 $post_counts = array();
479
480 /**
481 * Filters whether to short-circuit performing the query for author post counts.
482 *
483 * @since 6.1.0
484 *
485 * @param int[]|false $post_counts Array of post counts, keyed by author ID.
486 * @param array $parsed_args The arguments passed to wp_list_authors() combined with the defaults.
487 */
488 $post_counts = apply_filters( 'pre_wp_list_authors_post_counts_query', false, $parsed_args );
489
490 if ( ! is_array( $post_counts ) ) {
491 $post_counts = array();
492 $post_counts_query = $wpdb->get_results(
493 "SELECT DISTINCT post_author, COUNT(ID) AS count
494 FROM $wpdb->posts
495 WHERE " . get_private_posts_cap_sql( 'post' ) . '
496 GROUP BY post_author'
497 );
498
499 foreach ( (array) $post_counts_query as $row ) {
500 $post_counts[ $row->post_author ] = $row->count;
501 }
502 }
503
504 foreach ( $authors as $author_id ) {
505 $posts = isset( $post_counts[ $author_id ] ) ? $post_counts[ $author_id ] : 0;
506
507 if ( ! $posts && $parsed_args['hide_empty'] ) {
508 continue;
509 }
510
511 $author = get_userdata( $author_id );
512
513 if ( $parsed_args['exclude_admin'] && 'admin' === $author->display_name ) {
514 continue;
515 }
516
517 if ( $parsed_args['show_fullname'] && $author->first_name && $author->last_name ) {
518 $name = sprintf(
519 /* translators: 1: User's first name, 2: Last name. */
520 _x( '%1$s %2$s', 'Display name based on first name and last name' ),
521 $author->first_name,
522 $author->last_name
523 );
524 } else {
525 $name = $author->display_name;
526 }
527
528 if ( ! $parsed_args['html'] ) {
529 $return .= $name . ', ';
530
531 continue; // No need to go further to process HTML.
532 }
533
534 if ( 'list' === $parsed_args['style'] ) {
535 $return .= '<li>';
536 }
537
538 $link = sprintf(
539 '<a href="%1$s" title="%2$s">%3$s</a>',
540 esc_url( get_author_posts_url( $author->ID, $author->user_nicename ) ),
541 /* translators: %s: Author's display name. */
542 esc_attr( sprintf( __( 'Posts by %s' ), $author->display_name ) ),
543 $name
544 );
545
546 if ( ! empty( $parsed_args['feed_image'] ) || ! empty( $parsed_args['feed'] ) ) {
547 $link .= ' ';
548 if ( empty( $parsed_args['feed_image'] ) ) {
549 $link .= '(';
550 }
551
552 $link .= '<a href="' . get_author_feed_link( $author->ID, $parsed_args['feed_type'] ) . '"';
553
554 $alt = '';
555 if ( ! empty( $parsed_args['feed'] ) ) {
556 $alt = ' alt="' . esc_attr( $parsed_args['feed'] ) . '"';
557 $name = $parsed_args['feed'];
558 }
559
560 $link .= '>';
561
562 if ( ! empty( $parsed_args['feed_image'] ) ) {
563 $link .= '<img src="' . esc_url( $parsed_args['feed_image'] ) . '" style="border: none;"' . $alt . ' />';
564 } else {
565 $link .= $name;
566 }
567
568 $link .= '</a>';
569
570 if ( empty( $parsed_args['feed_image'] ) ) {
571 $link .= ')';
572 }
573 }
574
575 if ( $parsed_args['optioncount'] ) {
576 $link .= ' (' . $posts . ')';
577 }
578
579 $return .= $link;
580 $return .= ( 'list' === $parsed_args['style'] ) ? '</li>' : ', ';
581 }
582
583 $return = rtrim( $return, ', ' );
584
585 if ( $parsed_args['echo'] ) {
586 echo $return;
587 } else {
588 return $return;
589 }
590}
591
592/**
593 * Determines whether this site has more than one author.
594 *
595 * Checks to see if more than one author has published posts.
596 *
597 * For more information on this and similar theme functions, check out
598 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
599 * Conditional Tags} article in the Theme Developer Handbook.
600 *
601 * @since 3.2.0
602 *
603 * @global wpdb $wpdb WordPress database abstraction object.
604 *
605 * @return bool Whether or not we have more than one author
606 */
607function is_multi_author() {
608 global $wpdb;
609
610 $is_multi_author = get_transient( 'is_multi_author' );
611 if ( false === $is_multi_author ) {
612 $rows = (array) $wpdb->get_col( "SELECT DISTINCT post_author FROM $wpdb->posts WHERE post_type = 'post' AND post_status = 'publish' LIMIT 2" );
613 $is_multi_author = 1 < count( $rows ) ? 1 : 0;
614 set_transient( 'is_multi_author', $is_multi_author );
615 }
616
617 /**
618 * Filters whether the site has more than one author with published posts.
619 *
620 * @since 3.2.0
621 *
622 * @param bool $is_multi_author Whether $is_multi_author should evaluate as true.
623 */
624 return apply_filters( 'is_multi_author', (bool) $is_multi_author );
625}
626
627/**
628 * Helper function to clear the cache for number of authors.
629 *
630 * @since 3.2.0
631 * @access private
632 */
633function __clear_multi_author_cache() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionDoubleUnderscore,PHPCompatibility.FunctionNameRestrictions.ReservedFunctionNames.FunctionDoubleUnderscore
634 delete_transient( 'is_multi_author' );
635}
636