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