Hooks & Filters

Hooks & Filters

The plugin provides 134 unique hooks across its PHP codebase. The most useful ones for customisation are documented here. All filters in the scoring pipeline use the bp_suggestions_* prefix; action hooks use bffs_*.

Add your custom code in a site plugin or your theme’s functions.php. Do not modify plugin files directly — your changes will be lost on the next update.

---

Filters — Scoring pipeline

These filters run every time a compatibility score is calculated between two members.

bp_suggestions_pre_compatibility_score

Short-circuits the entire scoring calculation. Return an integer to skip the normal calculation and use your value instead. Return false to let normal scoring proceed.

add_filter( 'bp_suggestions_pre_compatibility_score', function( $pre, $user_id1, $user_id2 ) {
    // Return a fixed score for a specific pair, skip normal calculation.
    if ( 999 === $user_id1 && 888 === $user_id2 ) {
        return 100;
    }
    return false; // Let normal scoring run.
}, 10, 3 );

Parameters: $pre (false|int), $user_id1 (int), $user_id2 (int)

---

bp_suggestions_match_settings

Modifies the settings array used for a specific pair’s calculation. Use this to apply custom logic per user — for example, to increase the weight of certain fields for premium members.

add_filter( 'bp_suggestions_match_settings', function( $settings, $user_id1, $user_id2 ) {
    // Double the baseline for a specific group.
    if ( groups_is_user_member( 42, $user_id1 ) ) {
        $settings['profile_st_percentage'] = 40;
    }
    return $settings;
}, 10, 3 );

Parameters: $settings (array), $user_id1 (int), $user_id2 (int)

---

bp_suggestions_final_score

Modifies the final calculated score before it is returned and cached. The score at this point is an integer 0–100.

add_filter( 'bp_suggestions_final_score', function( $score, $user_id1, $user_id2 ) {
    // Cap scores at 95 to avoid showing "perfect match" claims.
    return min( $score, 95 );
}, 10, 3 );

Parameters: $score (int), $user_id1 (int), $user_id2 (int)

---

bp_suggestions_field_value_user1 / bp_suggestions_field_value_user2

Modifies the raw xProfile field value for either user before comparison. Use this to normalise values — for example, to make text field comparisons case-insensitive.

add_filter( 'bp_suggestions_field_value_user1', function( $value, $field_id, $user_id1, $user_id2 ) {
    return is_string( $value ) ? strtolower( trim( $value ) ) : $value;
}, 10, 4 );

add_filter( 'bp_suggestions_field_value_user2', function( $value, $field_id, $user_id1, $user_id2 ) {
    return is_string( $value ) ? strtolower( trim( $value ) ) : $value;
}, 10, 4 );

Parameters: $value (mixed), $field_id (int), $user_id1 (int), $user_id2 (int)

---

bp_suggestions_score_cache_key

Changes the transient key used to cache a score. Useful if you need per-segment caching.

add_filter( 'bp_suggestions_score_cache_key', function( $key, $user_id1, $user_id2 ) {
    return $key . '_v2'; // Bust the cache after a major algorithm change.
}, 10, 3 );

Parameters: $key (string), $user_id1 (int), $user_id2 (int)

---

Filters — Display

bffs_match_badge_html

Modifies the HTML for the match badge that appears on member profile headers.

add_filter( 'bffs_match_badge_html', function( $html, $score, $user_id1, $user_id2 ) {
    // Add a custom class for scores above 90.
    if ( $score >= 90 ) {
        $html = str_replace( 'class="bffs-match-badge"', 'class="bffs-match-badge bffs-top-match"', $html );
    }
    return $html;
}, 10, 4 );

Parameters: $html (string), $score (int), $user_id1 (int), $user_id2 (int)

---

bffs_force_public_enqueue

Forces the plugin’s frontend stylesheet to load on every page, even pages without a widget or shortcode. Return true to enable. Default: false (stylesheet only loads when needed).

add_filter( 'bffs_force_public_enqueue', '__return_true' );

---

Filters — Email

bffs_suggestions_url

Changes the URL used in email digests for the “View All Suggestions” link.

add_filter( 'bffs_suggestions_url', function( $url ) {
    return home_url( '/my-custom-suggestions-page/' );
} );

Parameters: $url (string)

---

bffs_new_suggestion_email_template / bffs_weekly_digest_email_template

Replaces the HTML email template used for instant notifications or the weekly digest.

---

bffs_hot_matches_check_limit

Sets the maximum number of members checked for “hot match” status per user per run. Default: 25.

add_filter( 'bffs_hot_matches_check_limit', function( $limit, $user_id ) {
    return 50;
}, 10, 2 );

---

bffs_hot_matches_max_notifications

Sets the maximum number of hot-match notifications sent to a user per run. Default: 5.

---

Action hooks

bffs_suggestion_dismissed

Fires when a member dismisses a suggestion card.

add_action( 'bffs_suggestion_dismissed', function( $user_id, $dismissed_user_id, $reason ) {
    // Log the dismissal to an external analytics service.
}, 10, 3 );

Parameters: $user_id (int), $dismissed_user_id (int), $reason (string — 'manual' or 'auto')

---

bffs_suggestions_refreshed_user

Fires when a member’s suggestion list is manually refreshed (via the refresh button).

add_action( 'bffs_suggestions_refreshed_user', function( $user_id ) {
    // Invalidate a third-party cache for this user.
}, 10, 1 );

---

bffs_settings_email_frequency_saved

Fires after a member saves their email frequency preference on the BuddyPress settings page.

add_action( 'bffs_settings_email_frequency_saved', function( $user_id, $frequency ) {
    // Sync preference to an external email system.
}, 10, 2 );

Parameters: $user_id (int), $frequency (string — 'instant', 'daily', 'weekly', 'never')

---

bffs_settings_after_email_frequency

Fires after the email-frequency control is output on the BuddyPress member settings page. Use this to add extra fields to the notifications settings section.

---

bffs_cache_cleared

Fires when the suggestion cache is cleared (manually from the Advanced tab or programmatically).

add_action( 'bffs_cache_cleared', function( $cleared ) {
    // $cleared is the number of cache entries deleted.
}, 10, 1 );

---

bffs_weekly_digest_sent / bffs_daily_digest_sent

Fires after a batch of digest emails has been sent. $users is an array of user IDs that received the email.

---

bffs_welcome_email_sent

Fires after the new-member welcome email is dispatched.

add_action( 'bffs_welcome_email_sent', function( $user_id, $suggestions, $sent, $used_bp_email ) {
    // Track deliverability.
}, 10, 4 );

Parameters: $user_id (int), $suggestions (array), $sent (bool), $used_bp_email (bool)

---

bffs_admin_tabs filter

Modifies the admin settings tab list. Add custom tabs or remove existing ones.

add_filter( 'bffs_admin_tabs', function( $tabs ) {
    $tabs['my_tab'] = array(
        'label' => 'My Custom Tab',
        'icon'  => 'dashicons-admin-generic',
    );
    return $tabs;
} );

---

Programmatic cache clear

The plugin does not expose an action to clear a single user’s cache programmatically. To bulk-clear suggestion transients from your own code (for example, after a bulk profile import), delete the transients with the bffs_cache_ prefix from wp_options:

global $wpdb;
$wpdb->query(
    $wpdb->prepare(
        "DELETE FROM {$wpdb->options} WHERE option_name LIKE %s OR option_name LIKE %s",
        '_transient_' . $wpdb->esc_like( 'bffs_cache_' ) . '%',
        '_transient_timeout_' . $wpdb->esc_like( 'bffs_cache_' ) . '%'
    )
);

After the cache is cleared internally (via the admin dashboard), the plugin fires:

bffs_cache_cleared

Fires after the dashboard cache-clear operation completes.

do_action( 'bffs_cache_cleared', $cleared ); // $cleared = number of transients removed.

Parameters: $cleared (int) — the number of transient rows deleted from wp_options.

Use this hook to log cache-clear events or trigger follow-on cleanup in your own code.