| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
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 */ 24 function 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 */ 61 function 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 */ 94 function 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 */ 124 function 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 */ 167 function 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 = $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 = $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 */ 209 function 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 * @since 7.0.0 Added `$use_title_attr` parameter. 233 * 234 * @global WP_User $authordata The current author's data. 235 * 236 * @param bool $use_title_attr Optional. Whether to add a title attribute. 237 * Default true. 238 * @return string An HTML link if the author's URL exists in user meta, 239 * otherwise the result of get_the_author(). 240 */ 241 function get_the_author_link( $use_title_attr = true ) { 242 if ( get_the_author_meta( 'url' ) ) { 243 global $authordata; 244 245 $author_url = get_the_author_meta( 'url' ); 246 $author_display_name = get_the_author(); 247 248 /* translators: %s: Author's display name. */ 249 $author_title = sprintf( __( 'Visit %s’s website' ), $author_display_name ); 250 251 $link = sprintf( 252 '<a href="%1$s"%2$s rel="author external">%3$s</a>', 253 esc_url( $author_url ), 254 $use_title_attr ? ' title="' . esc_attr( $author_title ) . '"' : '', 255 $author_display_name 256 ); 257 258 /** 259 * Filters the author URL link HTML. 260 * 261 * @since 6.0.0 262 * 263 * @param string $link The default rendered author HTML link. 264 * @param string $author_url Author's URL. 265 * @param WP_User $authordata Author user data. 266 */ 267 return apply_filters( 'the_author_link', $link, $author_url, $authordata ); 268 } else { 269 return get_the_author(); 270 } 271 } 272 273 /** 274 * Displays either author's link or author's name. 275 * 276 * If the author has a home page set, echo an HTML link, otherwise just echo the 277 * author's name. 278 * 279 * @link https://developer.wordpress.org/reference/functions/the_author_link/ 280 * 281 * @since 2.1.0 282 * @since 7.0.0 Added `$use_title_attr` parameter. 283 * 284 * @param bool $use_title_attr Optional. Whether to add a title attribute. 285 * Default true. 286 */ 287 function the_author_link( $use_title_attr = true ) { 288 echo get_the_author_link( $use_title_attr ); 289 } 290 291 /** 292 * Retrieves the number of posts by the author of the current post. 293 * 294 * @since 1.5.0 295 * 296 * @return int The number of posts by the author. 297 */ 298 function get_the_author_posts() { 299 $post = get_post(); 300 if ( ! $post ) { 301 return 0; 302 } 303 return (int) count_user_posts( $post->post_author, $post->post_type ); 304 } 305 306 /** 307 * Displays the number of posts by the author of the current post. 308 * 309 * @link https://developer.wordpress.org/reference/functions/the_author_posts/ 310 * @since 0.71 311 */ 312 function the_author_posts() { 313 echo get_the_author_posts(); 314 } 315 316 /** 317 * Retrieves an HTML link to the author page of the current post's author. 318 * 319 * Returns an HTML-formatted link using get_author_posts_url(). 320 * 321 * @since 4.4.0 322 * @since 7.0.0 Removed title attribute. 323 * 324 * @global WP_User $authordata The current author's data. 325 * 326 * @return string An HTML link to the author page, or an empty string if $authordata is not set. 327 */ 328 function get_the_author_posts_link() { 329 global $authordata; 330 331 if ( ! is_object( $authordata ) ) { 332 return ''; 333 } 334 335 $author = get_the_author(); 336 /* translators: %s: Author's display name. */ 337 $title = sprintf( __( 'Posts by %s' ), $author ); 338 339 $link = sprintf( 340 '<a href="%1$s" rel="author">%2$s</a>', 341 esc_url( get_author_posts_url( $authordata->ID, $authordata->user_nicename ) ), 342 $author 343 ); 344 345 /** 346 * Filters the link to the author page of the author of the current post. 347 * 348 * @since 2.9.0 349 * @since 7.0.0 Added `$author` and `$title` parameters. 350 * 351 * @param string $link HTML link. 352 * @param string $author Author's display name. 353 * @param string $title Text originally used for a title attribute. 354 */ 355 return apply_filters( 'the_author_posts_link', $link, $author, $title ); 356 } 357 358 /** 359 * Displays an HTML link to the author page of the current post's author. 360 * 361 * @since 1.2.0 362 * @since 4.4.0 Converted into a wrapper for get_the_author_posts_link() 363 * 364 * @param string $deprecated Unused. 365 */ 366 function the_author_posts_link( $deprecated = '' ) { 367 if ( ! empty( $deprecated ) ) { 368 _deprecated_argument( __FUNCTION__, '2.1.0' ); 369 } 370 echo get_the_author_posts_link(); 371 } 372 373 /** 374 * Retrieves the URL to the author page for the user with the ID provided. 375 * 376 * @since 2.1.0 377 * 378 * @global WP_Rewrite $wp_rewrite WordPress rewrite component. 379 * 380 * @param int $author_id Author ID. 381 * @param string $author_nicename Optional. The author's nicename (slug). Default empty. 382 * @return string The URL to the author's page. 383 */ 384 function get_author_posts_url( $author_id, $author_nicename = '' ) { 385 global $wp_rewrite; 386 387 $author_id = (int) $author_id; 388 $link = $wp_rewrite->get_author_permastruct(); 389 390 if ( empty( $link ) ) { 391 $file = home_url( '/' ); 392 $link = $file . '?author=' . $author_id; 393 } else { 394 if ( '' === $author_nicename ) { 395 $user = get_userdata( $author_id ); 396 if ( ! empty( $user->user_nicename ) ) { 397 $author_nicename = $user->user_nicename; 398 } 399 } 400 $link = str_replace( '%author%', $author_nicename, $link ); 401 $link = home_url( user_trailingslashit( $link ) ); 402 } 403 404 /** 405 * Filters the URL to the author's page. 406 * 407 * @since 2.1.0 408 * 409 * @param string $link The URL to the author's page. 410 * @param int $author_id The author's ID. 411 * @param string $author_nicename The author's nice name. 412 */ 413 $link = apply_filters( 'author_link', $link, $author_id, $author_nicename ); 414 415 return $link; 416 } 417 418 /** 419 * Lists all the authors of the site, with several options available. 420 * 421 * @link https://developer.wordpress.org/reference/functions/wp_list_authors/ 422 * 423 * @since 1.2.0 424 * 425 * @global wpdb $wpdb WordPress database abstraction object. 426 * 427 * @param string|array $args { 428 * Optional. Array or string of default arguments. 429 * 430 * @type string $orderby How to sort the authors. Accepts 'nicename', 'email', 'url', 'registered', 431 * 'user_nicename', 'user_email', 'user_url', 'user_registered', 'name', 432 * 'display_name', 'post_count', 'ID', 'meta_value', 'user_login'. Default 'name'. 433 * @type string $order Sorting direction for $orderby. Accepts 'ASC', 'DESC'. Default 'ASC'. 434 * @type int $number Maximum authors to return or display. Default empty (all authors). 435 * @type bool $optioncount Show the count in parenthesis next to the author's name. Default false. 436 * @type bool $exclude_admin Whether to exclude the 'admin' account, if it exists. Default true. 437 * @type bool $show_fullname Whether to show the author's full name. Default false. 438 * @type bool $hide_empty Whether to hide any authors with no posts. Default true. 439 * @type string $feed If not empty, show a link to the author's feed and use this text as the alt 440 * parameter of the link. Default empty. 441 * @type string $feed_image If not empty, show a link to the author's feed and use this image URL as 442 * clickable anchor. Default empty. 443 * @type string $feed_type The feed type to link to. Possible values include 'rss2', 'atom'. 444 * Default is the value of get_default_feed(). 445 * @type bool $echo Whether to output the result or instead return it. Default true. 446 * @type string $style If 'list', each author is wrapped in an `<li>` element, otherwise the authors 447 * will be separated by commas. 448 * @type bool $html Whether to list the items in HTML form or plaintext. Default true. 449 * @type int[]|string $exclude Array or comma/space-separated list of author IDs to exclude. Default empty. 450 * @type int[]|string $include Array or comma/space-separated list of author IDs to include. Default empty. 451 * } 452 * @return void|string Void if 'echo' argument is true, list of authors if 'echo' is false. 453 */ 454 function wp_list_authors( $args = '' ) { 455 global $wpdb; 456 457 $defaults = array( 458 'orderby' => 'name', 459 'order' => 'ASC', 460 'number' => '', 461 'optioncount' => false, 462 'exclude_admin' => true, 463 'show_fullname' => false, 464 'hide_empty' => true, 465 'feed' => '', 466 'feed_image' => '', 467 'feed_type' => '', 468 'echo' => true, 469 'style' => 'list', 470 'html' => true, 471 'exclude' => '', 472 'include' => '', 473 ); 474 475 $parsed_args = wp_parse_args( $args, $defaults ); 476 477 $return = ''; 478 479 $query_args = wp_array_slice_assoc( $parsed_args, array( 'orderby', 'order', 'number', 'exclude', 'include' ) ); 480 $query_args['fields'] = 'ids'; 481 482 /** 483 * Filters the query arguments for the list of all authors of the site. 484 * 485 * @since 6.1.0 486 * 487 * @param array $query_args The query arguments for get_users(). 488 * @param array $parsed_args The arguments passed to wp_list_authors() combined with the defaults. 489 */ 490 $query_args = apply_filters( 'wp_list_authors_args', $query_args, $parsed_args ); 491 492 $authors = get_users( $query_args ); 493 494 /** 495 * Filters whether to short-circuit performing the query for author post counts. 496 * 497 * @since 6.1.0 498 * 499 * @param int[]|false $post_counts Array of post counts, keyed by author ID. 500 * @param array $parsed_args The arguments passed to wp_list_authors() combined with the defaults. 501 */ 502 $post_counts = apply_filters( 'pre_wp_list_authors_post_counts_query', false, $parsed_args ); 503 504 if ( ! is_array( $post_counts ) ) { 505 $post_counts = array(); 506 $post_counts_query = $wpdb->get_results( 507 "SELECT DISTINCT post_author, COUNT(ID) AS count 508 FROM $wpdb->posts 509 WHERE " . get_private_posts_cap_sql( 'post' ) . ' 510 GROUP BY post_author' 511 ); 512 513 foreach ( (array) $post_counts_query as $row ) { 514 $post_counts[ $row->post_author ] = $row->count; 515 } 516 } 517 518 foreach ( $authors as $author_id ) { 519 $posts = $post_counts[ $author_id ] ?? 0; 520 521 if ( ! $posts && $parsed_args['hide_empty'] ) { 522 continue; 523 } 524 525 $author = get_userdata( $author_id ); 526 527 if ( $parsed_args['exclude_admin'] && 'admin' === $author->display_name ) { 528 continue; 529 } 530 531 if ( $parsed_args['show_fullname'] && $author->first_name && $author->last_name ) { 532 $name = sprintf( 533 /* translators: 1: User's first name, 2: Last name. */ 534 _x( '%1$s %2$s', 'Display name based on first name and last name' ), 535 $author->first_name, 536 $author->last_name 537 ); 538 } else { 539 $name = $author->display_name; 540 } 541 542 if ( ! $parsed_args['html'] ) { 543 $return .= $name . ', '; 544 545 continue; // No need to go further to process HTML. 546 } 547 548 if ( 'list' === $parsed_args['style'] ) { 549 $return .= '<li>'; 550 } 551 552 $link = sprintf( 553 '<a href="%1$s">%2$s</a>', 554 esc_url( get_author_posts_url( $author->ID, $author->user_nicename ) ), 555 $name 556 ); 557 558 if ( ! empty( $parsed_args['feed_image'] ) || ! empty( $parsed_args['feed'] ) ) { 559 $link .= ' '; 560 if ( empty( $parsed_args['feed_image'] ) ) { 561 $link .= '('; 562 } 563 564 $link .= '<a href="' . get_author_feed_link( $author->ID, $parsed_args['feed_type'] ) . '"'; 565 566 $alt = ''; 567 if ( ! empty( $parsed_args['feed'] ) ) { 568 $alt = ' alt="' . esc_attr( $parsed_args['feed'] ) . '"'; 569 $name = $parsed_args['feed']; 570 } 571 572 $link .= '>'; 573 574 if ( ! empty( $parsed_args['feed_image'] ) ) { 575 $link .= '<img src="' . esc_url( $parsed_args['feed_image'] ) . '" style="border: none;"' . $alt . ' />'; 576 } else { 577 $link .= $name; 578 } 579 580 $link .= '</a>'; 581 582 if ( empty( $parsed_args['feed_image'] ) ) { 583 $link .= ')'; 584 } 585 } 586 587 if ( $parsed_args['optioncount'] ) { 588 $link .= ' (' . $posts . ')'; 589 } 590 591 $return .= $link; 592 $return .= ( 'list' === $parsed_args['style'] ) ? '</li>' : ', '; 593 } 594 595 $return = rtrim( $return, ', ' ); 596 597 if ( $parsed_args['echo'] ) { 598 echo $return; 599 } else { 600 return $return; 601 } 602 } 603 604 /** 605 * Determines whether this site has more than one author. 606 * 607 * Checks to see if more than one author has published posts. 608 * 609 * For more information on this and similar theme functions, check out 610 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 611 * Conditional Tags} article in the Theme Developer Handbook. 612 * 613 * @since 3.2.0 614 * 615 * @global wpdb $wpdb WordPress database abstraction object. 616 * 617 * @return bool Whether or not we have more than one author 618 */ 619 function is_multi_author() { 620 global $wpdb; 621 622 $is_multi_author = get_transient( 'is_multi_author' ); 623 if ( false === $is_multi_author ) { 624 $rows = (array) $wpdb->get_col( "SELECT DISTINCT post_author FROM $wpdb->posts WHERE post_type = 'post' AND post_status = 'publish' LIMIT 2" ); 625 $is_multi_author = 1 < count( $rows ) ? 1 : 0; 626 set_transient( 'is_multi_author', $is_multi_author ); 627 } 628 629 /** 630 * Filters whether the site has more than one author with published posts. 631 * 632 * @since 3.2.0 633 * 634 * @param bool $is_multi_author Whether $is_multi_author should evaluate as true. 635 */ 636 return apply_filters( 'is_multi_author', (bool) $is_multi_author ); 637 } 638 639 /** 640 * Helper function to clear the cache for number of authors. 641 * 642 * @since 3.2.0 643 * @access private 644 */ 645 function __clear_multi_author_cache() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionDoubleUnderscore,PHPCompatibility.FunctionNameRestrictions.ReservedFunctionNames.FunctionDoubleUnderscore 646 delete_transient( 'is_multi_author' ); 647 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Sun Jun 14 08:20:09 2026 | Cross-referenced by PHPXref |