PluginProbe
bbPress / 2.6.17
bbPress v2.6.17
2.6.17 trunk 2.0 2.0-beta-1 2.0-beta-2b 2.0-beta-3 2.0-beta-3b 2.0-rc-2 2.0-rc-3 2.0-rc-4 2.0-rc-5 2.0.1 2.0.2 2.0.3 2.1 2.1-beta-1 2.1-rc1 2.1-rc2 2.1-rc3 2.1-rc4 2.1.1 2.1.2 2.1.3 2.2 2.2.1 All 72 releases
← All changes | includes/forums/functions.php +148 -120 trunk → 2.6.17 View file →
@@ -17,12 +17,10 @@
17 17 * for the forum to function properly.
18 18 *
19 19 * @since 2.0.0 bbPress (r3349)
20 20 *
21 - * @param array $forum_data Forum post data.
22 - * @param array $forum_meta Forum meta data.
23 - *
24 - * @return int|false Forum ID on success, false on failure.
21 + * @param array $forum_data Forum post data
22 + * @param array $forum_meta Forum meta data
25 23 */
26 24 function bbp_insert_forum( $forum_data = array(), $forum_meta = array() ) {
27 25
28 26 // Forum
@@ -121,11 +119,11 @@
121 119
122 120 /** Post Form Handlers ********************************************************/
123 121
124 122 /**
125 - * Handles the front end forum submission.
123 + * Handles the front end forum submission
126 124 *
127 - * @param string $action The requested action to compare this function to.
125 + * @param string $action The requested action to compare this function to
128 126 */
129 127 function bbp_new_forum_handler( $action = '' ) {
130 128
131 129 // Bail if action is not bbp-new-forum
@@ -197,10 +195,10 @@
197 195 }
198 196
199 197 /** Forum Parent **********************************************************/
200 198
201 - // Forum parent is expected for theme-side submissions
202 - if ( ! empty( $_POST['bbp_forum_parent_id'] ) && is_numeric( $_POST['bbp_forum_parent_id'] ) ) {
199 + // Forum parent was passed (the norm)
200 + if ( ! empty( $_POST['bbp_forum_parent_id'] ) ) {
203 201 $forum_parent_id = bbp_get_forum_id( $_POST['bbp_forum_parent_id'] );
204 202 }
205 203
206 204 // Filter and sanitize
@@ -205,28 +203,34 @@
205 203
206 204 // Filter and sanitize
207 205 $forum_parent_id = apply_filters( 'bbp_new_forum_pre_parent_id', $forum_parent_id );
208 206
209 - // Forum parent was not passed (required for theme-side BuddyPress support)
207 + // No forum parent was passed (should never happen)
210 208 if ( empty( $forum_parent_id ) ) {
211 209 bbp_add_error( 'bbp_new_forum_missing_parent', __( '<strong>Error</strong>: Your forum must have a parent.', 'bbpress' ) );
212 210
213 - // Forum parent exists
211 + // Forum exists
214 212 } elseif ( ! empty( $forum_parent_id ) ) {
215 213
216 - // Forum parent not editable by user
217 - if ( ! current_user_can( 'edit_forum', $forum_parent_id ) ) {
214 + // Forum is a category
215 + if ( bbp_is_forum_category( $forum_parent_id ) ) {
216 + bbp_add_error( 'bbp_new_forum_forum_category', __( '<strong>Error</strong>: This forum is a category. No forums can be created in this forum.', 'bbpress' ) );
217 + }
218 218
219 - // Forum parent is closed
220 - if ( bbp_is_forum_closed( $forum_parent_id ) ) {
221 - bbp_add_error( 'bbp_new_forum_forum_closed', __( '<strong>Error</strong>: This forum is closed to new forums.', 'bbpress' ) );
222 - }
219 + // Forum is closed and user cannot access
220 + if ( bbp_is_forum_closed( $forum_parent_id ) && ! current_user_can( 'edit_forum', $forum_parent_id ) ) {
221 + bbp_add_error( 'bbp_new_forum_forum_closed', __( '<strong>Error</strong>: This forum has been closed to new forums.', 'bbpress' ) );
223 222 }
224 223
225 - // Forum parent not readable by user
226 - if ( ! current_user_can( 'read_forum', $forum_parent_id ) ) {
227 - bbp_add_error( 'bbp_new_forum_forum_read', __( '<strong>Error</strong>: You do not have the capability to create new forums in this forum.', 'bbpress' ) );
224 + // Forum is private and user cannot access
225 + if ( bbp_is_forum_private( $forum_parent_id ) && ! current_user_can( 'read_forum', $forum_parent_id ) ) {
226 + bbp_add_error( 'bbp_new_forum_forum_private', __( '<strong>Error</strong>: This forum is private and you do not have the capability to read or create new forums in it.', 'bbpress' ) );
228 227 }
228 +
229 + // Forum is hidden and user cannot access
230 + if ( bbp_is_forum_hidden( $forum_parent_id ) && ! current_user_can( 'read_forum', $forum_parent_id ) ) {
231 + bbp_add_error( 'bbp_new_forum_forum_hidden', __( '<strong>Error</strong>: This forum is hidden and you do not have the capability to read or create new forums in it.', 'bbpress' ) );
232 + }
229 233 }
230 234
231 235 /** Forum Flooding ********************************************************/
232 236
@@ -375,14 +379,14 @@
375 379
376 380 } elseif ( is_wp_error( $forum_id ) ) {
377 381 bbp_add_error(
378 382 'bbp_forum_error',
379 - sprintf(
380 - /* translators: %s: Error message */
381 - esc_html__( '<strong>Error</strong>: The following problem(s) occurred: %s', 'bbpress' ),
383 + sprintf( /* translators: %s: Error message(s) */ __( '<strong>Error</strong>: The following problem(s) occurred: %s', 'bbpress' ),
382 384 $forum_id->get_error_message()
383 385 )
384 386 );
387 +
388 + // Generic error
385 389 } else {
386 390 bbp_add_error( 'bbp_forum_error', __( '<strong>Error</strong>: The forum was not created.', 'bbpress' ) );
387 391 }
388 392 }
@@ -387,11 +391,11 @@
387 391 }
388 392 }
389 393
390 394 /**
391 - * Handles the front end edit forum submission.
395 + * Handles the front end edit forum submission
392 396 *
393 - * @param string $action The requested action to compare this function to.
397 + * @param string $action The requested action to compare this function to
394 398 */
395 399 function bbp_edit_forum_handler( $action = '' ) {
396 400
397 401 // Bail if action is not bbp-edit-forum
@@ -449,9 +453,9 @@
449 453 $current_parent_forum_id = bbp_get_forum_parent_id( $forum_id );
450 454
451 455 // Only users who can assign forum moderators can change forum structure
452 456 if ( current_user_can( 'assign_moderators' ) ) {
453 - $forum_parent_id = ( ! empty( $_POST['bbp_forum_parent_id'] ) && is_numeric( $_POST['bbp_forum_parent_id'] ) )
457 + $forum_parent_id = ! empty( $_POST['bbp_forum_parent_id'] )
454 458 ? bbp_get_forum_id( $_POST['bbp_forum_parent_id'] )
455 459 : 0;
456 460 } else {
457 461 $forum_parent_id = $current_parent_forum_id;
@@ -456,23 +460,24 @@
456 460 } else {
457 461 $forum_parent_id = $current_parent_forum_id;
458 462 }
459 463
460 - // Forum parent exists
464 + // Forum exists
461 465 if ( ! empty( $forum_parent_id ) && ( $forum_parent_id !== $current_parent_forum_id ) ) {
462 466
463 - // Forum parent not editable by user
464 - if ( ! current_user_can( 'edit_forum', $forum_parent_id ) ) {
467 + // Forum is closed and user cannot access
468 + if ( bbp_is_forum_closed( $forum_parent_id ) && ! current_user_can( 'edit_forum', $forum_parent_id ) ) {
469 + bbp_add_error( 'bbp_edit_forum_forum_closed', __( '<strong>Error</strong>: This forum has been closed to new forums.', 'bbpress' ) );
470 + }
465 471
466 - // Forum is closed
467 - if ( bbp_is_forum_closed( $forum_parent_id ) ) {
468 - bbp_add_error( 'bbp_edit_forum_forum_closed', __( '<strong>Error</strong>: This forum is closed to new forums.', 'bbpress' ) );
469 - }
472 + // Forum is private and user cannot access
473 + if ( bbp_is_forum_private( $forum_parent_id ) && ! current_user_can( 'read_forum', $forum_parent_id ) ) {
474 + bbp_add_error( 'bbp_edit_forum_forum_private', __( '<strong>Error</strong>: This forum is private and you do not have the capability to read or create new forums in it.', 'bbpress' ) );
470 475 }
471 476
472 - // Forum parent not readable by user
473 - if ( ! current_user_can( 'read_forum', $forum_parent_id ) ) {
474 - bbp_add_error( 'bbp_edit_forum_forum_read', __( '<strong>Error</strong>: You do not have the capability to create new forums in this forum.', 'bbpress' ) );
477 + // Forum is hidden and user cannot access
478 + if ( bbp_is_forum_hidden( $forum_parent_id ) && ! current_user_can( 'read_forum', $forum_parent_id ) ) {
479 + bbp_add_error( 'bbp_edit_forum_forum_hidden', __( '<strong>Error</strong>: This forum is hidden and you do not have the capability to read or create new forums in it.', 'bbpress' ) );
475 480 }
476 481 }
477 482
478 483 /** Forum Title ***********************************************************/
@@ -638,11 +643,11 @@
638 643 bbp_add_error(
639 644 'bbp_forum_error',
640 645 sprintf(
641 646 /* translators: %s: Error message */
642 - __( '<strong>Error</strong>: The following problem(s) have been found with your forum: %s Please try again.', 'bbpress' )
643 - ),
644 - $append_error
647 + __( '<strong>Error</strong>: The following problem(s) have been found with your forum: %sPlease try again.', 'bbpress' ),
648 + $append_error
649 + )
645 650 );
646 651 }
647 652 }
648 653
@@ -648,9 +653,9 @@
648 653
649 654 /**
650 655 * Filter forum data submitted through the WordPress administration area.
651 656 *
652 - * @since 2.7.0 bbPress
657 + * @since 2.6.17 bbPress
653 658 *
654 659 * @param array $data Sanitized post data.
655 660 * @param array $postarr Raw post data.
656 661 * @return array Filtered post data.
@@ -683,14 +688,14 @@
683 688 return $data;
684 689 }
685 690
686 691 /**
687 - * Handle the saving of core forum metadata (Status, Visibility, and Type).
692 + * Handle the saving of core forum metadata (Status, Visibility, and Type)
688 693 *
689 694 * @since 2.1.0 bbPress (r3678)
690 695 *
691 - * @param int $forum_id.
692 - * @return If forum ID is empty.
696 + * @param int $forum_id
697 + * @return If forum ID is empty
693 698 */
694 699 function bbp_save_forum_extras( $forum_id = 0 ) {
695 700
696 701 // Validate the forum ID
@@ -755,15 +760,15 @@
755 760 break;
756 761 }
757 762
758 763 /**
759 - * Allow custom forum visibility save actions.
764 + * Allow custom forum visibility save actions
760 765 *
761 766 * @since 2.6.0 bbPress (r5855)
762 767 *
763 - * @param int $forum_id The forum ID.
764 - * @param string $old_visibility The current forum visibility.
765 - * @param string $new_visibility The new forum visibility.
768 + * @param int $forum_id The forum ID
769 + * @param string $old_visibility The current forum visibility
770 + * @param string $new_visibility The new forum visibility
766 771 */
767 772 do_action( 'bbp_update_forum_visibility', $forum_id, $old_visibility, $new_visibility );
768 773 }
769 774
@@ -798,14 +803,14 @@
798 803
799 804 /** Forum Open/Close **********************************************************/
800 805
801 806 /**
802 - * Closes a forum.
807 + * Closes a forum
803 808 *
804 809 * @since 2.0.0 bbPress (r2746)
805 810 *
806 - * @param int $forum_id forum id.
807 - * @return mixed False or {@link WP_Error} on failure, forum id on success.
811 + * @param int $forum_id forum id
812 + * @return mixed False or {@link WP_Error} on failure, forum id on success
808 813 */
809 814 function bbp_close_forum( $forum_id = 0 ) {
810 815
811 816 $forum_id = bbp_get_forum_id( $forum_id );
@@ -819,14 +824,14 @@
819 824 return $forum_id;
820 825 }
821 826
822 827 /**
823 - * Opens a forum.
828 + * Opens a forum
824 829 *
825 830 * @since 2.0.0 bbPress (r2746)
826 831 *
827 - * @param int $forum_id forum id.
828 - * @return mixed False or {@link WP_Error} on failure, forum id on success.
832 + * @param int $forum_id forum id
833 + * @return mixed False or {@link WP_Error} on failure, forum id on success
829 834 */
830 835 function bbp_open_forum( $forum_id = 0 ) {
831 836
832 837 $forum_id = bbp_get_forum_id( $forum_id );
@@ -842,14 +847,14 @@
842 847
843 848 /** Forum Type ****************************************************************/
844 849
845 850 /**
846 - * Make the forum a category.
851 + * Make the forum a category
847 852 *
848 853 * @since 2.0.0 bbPress (r2746)
849 854 *
850 - * @param int $forum_id Optional. Forum id.
851 - * @return bool False on failure, true on success.
855 + * @param int $forum_id Optional. Forum id
856 + * @return bool False on failure, true on success
852 857 */
853 858 function bbp_categorize_forum( $forum_id = 0 ) {
854 859
855 860 $forum_id = bbp_get_forum_id( $forum_id );
@@ -863,14 +868,14 @@
863 868 return $forum_id;
864 869 }
865 870
866 871 /**
867 - * Remove the category status from a forum.
872 + * Remove the category status from a forum
868 873 *
869 874 * @since 2.0.0 bbPress (r2746)
870 875 *
871 - * @param int $forum_id Optional. Forum id.
872 - * @return bool False on failure, true on success.
876 + * @param int $forum_id Optional. Forum id
877 + * @return bool False on failure, true on success
873 878 */
874 879 function bbp_normalize_forum( $forum_id = 0 ) {
875 880
876 881 $forum_id = bbp_get_forum_id( $forum_id );
@@ -886,14 +891,14 @@
886 891
887 892 /** Forum Visibility **********************************************************/
888 893
889 894 /**
890 - * Mark the forum as public.
895 + * Mark the forum as public
891 896 *
892 897 * @since 2.0.0 bbPress (r2746)
893 898 *
894 - * @param int $forum_id Optional. Forum id.
895 - * @return bool False on failure, true on success.
899 + * @param int $forum_id Optional. Forum id
900 + * @return bool False on failure, true on success
896 901 */
897 902 function bbp_publicize_forum( $forum_id = 0, $current_visibility = '' ) {
898 903
899 904 $forum_id = bbp_get_forum_id( $forum_id );
@@ -943,14 +948,14 @@
943 948 return $forum_id;
944 949 }
945 950
946 951 /**
947 - * Mark the forum as private.
952 + * Mark the forum as private
948 953 *
949 954 * @since 2.0.0 bbPress (r2746)
950 955 *
951 - * @param int $forum_id Optional. Forum id.
952 - * @return bool False on failure, true on success.
956 + * @param int $forum_id Optional. Forum id
957 + * @return bool False on failure, true on success
953 958 */
954 959 function bbp_privatize_forum( $forum_id = 0, $current_visibility = '' ) {
955 960
956 961 $forum_id = bbp_get_forum_id( $forum_id );
@@ -992,14 +997,14 @@
992 997 return $forum_id;
993 998 }
994 999
995 1000 /**
996 - * Mark the forum as hidden.
1001 + * Mark the forum as hidden
997 1002 *
998 1003 * @since 2.0.0 bbPress (r2996)
999 1004 *
1000 - * @param int $forum_id Optional. Forum id.
1001 - * @return bool False on failure, true on success.
1005 + * @param int $forum_id Optional. Forum id
1006 + * @return bool False on failure, true on success
1002 1007 */
1003 1008 function bbp_hide_forum( $forum_id = 0, $current_visibility = '' ) {
1004 1009
1005 1010 $forum_id = bbp_get_forum_id( $forum_id );
@@ -1041,13 +1046,13 @@
1041 1046 return $forum_id;
1042 1047 }
1043 1048
1044 1049 /**
1045 - * Re-caches the private and hidden forums.
1050 + * Recaches the private and hidden forums
1046 1051 *
1047 1052 * @since 2.4.0 bbPress (r5017)
1048 1053 *
1049 - * @return array An array of the status code and the message.
1054 + * @return array An array of the status code and the message
1050 1055 */
1051 1056 function bbp_repair_forum_visibility() {
1052 1057
1053 1058 // First, delete everything.
@@ -1121,13 +1126,13 @@
1121 1126
1122 1127 /** Subscriptions *************************************************************/
1123 1128
1124 1129 /**
1125 - * Remove a deleted forum from all user subscriptions.
1130 + * Remove a deleted forum from all user subscriptions
1126 1131 *
1127 1132 * @since 2.5.0 bbPress (r5156)
1128 1133 *
1129 - * @param int $forum_id Get the forum ID to remove.
1134 + * @param int $forum_id Get the forum ID to remove
1130 1135 */
1131 1136 function bbp_remove_forum_from_all_subscriptions( $forum_id = 0 ) {
1132 1137
1133 1138 // Subscriptions are not active
@@ -1147,9 +1152,9 @@
1147 1152
1148 1153 /** Count Bumpers *************************************************************/
1149 1154
1150 1155 /**
1151 - * Bump the total topic count of a forum.
1156 + * Bump the total topic count of a forum
1152 1157 *
1153 1158 * @since 2.1.0 bbPress (r3825)
1154 1159 * @since 2.6.17 Use atomic metadata writes and non-negative counts.
1155 1160 *
@@ -1212,8 +1217,9 @@
1212 1217 *
1213 1218 * @since 2.6.0 bbPress (r6036)
1214 1219 *
1215 1220 * @param int $forum_id The forum id.
1221 + * @return void
1216 1222 */
1217 1223 function bbp_increase_forum_topic_count( $forum_id = 0 ) {
1218 1224
1219 1225 // Bail early if no id is passed.
@@ -1242,8 +1248,10 @@
1242 1248 *
1243 1249 * @since 2.6.0 bbPress (r6036)
1244 1250 *
1245 1251 * @param int $forum_id The forum id.
1252 + *
1253 + * @return void
1246 1254 */
1247 1255 function bbp_decrease_forum_topic_count( $forum_id = 0 ) {
1248 1256
1249 1257 // Bail early if no id is passed.
@@ -1267,9 +1275,9 @@
1267 1275 bbp_bump_forum_topic_count( $forum_id, -1 );
1268 1276 }
1269 1277
1270 1278 /**
1271 - * Bump the total topic count of a forum.
1279 + * Bump the total topic count of a forum
1272 1280 *
1273 1281 * @since 2.1.0 bbPress (r3825)
1274 1282 * @since 2.6.17 Use atomic metadata writes and non-negative counts.
1275 1283 *
@@ -1332,8 +1340,10 @@
1332 1340 *
1333 1341 * @since 2.6.0 bbPress (r6036)
1334 1342 *
1335 1343 * @param int $forum_id The forum id.
1344 + *
1345 + * @return void
1336 1346 */
1337 1347 function bbp_increase_forum_topic_count_hidden( $forum_id = 0 ) {
1338 1348
1339 1349 // Bail early if no id is passed.
@@ -1362,8 +1372,10 @@
1362 1372 *
1363 1373 * @since 2.6.0 bbPress (r6036)
1364 1374 *
1365 1375 * @param int $forum_id The forum id.
1376 + *
1377 + * @return void
1366 1378 */
1367 1379 function bbp_decrease_forum_topic_count_hidden( $forum_id = 0 ) {
1368 1380
1369 1381 // Bail early if no id is passed.
@@ -1387,16 +1399,16 @@
1387 1399 bbp_bump_forum_topic_count_hidden( $forum_id, -1 );
1388 1400 }
1389 1401
1390 1402 /**
1391 - * Bump the total topic count of a forum.
1403 + * Bump the total topic count of a forum
1392 1404 *
1393 1405 * @since 2.1.0 bbPress (r3825)
1394 1406 * @since 2.6.17 Use atomic metadata writes and non-negative counts.
1395 1407 *
1396 1408 * @param int $forum_id Optional. Forum id.
1397 - * @param int $difference Optional. Default 1.
1398 - * @param bool $update_ancestors Optional. Default true.
1409 + * @param int $difference Optional. Default 1
1410 + * @param bool $update_ancestors Optional. Default true
1399 1411 *
1400 1412 * @return int Forum topic count
1401 1413 */
1402 1414 function bbp_bump_forum_reply_count( $forum_id = 0, $difference = 1, $update_ancestors = true ) {
@@ -1447,16 +1459,16 @@
1447 1459 return (int) apply_filters( 'bbp_bump_forum_reply_count', $forum_reply_count, $forum_id, $difference, $update_ancestors );
1448 1460 }
1449 1461
1450 1462 /**
1451 - * Bump the total topic count of a forum.
1463 + * Bump the total topic count of a forum
1452 1464 *
1453 1465 * @since 2.6.0 bbPress (r6922)
1454 1466 * @since 2.6.17 Use atomic metadata writes and non-negative counts.
1455 1467 *
1456 1468 * @param int $forum_id Optional. Forum id.
1457 - * @param int $difference Optional. Default 1.
1458 - * @param bool $update_ancestors Optional. Default true.
1469 + * @param int $difference Optional. Default 1
1470 + * @param bool $update_ancestors Optional. Default true
1459 1471 *
1460 1472 * @return int Forum topic count
1461 1473 */
1462 1474 function bbp_bump_forum_reply_count_hidden( $forum_id = 0, $difference = 1, $update_ancestors = true ) {
@@ -1568,8 +1580,10 @@
1568 1580 *
1569 1581 * @since 2.6.0 bbPress (r6036)
1570 1582 *
1571 1583 * @param int $forum_id The forum id.
1584 + *
1585 + * @return void
1572 1586 */
1573 1587 function bbp_increase_forum_reply_count( $forum_id = 0 ) {
1574 1588
1575 1589 // Bail early if no id is passed.
@@ -1598,8 +1612,10 @@
1598 1612 *
1599 1613 * @since 2.6.0 bbPress (r6036)
1600 1614 *
1601 1615 * @param int $forum_id The forum id.
1616 + *
1617 + * @return void
1602 1618 */
1603 1619 function bbp_decrease_forum_reply_count( $forum_id = 0 ) {
1604 1620
1605 1621 // Bail early if no id is passed.
@@ -1628,8 +1644,10 @@
1628 1644 *
1629 1645 * @since 2.6.0 bbPress (r6036)
1630 1646 *
1631 1647 * @param int $forum_id The forum id.
1648 + *
1649 + * @return void
1632 1650 */
1633 1651 function bbp_increase_forum_reply_count_hidden( $forum_id = 0 ) {
1634 1652
1635 1653 // Bail early if no id is passed.
@@ -1658,8 +1676,10 @@
1658 1676 *
1659 1677 * @since 2.6.0 bbPress (r6036)
1660 1678 *
1661 1679 * @param int $forum_id The forum id.
1680 + *
1681 + * @return void
1662 1682 */
1663 1683 function bbp_decrease_forum_reply_count_hidden( $forum_id = 0 ) {
1664 1684
1665 1685 // Bail early if no id is passed.
@@ -1688,8 +1708,10 @@
1688 1708 *
1689 1709 * @since 2.6.0 bbPress (r6036)
1690 1710 *
1691 1711 * @param int $topic_id The topic id.
1712 + *
1713 + * @return void
1692 1714 */
1693 1715 function bbp_approved_unapproved_topic_update_forum_reply_count( $topic_id = 0 ) {
1694 1716
1695 1717 // Bail early if we don't have a topic id.
@@ -1711,15 +1733,15 @@
1711 1733
1712 1734 /** Forum Updaters ************************************************************/
1713 1735
1714 1736 /**
1715 - * Update the forum last topic id.
1737 + * Update the forum last topic id
1716 1738 *
1717 1739 * @since 2.0.0 bbPress (r2625)
1718 1740 *
1719 1741 * @param int $forum_id Optional. Forum id.
1720 1742 * @param int $topic_id Optional. Topic id.
1721 - * @return int Id of the forums most recent topic.
1743 + * @return int Id of the forums most recent topic
1722 1744 */
1723 1745 function bbp_update_forum_last_topic_id( $forum_id = 0, $topic_id = 0 ) {
1724 1746 $forum_id = bbp_get_forum_id( $forum_id );
1725 1747
@@ -1770,15 +1792,15 @@
1770 1792 return (int) apply_filters( 'bbp_update_forum_last_topic_id', $topic_id, $forum_id );
1771 1793 }
1772 1794
1773 1795 /**
1774 - * Update the forum last reply id.
1796 + * Update the forum last reply id
1775 1797 *
1776 1798 * @since 2.0.0 bbPress (r2625)
1777 1799 *
1778 1800 * @param int $forum_id Optional. Forum id.
1779 1801 * @param int $reply_id Optional. Reply id.
1780 - * @return int Id of the forums most recent reply.
1802 + * @return int Id of the forums most recent reply
1781 1803 */
1782 1804 function bbp_update_forum_last_reply_id( $forum_id = 0, $reply_id = 0 ) {
1783 1805 $forum_id = bbp_get_forum_id( $forum_id );
1784 1806
@@ -1826,15 +1848,15 @@
1826 1848 return (int) apply_filters( 'bbp_update_forum_last_reply_id', $reply_id, $forum_id );
1827 1849 }
1828 1850
1829 1851 /**
1830 - * Update the forum last active post id.
1852 + * Update the forum last active post id
1831 1853 *
1832 1854 * @since 2.0.0 bbPress (r2860)
1833 1855 *
1834 1856 * @param int $forum_id Optional. Forum id.
1835 1857 * @param int $active_id Optional. Active post id.
1836 - * @return int Id of the forums last active post.
1858 + * @return int Id of the forums last active post
1837 1859 */
1838 1860 function bbp_update_forum_last_active_id( $forum_id = 0, $active_id = 0 ) {
1839 1861
1840 1862 $forum_id = bbp_get_forum_id( $forum_id );
@@ -1884,9 +1906,9 @@
1884 1906 return (int) apply_filters( 'bbp_update_forum_last_active_id', $active_id, $forum_id );
1885 1907 }
1886 1908
1887 1909 /**
1888 - * Update the forums last active date/time (aka freshness).
1910 + * Update the forums last active date/time (aka freshness)
1889 1911 *
1890 1912 * @since 2.0.0 bbPress (r2680)
1891 1913 *
1892 1914 * @param int $forum_id Optional. Topic id.
@@ -1891,9 +1913,9 @@
1891 1913 *
1892 1914 * @param int $forum_id Optional. Topic id.
1893 1915 * @param string $new_time Optional. New time in mysql format.
1894 1916 *
1895 - * @return string MySQL timestamp of last active topic or reply.
1917 + * @return string MySQL timestamp of last active topic or reply
1896 1918 */
1897 1919 function bbp_update_forum_last_active_time( $forum_id = 0, $new_time = '' ) {
1898 1920 $forum_id = bbp_get_forum_id( $forum_id );
1899 1921
@@ -1911,9 +1933,9 @@
1911 1933 return apply_filters( 'bbp_update_forum_last_active', $new_time, $forum_id );
1912 1934 }
1913 1935
1914 1936 /**
1915 - * Update the forum sub-forum count.
1937 + * Update the forum sub-forum count
1916 1938 *
1917 1939 * @since 2.0.0 bbPress (r2625)
1918 1940 * @since 2.6.17 Count supported forum visibilities from the post hierarchy.
1919 1941 *
@@ -1919,9 +1941,9 @@
1919 1941 *
1920 1942 * @param int $forum_id Optional. Forum ID.
1921 1943 * @param int|bool $subforums Optional. Number of subforums, or false to query.
1922 1944 * @return int|false Number of subforums, or false on query failure.
1923 - */
1945 +*/
1924 1946 function bbp_update_forum_subforum_count( $forum_id = 0, $subforums = false ) {
1925 1947 $forum_id = bbp_get_forum_id( $forum_id );
1926 1948
1927 1949 // Maybe query for counts
@@ -2439,9 +2461,9 @@
2439 2461
2440 2462 /** Helpers *******************************************************************/
2441 2463
2442 2464 /**
2443 - * Return an associative array of available topic statuses.
2465 + * Return an associative array of available topic statuses
2444 2466 *
2445 2467 * Developers note: these statuses are actually stored as meta data, and
2446 2468 * Visibilities are stored in post_status.
2447 2469 *
@@ -2446,9 +2468,9 @@
2446 2468 * Visibilities are stored in post_status.
2447 2469 *
2448 2470 * @since 2.4.0 bbPress (r5059)
2449 2471 *
2450 - * @param int $forum_id Optional. Forum id.
2472 + * @param int $forum_id Optional. Forum id.
2451 2473 *
2452 2474 * @return array
2453 2475 */
2454 2476 function bbp_get_forum_statuses( $forum_id = 0 ) {
@@ -2464,13 +2486,13 @@
2464 2486 );
2465 2487 }
2466 2488
2467 2489 /**
2468 - * Return an associative array of forum type.
2490 + * Return an associative array of forum types
2469 2491 *
2470 2492 * @since 2.4.0 bbPress (r5059)
2471 2493 *
2472 - * @param int $forum_id Optional. Forum id.
2494 + * @param int $forum_id Optional. Forum id.
2473 2495 *
2474 2496 * @return array
2475 2497 */
2476 2498 function bbp_get_forum_types( $forum_id = 0 ) {
@@ -2493,9 +2515,9 @@
2493 2515 * Statuses are stored in meta data.
2494 2516 *
2495 2517 * @since 2.4.0 bbPress (r5059)
2496 2518 *
2497 - * @param int $forum_id Optional. Forum id.
2519 + * @param int $forum_id Optional. Forum id.
2498 2520 *
2499 2521 * @return array
2500 2522 */
2501 2523 function bbp_get_forum_visibilities( $forum_id = 0 ) {
@@ -2561,9 +2583,9 @@
2561 2583
2562 2584 /** Queries *******************************************************************/
2563 2585
2564 2586 /**
2565 - * Returns the hidden forum ids.
2587 + * Returns the hidden forum ids
2566 2588 *
2567 2589 * Only hidden forum ids are returned. Public and private ids are not.
2568 2590 *
2569 2591 * @since 2.0.0 bbPress (r3007)
@@ -2578,9 +2600,9 @@
2578 2600 return (array) apply_filters( 'bbp_get_hidden_forum_ids', $forum_ids );
2579 2601 }
2580 2602
2581 2603 /**
2582 - * Returns the private forum ids.
2604 + * Returns the private forum ids
2583 2605 *
2584 2606 * Only private forum ids are returned. Public and hidden ids are not.
2585 2607 *
2586 2608 * @since 2.0.0 bbPress (r3007)
@@ -2598,11 +2620,18 @@
2598 2620 /**
2599 2621 * Returns the forum IDs that should be excluded from various views & queries,
2600 2622 * based on the current user's capabilities.
2601 2623 *
2624 + * These results are automatically filtered by bbp_allow_forums_of_user(), to
2625 + * allow per-forum moderators to see forums that would otherwise be private or
2626 + * hidden to them.
2627 + *
2628 + * If you have a need to filter these results based on your own custom
2629 + * engagements API usages, please see: bbp_allow_forums_of_user()
2630 + *
2602 2631 * @since 2.6.0 bbPress (r6425)
2603 2632 *
2604 - * @return array Forum IDs to exclude, or an empty array.
2633 + * @return array Forum IDs to exclude, or an empty array
2605 2634 */
2606 2635 function bbp_get_excluded_forum_ids() {
2607 2636
2608 2637 // Private forums
@@ -2645,9 +2674,9 @@
2645 2674 * from a query.
2646 2675 *
2647 2676 * @since 2.0.0 bbPress (r3291)
2648 2677 *
2649 - * @param string Optional. The type of value to return (string|array|meta_query).
2678 + * @param string Optional. The type of value to return. (string|array|meta_query)
2650 2679 */
2651 2680 function bbp_exclude_forum_ids( $type = 'string' ) {
2652 2681
2653 2682 // Setup arrays
@@ -2978,15 +3007,15 @@
2978 3007 return $where . $visibility_where;
2979 3008 }
2980 3009
2981 3010 /**
2982 - * Returns the forum's topic ids.
3011 + * Returns the forum's topic ids
2983 3012 *
2984 - * Only topics with published and closed statuses are returned.
3013 + * Only topics with published and closed statuses are returned
2985 3014 *
2986 3015 * @since 2.0.0 bbPress (r2908)
2987 3016 *
2988 - * @param int $forum_id Forum id.
3017 + * @param int $forum_id Forum id
2989 3018 */
2990 3019 function bbp_forum_query_topic_ids( $forum_id ) {
2991 3020 $topic_ids = bbp_get_public_child_ids( $forum_id, bbp_get_topic_post_type() );
2992 3021
@@ -3043,12 +3072,12 @@
3043 3072 return (array) apply_filters( 'bbp_forum_query_subforum_ids', $subforum_ids, $forum_id );
3044 3073 }
3045 3074
3046 3075 /**
3047 - * Returns the forum's last reply id.
3076 + * Returns the forum's last reply id
3048 3077 *
3049 3078 * @since 2.0.0 bbPress (r2908)
3050 - * @since 2.6.0 bbPress (r5954) Replace direct queries with WP_Query() objects.
3079 + * @since 2.6.0 bbPress (r5954) Replace direct queries with WP_Query() objects
3051 3080 *
3052 3081 * @param int $forum_id Forum id.
3053 3082 * @param int $topic_ids Optional. Topic ids.
3054 3083 */
@@ -3094,9 +3123,9 @@
3094 3123 /** Listeners *****************************************************************/
3095 3124
3096 3125 /**
3097 3126 * Check if it's a hidden forum or a topic or reply of a hidden forum and if
3098 - * the user can't view it, then sets a 404.
3127 + * the user can't view it, then sets a 404
3099 3128 *
3100 3129 * @since 2.0.0 bbPress (r2996)
3101 3130 */
3102 3131 function bbp_forum_enforce_hidden() {
@@ -3131,12 +3160,10 @@
3131 3160 $forum_id = bbp_get_reply_forum_id( $post_id );
3132 3161 break;
3133 3162 }
3134 3163
3135 - // If forum is explicitly hidden and user not capable...
3164 + // If forum is explicitly hidden and user not capable, set 404
3136 3165 if ( ! empty( $forum_id ) && bbp_is_forum_hidden( $forum_id ) && ! current_user_can( 'read_forum', $forum_id ) ) {
3137 -
3138 - // Set 404 status
3139 3166 bbp_set_404( $wp_query );
3140 3167 }
3141 3168 }
3142 3169
@@ -3141,9 +3168,9 @@
3141 3168 }
3142 3169
3143 3170 /**
3144 3171 * Check if it's a private forum or a topic or reply of a private forum and if
3145 - * the user can't view it, then sets a 404.
3172 + * the user can't view it, then sets a 404
3146 3173 *
3147 3174 * @since 2.0.0 bbPress (r2996)
3148 3175 */
3149 3176 function bbp_forum_enforce_private() {
@@ -3178,12 +3205,10 @@
3178 3205 $forum_id = bbp_get_reply_forum_id( $post_id );
3179 3206 break;
3180 3207 }
3181 3208
3182 - // If forum is explicitly private and user not capable
3209 + // If forum is explicitly hidden and user not capable, set 404
3183 3210 if ( ! empty( $forum_id ) && bbp_is_forum_private( $forum_id ) && ! current_user_can( 'read_forum', $forum_id ) ) {
3184 -
3185 - // Set 404 status
3186 3211 bbp_set_404( $wp_query );
3187 3212 }
3188 3213 }
3189 3214
@@ -3189,9 +3214,9 @@
3189 3214
3190 3215 /** Permissions ***************************************************************/
3191 3216
3192 3217 /**
3193 - * Redirect if unauthorized user is attempting to edit a forum.
3218 + * Redirect if unauthorized user is attempting to edit a forum
3194 3219 *
3195 3220 * @since 2.1.0 bbPress (r3607)
3196 3221 */
3197 3222 function bbp_check_forum_edit() {
@@ -3207,13 +3232,14 @@
3207 3232 }
3208 3233 }
3209 3234
3210 3235 /**
3211 - * Delete all topics (and their replies) for a specific forum ID.
3236 + * Delete all topics (and their replies) for a specific forum ID
3212 3237 *
3213 3238 * @since 2.1.0 bbPress (r3668)
3214 3239 *
3215 3240 * @param int $forum_id
3241 + * @return If forum is not valid
3216 3242 */
3217 3243 function bbp_delete_forum_topics( $forum_id = 0 ) {
3218 3244
3219 3245 // Validate forum ID
@@ -3257,13 +3283,14 @@
3257 3283 unset( $topics );
3258 3284 }
3259 3285
3260 3286 /**
3261 - * Trash all topics inside a forum.
3287 + * Trash all topics inside a forum
3262 3288 *
3263 3289 * @since 2.1.0 bbPress (r3668)
3264 3290 *
3265 3291 * @param int $forum_id
3292 + * @return If forum is not valid
3266 3293 */
3267 3294 function bbp_trash_forum_topics( $forum_id = 0 ) {
3268 3295
3269 3296 // Validate forum ID
@@ -3324,13 +3351,14 @@
3324 3351 unset( $topics );
3325 3352 }
3326 3353
3327 3354 /**
3328 - * Untrash all topics inside a forum.
3355 + * Untrash all topics inside a forum
3329 3356 *
3330 3357 * @since 2.1.0 bbPress (r3668)
3331 3358 *
3332 3359 * @param int $forum_id
3360 + * @return If forum is not valid
3333 3361 */
3334 3362 function bbp_untrash_forum_topics( $forum_id = 0 ) {
3335 3363
3336 3364 // Validate forum ID
@@ -3379,9 +3407,9 @@
3379 3407 do_action( 'bbp_delete_forum', $forum_id );
3380 3408 }
3381 3409
3382 3410 /**
3383 - * Called before trashing a forum.
3411 + * Called before trashing a forum
3384 3412 *
3385 3413 * This function is supplemental to the actual forum being trashed which is
3386 3414 * handled by WordPress core API functions. It is used to clean up after
3387 3415 * a forum that is being trashed.
@@ -3398,9 +3426,9 @@
3398 3426 do_action( 'bbp_trash_forum', $forum_id );
3399 3427 }
3400 3428
3401 3429 /**
3402 - * Called before untrashing a forum.
3430 + * Called before untrashing a forum
3403 3431 *
3404 3432 * @since 2.1.0 bbPress (r3668)
3405 3433 */
3406 3434 function bbp_untrash_forum( $forum_id = 0 ) {
@@ -3415,9 +3443,9 @@
3415 3443
3416 3444 /** After Delete/Trash/Untrash ************************************************/
3417 3445
3418 3446 /**
3419 - * Called after deleting a forum.
3447 + * Called after deleting a forum
3420 3448 *
3421 3449 * Try not to use this action. All meta & taxonomy terms have already been
3422 3450 * deleted, making them impossible to use.
3423 3451 *
@@ -3442,9 +3470,9 @@
3442 3470 do_action( 'bbp_deleted_forum', $forum_id, $forum );
3443 3471 }
3444 3472
3445 3473 /**
3446 - * Called after trashing a forum.
3474 + * Called after trashing a forum
3447 3475 *
3448 3476 * @since 2.1.0 bbPress (r3668)
3449 3477 */
3450 3478 function bbp_trashed_forum( $forum_id = 0 ) {
@@ -3457,9 +3485,9 @@
3457 3485 do_action( 'bbp_trashed_forum', $forum_id );
3458 3486 }
3459 3487
3460 3488 /**
3461 - * Called after untrashing a forum.
3489 + * Called after untrashing a forum
3462 3490 *
3463 3491 * @since 2.1.0 bbPress (r3668)
3464 3492 */
3465 3493 function bbp_untrashed_forum( $forum_id = 0 ) {