Action Hooks & Filters Reference
BuddyPress Auto Friends overviewPremiumGet BuddyPress Auto Friends →
All plugin-specific hooks use the bautof_ prefix. Filters from the earlier bp_auto_ prefix are listed for back-compat.
Actions
Section titled “Actions”bautof_create_friendships_event
Section titled “bautof_create_friendships_event”Fires the friendship creation routine for a single user. Hooked to WordPress cron. Also scheduled directly when a user registers or when their role or member type changes.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$user_id |
int | ID of the user for whom friendships should be created |
$offset |
int | Position in the welcome list this chunk starts at. Defaults to 0; the next chunk is queued with the offset it reached |
Example:
// Manually trigger friendship creation for a user.do_action( 'bautof_create_friendships_event', $user_id );bautof_create_existing_user_friendships_event
Section titled “bautof_create_existing_user_friendships_event”Fires the bulk friendship creation routine for existing users. Used by the manual processing card on the Overview tab.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$add_friends |
string | Mode: 'user_roles' or 'member_types' |
$user_type |
array | Array of role slugs or member-type term IDs |
bautof_send_friends_add_friend
Section titled “bautof_send_friends_add_friend”Fires for each chunk of users during the “Add as friend to all existing members” operation. Scheduled via cron with a 5-second delay between chunks.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$to_befriend |
int | User ID being befriended with others |
$pending_chunk |
array | Array of user IDs to befriend in this chunk |
Filters
Section titled “Filters”bautof_enable_notifications_for_user
Section titled “bautof_enable_notifications_for_user”Filters whether BuddyPress friendship notifications should fire for a specific auto-friendship. The default is false - auto-friendships are silent by design.
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
$enabled |
bool | false |
Whether to send notifications |
$user_id |
int | - | Recipient user ID |
$bpaf_settings |
array | - | Current plugin settings array |
Returns: bool
Example:
// Send notifications only for users with the 'premium' role.add_filter( 'bautof_enable_notifications_for_user', function( $enabled, $user_id, $settings ) { $user = get_userdata( $user_id ); return $user && in_array( 'premium', (array) $user->roles, true ); }, 10, 3);bautof_list_members_per_page
Section titled “bautof_list_members_per_page”Filters how many members a friend list shows per page in the Manage members window and in the REST GET /lists/{slug}/members response. Members past the first page load with the Show more members button.
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
$per_page |
int | 30 |
Members per page (minimum 1) |
Returns: int
Example:
add_filter( 'bautof_list_members_per_page', function( $per_page ) { return 50;} );bautof_welcome_chunk_size
Section titled “bautof_welcome_chunk_size”Filters how many friendships one welcome run creates before it queues the next chunk, so a large welcome group never relies on one long request.
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
$size |
int | 100 |
Friendships created per run (minimum 1) |
Returns: int
add_filter( 'bautof_welcome_chunk_size', function( $size ) { return 50;} );bautof_inline_befriend_threshold
Section titled “bautof_inline_befriend_threshold”Filters how many members “Add as friend to all existing members” befriends straight away. A longer list is handed to cron in chunks.
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
$threshold |
int | 100 |
Largest list processed in the admin request |
Returns: int
bautof_friendship_batch_size
Section titled “bautof_friendship_batch_size”Filters the number of users retrieved per database query during the bulk sync sweep.
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
$batch_size |
int | 100 |
Users fetched per batch in bautof_create_existing_friendships() |
Returns: int
Example:
// Increase batch size on high-memory servers.add_filter( 'bautof_friendship_batch_size', function( $size ) { return 200;} );bp_auto_befriend_all_chunk_size
Section titled “bp_auto_befriend_all_chunk_size”Filters the number of users processed per chunk during the “Add as friend to all existing members” operation.
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
$chunk_size |
int | 25 |
Number of user IDs per scheduled cron chunk |
Returns: int
Example:
// Reduce chunk size on low-memory servers.add_filter( 'bp_auto_befriend_all_chunk_size', function( $size ) { return 10;} );bautof_admin_tabs
Section titled “bautof_admin_tabs”Filters the admin tab registry before the sidebar is rendered. Allows adding, removing, or reordering tabs.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$tabs |
array | Associative array of tab slugs to tab config arrays |
Tab config keys: label (string), icon (dashicons class), group ('main', 'settings', or 'account')
Returns: array
Key functions
Section titled “Key functions”bautof_force_friendship( $initiator_user_id, $friend_user_id )
Section titled “bautof_force_friendship( $initiator_user_id, $friend_user_id )”Central friendship creation function. Handles all BuddyPress friendship states.
Since: 1.8.1
/** * Ensures a confirmed friendship between two users. * * @since 1.8.1 * * @param int $initiator_user_id The user initiating the friendship. * @param int $friend_user_id The intended friend user. * @return bool True if both users are confirmed friends after this call. */function bautof_force_friendship( $initiator_user_id, $friend_user_id );This function correctly handles pending and awaiting_response states by promoting them to confirmed via a direct database update. This works in cron and CLI contexts where bp_loggedin_user_id() returns 0.
bautof_get_global_friends()
Section titled “bautof_get_global_friends()”Returns an array of user IDs marked as global friends. Results are cached in the WordPress object cache for 1 hour.
$global_friends = bautof_get_global_friends();// Returns: int[]bautof_mark_auto_created( $user_a, $user_b )
Section titled “bautof_mark_auto_created( $user_a, $user_b )”Records that the plugin auto-created the friendship between two users. Mirrors the record on both sides so cleanup from either direction finds it. Stored in _bautof_auto_created_friends user meta.
Since: 1.8.2
bautof_remove_auto_created_friendships( $user_id, $reason )
Section titled “bautof_remove_auto_created_friendships( $user_id, $reason )”Removes all plugin-tracked auto-created friendships for a user. Uses explicit _bautof_auto_created_friends meta as the primary source (friendships since 1.8.2), with a legacy role/type heuristic fallback for friendships predating the tracking upgrade.
Since: 1.7.0
Returns: int|false - number of friendships removed, or false on invalid input.
WordPress cron events
Section titled “WordPress cron events”| Event hook | Callback | Purpose |
|---|---|---|
bautof_create_friendships_event |
bautof_create_friendships |
Per-user friendship creation on registration or role change |
bautof_create_existing_user_friendships_event |
bautof_create_existing_friendships |
Bulk sync for existing users (manual processing) |
bautof_send_friends_add_friend |
bautof_friends_add_friend |
Chunked “Add as friend to all existing members” backfill |
bautof_cleanup_transients |
Admin class method | Daily transient cleanup |
WordPress and BuddyPress hooks used
Section titled “WordPress and BuddyPress hooks used”| Hook | Purpose |
|---|---|
user_register |
Schedules friendship creation for new users |
set_user_role |
Triggers dynamic processing and cleanup on role replacement |
add_user_role |
Triggers dynamic processing on role addition |
remove_user_role |
Triggers cleanup if enabled |
bp_set_member_type |
Triggers dynamic processing and cleanup on member-type change |
bp_remove_member_type |
Triggers cleanup if enabled |
friends_friendship_accepted |
Cache invalidation |
friends_friendship_deleted |
Cache invalidation |
bp_setup_nav |
Registers the Friend Lists sub-tab and per-list activity tabs |
rest_api_init |
Registers REST API routes |
admin_menu |
Registers the WB Plugins hub and Auto Friends submenu |

