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