| [ 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 = 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 */ 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 * 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 */ 238 function 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 */ 278 function 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 */ 289 function 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 */ 303 function 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 */ 318 function 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 */ 351 function 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 */ 369 function 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 */ 439 function 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 */ 607 function 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 */ 633 function __clear_multi_author_cache() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionDoubleUnderscore,PHPCompatibility.FunctionNameRestrictions.ReservedFunctionNames.FunctionDoubleUnderscore 634 delete_transient( 'is_multi_author' ); 635 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Sat Oct 25 08:20:05 2025 | Cross-referenced by PHPXref |