author-template.php 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570
  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. * Retrieve the author of the current post.
  14. *
  15. * @since 1.5.0
  16. *
  17. * @global object $authordata The current author's DB object.
  18. *
  19. * @param string $deprecated Deprecated.
  20. * @return string|null The author's display name.
  21. */
  22. function get_the_author( $deprecated = '' ) {
  23. global $authordata;
  24. if ( ! empty( $deprecated ) ) {
  25. _deprecated_argument( __FUNCTION__, '2.1.0' );
  26. }
  27. /**
  28. * Filters the display name of the current post's author.
  29. *
  30. * @since 2.9.0
  31. *
  32. * @param string $authordata->display_name The author's display name.
  33. */
  34. return apply_filters( 'the_author', is_object( $authordata ) ? $authordata->display_name : null );
  35. }
  36. /**
  37. * Display the name of the author of the current post.
  38. *
  39. * The behavior of this function is based off of old functionality predating
  40. * get_the_author(). This function is not deprecated, but is designed to echo
  41. * the value from get_the_author() and as an result of any old theme that might
  42. * still use the old behavior will also pass the value from get_the_author().
  43. *
  44. * The normal, expected behavior of this function is to echo the author and not
  45. * return it. However, backward compatibility has to be maintained.
  46. *
  47. * @since 0.71
  48. * @see get_the_author()
  49. * @link https://developer.wordpress.org/reference/functions/the_author/
  50. *
  51. * @param string $deprecated Deprecated.
  52. * @param bool $deprecated_echo Deprecated. Use get_the_author(). Echo the string or return it.
  53. * @return string|null The author's display name, from get_the_author().
  54. */
  55. function the_author( $deprecated = '', $deprecated_echo = true ) {
  56. if ( ! empty( $deprecated ) ) {
  57. _deprecated_argument( __FUNCTION__, '2.1.0' );
  58. }
  59. if ( true !== $deprecated_echo ) {
  60. _deprecated_argument(
  61. __FUNCTION__,
  62. '1.5.0',
  63. sprintf(
  64. /* translators: %s: get_the_author() */
  65. __( 'Use %s instead if you do not want the value echoed.' ),
  66. '<code>get_the_author()</code>'
  67. )
  68. );
  69. }
  70. if ( $deprecated_echo ) {
  71. echo get_the_author();
  72. }
  73. return get_the_author();
  74. }
  75. /**
  76. * Retrieve the author who last edited the current post.
  77. *
  78. * @since 2.8.0
  79. *
  80. * @return string|void The author's display name.
  81. */
  82. function get_the_modified_author() {
  83. $last_id = get_post_meta( get_post()->ID, '_edit_last', true );
  84. if ( $last_id ) {
  85. $last_user = get_userdata( $last_id );
  86. /**
  87. * Filters the display name of the author who last edited the current post.
  88. *
  89. * @since 2.8.0
  90. *
  91. * @param string $last_user->display_name The author's display name.
  92. */
  93. return apply_filters( 'the_modified_author', $last_user->display_name );
  94. }
  95. }
  96. /**
  97. * Display the name of the author who last edited the current post,
  98. * if the author's ID is available.
  99. *
  100. * @since 2.8.0
  101. *
  102. * @see get_the_author()
  103. */
  104. function the_modified_author() {
  105. echo get_the_modified_author();
  106. }
  107. /**
  108. * Retrieves the requested data of the author of the current post.
  109. *
  110. * Valid values for the `$field` parameter include:
  111. *
  112. * - admin_color
  113. * - aim
  114. * - comment_shortcuts
  115. * - description
  116. * - display_name
  117. * - first_name
  118. * - ID
  119. * - jabber
  120. * - last_name
  121. * - nickname
  122. * - plugins_last_view
  123. * - plugins_per_page
  124. * - rich_editing
  125. * - syntax_highlighting
  126. * - user_activation_key
  127. * - user_description
  128. * - user_email
  129. * - user_firstname
  130. * - user_lastname
  131. * - user_level
  132. * - user_login
  133. * - user_nicename
  134. * - user_pass
  135. * - user_registered
  136. * - user_status
  137. * - user_url
  138. * - yim
  139. *
  140. * @since 2.8.0
  141. *
  142. * @global object $authordata The current author's DB object.
  143. *
  144. * @param string $field Optional. The user field to retrieve. Default empty.
  145. * @param int|false $user_id Optional. User ID.
  146. * @return string The author's field from the current author's DB object, otherwise an empty string.
  147. */
  148. function get_the_author_meta( $field = '', $user_id = false ) {
  149. $original_user_id = $user_id;
  150. if ( ! $user_id ) {
  151. global $authordata;
  152. $user_id = isset( $authordata->ID ) ? $authordata->ID : 0;
  153. } else {
  154. $authordata = get_userdata( $user_id );
  155. }
  156. if ( in_array( $field, array( 'login', 'pass', 'nicename', 'email', 'url', 'registered', 'activation_key', 'status' ) ) ) {
  157. $field = 'user_' . $field;
  158. }
  159. $value = isset( $authordata->$field ) ? $authordata->$field : '';
  160. /**
  161. * Filters the value of the requested user metadata.
  162. *
  163. * The filter name is dynamic and depends on the $field parameter of the function.
  164. *
  165. * @since 2.8.0
  166. * @since 4.3.0 The `$original_user_id` parameter was added.
  167. *
  168. * @param string $value The value of the metadata.
  169. * @param int $user_id The user ID for the value.
  170. * @param int|false $original_user_id The original user ID, as passed to the function.
  171. */
  172. return apply_filters( "get_the_author_{$field}", $value, $user_id, $original_user_id );
  173. }
  174. /**
  175. * Outputs the field from the user's DB object. Defaults to current post's author.
  176. *
  177. * @since 2.8.0
  178. *
  179. * @param string $field Selects the field of the users record. See get_the_author_meta()
  180. * for the list of possible fields.
  181. * @param int|false $user_id Optional. User ID.
  182. *
  183. * @see get_the_author_meta()
  184. */
  185. function the_author_meta( $field = '', $user_id = false ) {
  186. $author_meta = get_the_author_meta( $field, $user_id );
  187. /**
  188. * The value of the requested user metadata.
  189. *
  190. * The filter name is dynamic and depends on the $field parameter of the function.
  191. *
  192. * @since 2.8.0
  193. *
  194. * @param string $author_meta The value of the metadata.
  195. * @param int|false $user_id The user ID.
  196. */
  197. echo apply_filters( "the_author_{$field}", $author_meta, $user_id );
  198. }
  199. /**
  200. * Retrieve either author's link or author's name.
  201. *
  202. * If the author has a home page set, return an HTML link, otherwise just return the
  203. * author's name.
  204. *
  205. * @since 3.0.0
  206. *
  207. * @return string|null An HTML link if the author's url exist in user meta,
  208. * else the result of get_the_author().
  209. */
  210. function get_the_author_link() {
  211. if ( get_the_author_meta( 'url' ) ) {
  212. return sprintf(
  213. '<a href="%1$s" title="%2$s" rel="author external">%3$s</a>',
  214. esc_url( get_the_author_meta( 'url' ) ),
  215. /* translators: %s: Author's display name. */
  216. esc_attr( sprintf( __( 'Visit %s&#8217;s website' ), get_the_author() ) ),
  217. get_the_author()
  218. );
  219. } else {
  220. return get_the_author();
  221. }
  222. }
  223. /**
  224. * Display either author's link or author's name.
  225. *
  226. * If the author has a home page set, echo an HTML link, otherwise just echo the
  227. * author's name.
  228. *
  229. * @link https://developer.wordpress.org/reference/functions/the_author_link/
  230. *
  231. * @since 2.1.0
  232. */
  233. function the_author_link() {
  234. echo get_the_author_link();
  235. }
  236. /**
  237. * Retrieve the number of posts by the author of the current post.
  238. *
  239. * @since 1.5.0
  240. *
  241. * @return int The number of posts by the author.
  242. */
  243. function get_the_author_posts() {
  244. $post = get_post();
  245. if ( ! $post ) {
  246. return 0;
  247. }
  248. return count_user_posts( $post->post_author, $post->post_type );
  249. }
  250. /**
  251. * Display the number of posts by the author of the current post.
  252. *
  253. * @link https://developer.wordpress.org/reference/functions/the_author_posts/
  254. * @since 0.71
  255. */
  256. function the_author_posts() {
  257. echo get_the_author_posts();
  258. }
  259. /**
  260. * Retrieves an HTML link to the author page of the current post's author.
  261. *
  262. * Returns an HTML-formatted link using get_author_posts_url().
  263. *
  264. * @since 4.4.0
  265. *
  266. * @global object $authordata The current author's DB object.
  267. *
  268. * @return string An HTML link to the author page, or an empty string if $authordata isn't defined.
  269. */
  270. function get_the_author_posts_link() {
  271. global $authordata;
  272. if ( ! is_object( $authordata ) ) {
  273. return '';
  274. }
  275. $link = sprintf(
  276. '<a href="%1$s" title="%2$s" rel="author">%3$s</a>',
  277. esc_url( get_author_posts_url( $authordata->ID, $authordata->user_nicename ) ),
  278. /* translators: %s: Author's display name. */
  279. esc_attr( sprintf( __( 'Posts by %s' ), get_the_author() ) ),
  280. get_the_author()
  281. );
  282. /**
  283. * Filters the link to the author page of the author of the current post.
  284. *
  285. * @since 2.9.0
  286. *
  287. * @param string $link HTML link.
  288. */
  289. return apply_filters( 'the_author_posts_link', $link );
  290. }
  291. /**
  292. * Displays an HTML link to the author page of the current post's author.
  293. *
  294. * @since 1.2.0
  295. * @since 4.4.0 Converted into a wrapper for get_the_author_posts_link()
  296. *
  297. * @param string $deprecated Unused.
  298. */
  299. function the_author_posts_link( $deprecated = '' ) {
  300. if ( ! empty( $deprecated ) ) {
  301. _deprecated_argument( __FUNCTION__, '2.1.0' );
  302. }
  303. echo get_the_author_posts_link();
  304. }
  305. /**
  306. * Retrieve the URL to the author page for the user with the ID provided.
  307. *
  308. * @since 2.1.0
  309. *
  310. * @global WP_Rewrite $wp_rewrite WordPress rewrite component.
  311. *
  312. * @param int $author_id Author ID.
  313. * @param string $author_nicename Optional. The author's nicename (slug). Default empty.
  314. * @return string The URL to the author's page.
  315. */
  316. function get_author_posts_url( $author_id, $author_nicename = '' ) {
  317. global $wp_rewrite;
  318. $auth_ID = (int) $author_id;
  319. $link = $wp_rewrite->get_author_permastruct();
  320. if ( empty( $link ) ) {
  321. $file = home_url( '/' );
  322. $link = $file . '?author=' . $auth_ID;
  323. } else {
  324. if ( '' == $author_nicename ) {
  325. $user = get_userdata( $author_id );
  326. if ( ! empty( $user->user_nicename ) ) {
  327. $author_nicename = $user->user_nicename;
  328. }
  329. }
  330. $link = str_replace( '%author%', $author_nicename, $link );
  331. $link = home_url( user_trailingslashit( $link ) );
  332. }
  333. /**
  334. * Filters the URL to the author's page.
  335. *
  336. * @since 2.1.0
  337. *
  338. * @param string $link The URL to the author's page.
  339. * @param int $author_id The author's id.
  340. * @param string $author_nicename The author's nice name.
  341. */
  342. $link = apply_filters( 'author_link', $link, $author_id, $author_nicename );
  343. return $link;
  344. }
  345. /**
  346. * List all the authors of the site, with several options available.
  347. *
  348. * @link https://developer.wordpress.org/reference/functions/wp_list_authors/
  349. *
  350. * @since 1.2.0
  351. *
  352. * @global wpdb $wpdb WordPress database abstraction object.
  353. *
  354. * @param string|array $args {
  355. * Optional. Array or string of default arguments.
  356. *
  357. * @type string $orderby How to sort the authors. Accepts 'nicename', 'email', 'url', 'registered',
  358. * 'user_nicename', 'user_email', 'user_url', 'user_registered', 'name',
  359. * 'display_name', 'post_count', 'ID', 'meta_value', 'user_login'. Default 'name'.
  360. * @type string $order Sorting direction for $orderby. Accepts 'ASC', 'DESC'. Default 'ASC'.
  361. * @type int $number Maximum authors to return or display. Default empty (all authors).
  362. * @type bool $optioncount Show the count in parenthesis next to the author's name. Default false.
  363. * @type bool $exclude_admin Whether to exclude the 'admin' account, if it exists. Default true.
  364. * @type bool $show_fullname Whether to show the author's full name. Default false.
  365. * @type bool $hide_empty Whether to hide any authors with no posts. Default true.
  366. * @type string $feed If not empty, show a link to the author's feed and use this text as the alt
  367. * parameter of the link. Default empty.
  368. * @type string $feed_image If not empty, show a link to the author's feed and use this image URL as
  369. * clickable anchor. Default empty.
  370. * @type string $feed_type The feed type to link to. Possible values include 'rss2', 'atom'.
  371. * Default is the value of get_default_feed().
  372. * @type bool $echo Whether to output the result or instead return it. Default true.
  373. * @type string $style If 'list', each author is wrapped in an `<li>` element, otherwise the authors
  374. * will be separated by commas.
  375. * @type bool $html Whether to list the items in HTML form or plaintext. Default true.
  376. * @type array|string $exclude Array or comma/space-separated list of author IDs to exclude. Default empty.
  377. * @type array|string $include Array or comma/space-separated list of author IDs to include. Default empty.
  378. * }
  379. * @return string|void The output, if echo is set to false.
  380. */
  381. function wp_list_authors( $args = '' ) {
  382. global $wpdb;
  383. $defaults = array(
  384. 'orderby' => 'name',
  385. 'order' => 'ASC',
  386. 'number' => '',
  387. 'optioncount' => false,
  388. 'exclude_admin' => true,
  389. 'show_fullname' => false,
  390. 'hide_empty' => true,
  391. 'feed' => '',
  392. 'feed_image' => '',
  393. 'feed_type' => '',
  394. 'echo' => true,
  395. 'style' => 'list',
  396. 'html' => true,
  397. 'exclude' => '',
  398. 'include' => '',
  399. );
  400. $args = wp_parse_args( $args, $defaults );
  401. $return = '';
  402. $query_args = wp_array_slice_assoc( $args, array( 'orderby', 'order', 'number', 'exclude', 'include' ) );
  403. $query_args['fields'] = 'ids';
  404. $authors = get_users( $query_args );
  405. $author_count = array();
  406. foreach ( (array) $wpdb->get_results( "SELECT DISTINCT post_author, COUNT(ID) AS count FROM $wpdb->posts WHERE " . get_private_posts_cap_sql( 'post' ) . ' GROUP BY post_author' ) as $row ) {
  407. $author_count[ $row->post_author ] = $row->count;
  408. }
  409. foreach ( $authors as $author_id ) {
  410. $posts = isset( $author_count[ $author_id ] ) ? $author_count[ $author_id ] : 0;
  411. if ( ! $posts && $args['hide_empty'] ) {
  412. continue;
  413. }
  414. $author = get_userdata( $author_id );
  415. if ( $args['exclude_admin'] && 'admin' === $author->display_name ) {
  416. continue;
  417. }
  418. if ( $args['show_fullname'] && $author->first_name && $author->last_name ) {
  419. $name = "$author->first_name $author->last_name";
  420. } else {
  421. $name = $author->display_name;
  422. }
  423. if ( ! $args['html'] ) {
  424. $return .= $name . ', ';
  425. continue; // No need to go further to process HTML.
  426. }
  427. if ( 'list' == $args['style'] ) {
  428. $return .= '<li>';
  429. }
  430. $link = sprintf(
  431. '<a href="%1$s" title="%2$s">%3$s</a>',
  432. get_author_posts_url( $author->ID, $author->user_nicename ),
  433. /* translators: %s: Author's display name. */
  434. esc_attr( sprintf( __( 'Posts by %s' ), $author->display_name ) ),
  435. $name
  436. );
  437. if ( ! empty( $args['feed_image'] ) || ! empty( $args['feed'] ) ) {
  438. $link .= ' ';
  439. if ( empty( $args['feed_image'] ) ) {
  440. $link .= '(';
  441. }
  442. $link .= '<a href="' . get_author_feed_link( $author->ID, $args['feed_type'] ) . '"';
  443. $alt = '';
  444. if ( ! empty( $args['feed'] ) ) {
  445. $alt = ' alt="' . esc_attr( $args['feed'] ) . '"';
  446. $name = $args['feed'];
  447. }
  448. $link .= '>';
  449. if ( ! empty( $args['feed_image'] ) ) {
  450. $link .= '<img src="' . esc_url( $args['feed_image'] ) . '" style="border: none;"' . $alt . ' />';
  451. } else {
  452. $link .= $name;
  453. }
  454. $link .= '</a>';
  455. if ( empty( $args['feed_image'] ) ) {
  456. $link .= ')';
  457. }
  458. }
  459. if ( $args['optioncount'] ) {
  460. $link .= ' (' . $posts . ')';
  461. }
  462. $return .= $link;
  463. $return .= ( 'list' == $args['style'] ) ? '</li>' : ', ';
  464. }
  465. $return = rtrim( $return, ', ' );
  466. if ( ! $args['echo'] ) {
  467. return $return;
  468. }
  469. echo $return;
  470. }
  471. /**
  472. * Determines whether this site has more than one author.
  473. *
  474. * Checks to see if more than one author has published posts.
  475. *
  476. * For more information on this and similar theme functions, check out
  477. * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
  478. * Conditional Tags} article in the Theme Developer Handbook.
  479. *
  480. * @since 3.2.0
  481. *
  482. * @global wpdb $wpdb WordPress database abstraction object.
  483. *
  484. * @return bool Whether or not we have more than one author
  485. */
  486. function is_multi_author() {
  487. global $wpdb;
  488. $is_multi_author = get_transient( 'is_multi_author' );
  489. if ( false === $is_multi_author ) {
  490. $rows = (array) $wpdb->get_col( "SELECT DISTINCT post_author FROM $wpdb->posts WHERE post_type = 'post' AND post_status = 'publish' LIMIT 2" );
  491. $is_multi_author = 1 < count( $rows ) ? 1 : 0;
  492. set_transient( 'is_multi_author', $is_multi_author );
  493. }
  494. /**
  495. * Filters whether the site has more than one author with published posts.
  496. *
  497. * @since 3.2.0
  498. *
  499. * @param bool $is_multi_author Whether $is_multi_author should evaluate as true.
  500. */
  501. return apply_filters( 'is_multi_author', (bool) $is_multi_author );
  502. }
  503. /**
  504. * Helper function to clear the cache for number of authors.
  505. *
  506. * @since 3.2.0
  507. * @access private
  508. */
  509. function __clear_multi_author_cache() { //phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionDoubleUnderscore,PHPCompatibility.FunctionNameRestrictions.ReservedFunctionNames.FunctionDoubleUnderscore
  510. delete_transient( 'is_multi_author' );
  511. }