| [ 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 string|void List of authors if 'echo' is false, nothing otherwise. 453 * @phpstan-return ( 454 * $args is array{ echo: false|0|''|'0', ... } 455 * ? string 456 * : ( $args is ''|array ? void : string|null ) 457 * ) 458 */ 459 function wp_list_authors( $args = '' ) { 460 global $wpdb; 461 462 $defaults = array( 463 'orderby' => 'name', 464 'order' => 'ASC', 465 'number' => '', 466 'optioncount' => false, 467 'exclude_admin' => true, 468 'show_fullname' => false, 469 'hide_empty' => true, 470 'feed' => '', 471 'feed_image' => '', 472 'feed_type' => '', 473 'echo' => true, 474 'style' => 'list', 475 'html' => true, 476 'exclude' => '', 477 'include' => '', 478 ); 479 480 $parsed_args = wp_parse_args( $args, $defaults ); 481 482 $return = ''; 483 484 $query_args = wp_array_slice_assoc( $parsed_args, array( 'orderby', 'order', 'number', 'exclude', 'include' ) ); 485 $query_args['fields'] = 'ids'; 486 487 /** 488 * Filters the query arguments for the list of all authors of the site. 489 * 490 * @since 6.1.0 491 * 492 * @param array $query_args The query arguments for get_users(). 493 * @param array $parsed_args The arguments passed to wp_list_authors() combined with the defaults. 494 */ 495 $query_args = apply_filters( 'wp_list_authors_args', $query_args, $parsed_args ); 496 497 $authors = get_users( $query_args ); 498 499 /** 500 * Filters whether to short-circuit performing the query for author post counts. 501 * 502 * @since 6.1.0 503 * 504 * @param int[]|false $post_counts Array of post counts, keyed by author ID. 505 * @param array $parsed_args The arguments passed to wp_list_authors() combined with the defaults. 506 */ 507 $post_counts = apply_filters( 'pre_wp_list_authors_post_counts_query', false, $parsed_args ); 508 509 if ( ! is_array( $post_counts ) ) { 510 $post_counts = array(); 511 $post_counts_query = $wpdb->get_results( 512 "SELECT DISTINCT post_author, COUNT(ID) AS count 513 FROM $wpdb->posts 514 WHERE " . get_private_posts_cap_sql( 'post' ) . ' 515 GROUP BY post_author' 516 ); 517 518 foreach ( (array) $post_counts_query as $row ) { 519 $post_counts[ $row->post_author ] = $row->count; 520 } 521 } 522 523 foreach ( $authors as $author_id ) { 524 $posts = $post_counts[ $author_id ] ?? 0; 525 526 if ( ! $posts && $parsed_args['hide_empty'] ) { 527 continue; 528 } 529 530 $author = get_userdata( $author_id ); 531 532 if ( $parsed_args['exclude_admin'] && 'admin' === $author->display_name ) { 533 continue; 534 } 535 536 if ( $parsed_args['show_fullname'] && $author->first_name && $author->last_name ) { 537 $name = sprintf( 538 /* translators: 1: User's first name, 2: Last name. */ 539 _x( '%1$s %2$s', 'Display name based on first name and last name' ), 540 $author->first_name, 541 $author->last_name 542 ); 543 } else { 544 $name = $author->display_name; 545 } 546 547 if ( ! $parsed_args['html'] ) { 548 $return .= $name . ', '; 549 550 continue; // No need to go further to process HTML. 551 } 552 553 if ( 'list' === $parsed_args['style'] ) { 554 $return .= '<li>'; 555 } 556 557 $link = sprintf( 558 '<a href="%1$s">%2$s</a>', 559 esc_url( get_author_posts_url( $author->ID, $author->user_nicename ) ), 560 $name 561 ); 562 563 if ( ! empty( $parsed_args['feed_image'] ) || ! empty( $parsed_args['feed'] ) ) { 564 $link .= ' '; 565 if ( empty( $parsed_args['feed_image'] ) ) { 566 $link .= '('; 567 } 568 569 $link .= '<a href="' . get_author_feed_link( $author->ID, $parsed_args['feed_type'] ) . '"'; 570 571 $alt = ''; 572 if ( ! empty( $parsed_args['feed'] ) ) { 573 $alt = ' alt="' . esc_attr( $parsed_args['feed'] ) . '"'; 574 $name = $parsed_args['feed']; 575 } 576 577 $link .= '>'; 578 579 if ( ! empty( $parsed_args['feed_image'] ) ) { 580 $link .= '<img src="' . esc_url( $parsed_args['feed_image'] ) . '" style="border: none;"' . $alt . ' />'; 581 } else { 582 $link .= $name; 583 } 584 585 $link .= '</a>'; 586 587 if ( empty( $parsed_args['feed_image'] ) ) { 588 $link .= ')'; 589 } 590 } 591 592 if ( $parsed_args['optioncount'] ) { 593 $link .= ' (' . $posts . ')'; 594 } 595 596 $return .= $link; 597 $return .= ( 'list' === $parsed_args['style'] ) ? '</li>' : ', '; 598 } 599 600 $return = rtrim( $return, ', ' ); 601 602 if ( $parsed_args['echo'] ) { 603 echo $return; 604 } else { 605 return $return; 606 } 607 } 608 609 /** 610 * Determines whether this site has more than one author. 611 * 612 * Checks to see if more than one author has published posts. 613 * 614 * For more information on this and similar theme functions, check out 615 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 616 * Conditional Tags} article in the Theme Developer Handbook. 617 * 618 * @since 3.2.0 619 * 620 * @global wpdb $wpdb WordPress database abstraction object. 621 * 622 * @return bool Whether or not we have more than one author 623 */ 624 function is_multi_author() { 625 global $wpdb; 626 627 $is_multi_author = get_transient( 'is_multi_author' ); 628 if ( false === $is_multi_author ) { 629 $rows = (array) $wpdb->get_col( "SELECT DISTINCT post_author FROM $wpdb->posts WHERE post_type = 'post' AND post_status = 'publish' LIMIT 2" ); 630 $is_multi_author = 1 < count( $rows ) ? 1 : 0; 631 set_transient( 'is_multi_author', $is_multi_author ); 632 } 633 634 /** 635 * Filters whether the site has more than one author with published posts. 636 * 637 * @since 3.2.0 638 * 639 * @param bool $is_multi_author Whether $is_multi_author should evaluate as true. 640 */ 641 return apply_filters( 'is_multi_author', (bool) $is_multi_author ); 642 } 643 644 /** 645 * Helper function to clear the cache for number of authors. 646 * 647 * @since 3.2.0 648 * @access private 649 */ 650 function __clear_multi_author_cache() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionDoubleUnderscore,PHPCompatibility.FunctionNameRestrictions.ReservedFunctionNames.FunctionDoubleUnderscore 651 delete_transient( 'is_multi_author' ); 652 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Thu Sep 3 08:20:25 2026 | Cross-referenced by PHPXref |