/wp-includes/author-template.php

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