PHP API Reference

This document covers the public PHP functions and classes available in BuddyPress Stats.

Main Functions

User Statistics

bp_stats_get_user_activity_count()

Get total activity count for a user.

$count = bp_stats_get_user_activity_count( $user_id );

Parameters: $user_id (int) – User ID

Returns: (int) Total activity count

bp_stats_get_user_last_login()

Get a user’s last login timestamp.

$timestamp = bp_stats_get_user_last_login( $user_id );

Returns: (int|false) Unix timestamp or false if never logged in

bp_stats_get_user_health_segment()

Get which health segment a user belongs to.

$segment = bp_stats_get_user_health_segment( $user_id );
// Returns: 'active', 'at_risk', 'dormant', or 'inactive'

Group Statistics

bp_stats_get_group_activity_count()

Get total activity count for a group.

$count = bp_stats_get_group_activity_count( $group_id );

bp_stats_get_group_top_contributors()

Get top contributors for a group.

$contributors = bp_stats_get_group_top_contributors( $group_id, $limit );

Parameters: $group_id (int), $limit (int) – Number to return (default: 10)

Returns: (array) Array of user objects with activity counts

Dashboard Data

bp_stats_get_active_users_count()

Get count of active users in a period.

$count = bp_stats_get_active_users_count( $days );

Parameters: $days (int) – Number of days to look back (default: 30)

bp_stats_get_new_registrations_count()

Get count of new user registrations.

$count = bp_stats_get_new_registrations_count( $days );

Admin Class Methods

Bp_Stats_Admin

bp_stats_get_user_health_segments()

Get counts for all user health segments.

$admin = new Bp_Stats_Admin();
$segments = $admin->bp_stats_get_user_health_segments();

// Returns:
// array(
//     'active'   => 150,
//     'at_risk'  => 75,
//     'dormant'  => 50,
//     'inactive' => 25,
//     'total'    => 300
// )

bp_stats_get_monthly_retention_rate()

Get the monthly retention rate percentage.

$admin = new Bp_Stats_Admin();
$retention = $admin->bp_stats_get_monthly_retention_rate();

// Returns:
// array(
//     'rate'       => 65.5,
//     'trend'      => 'up',
//     'change'     => 5.2,
//     'active'     => 200,
//     'total'      => 305
// )

Cache Handler

Stats_Cache_Handler

Handles transient caching for statistics.

// Getting Cached Data
$cache = new Stats_Cache_Handler();
$data = $cache->get( 'dashboard_summary' );

// Setting Cache
$cache->set( 'dashboard_summary', $data, HOUR_IN_SECONDS );

// Clearing Cache
$cache->clear( 'dashboard_summary' );
$cache->clear_all(); // Clear everything

Database Table

Table Structure

The plugin creates one custom table: {prefix}_bp_stats_activity_log

Column	Type	Description
id	bigint	Auto-increment ID
activity_id	bigint	Related BP activity ID
activity_date	datetime	When it occurred
user_id	bigint	User who performed action
action	varchar	Action type
topic	varchar	Category/topic
context	text	Additional context
meta	longtext	JSON metadata
item_id	bigint	Related item ID
activity_type	varchar	Type classification
ip	varchar	IP address

Direct Queries

global $wpdb;
$table = $wpdb->prefix . 'bp_stats_activity_log';

// Get recent logs
$logs = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT * FROM $table WHERE user_id = %d ORDER BY activity_date DESC LIMIT 10",
        $user_id
    )
);

Best Practices

Performance

1. Use Caching: Always check cache before database queries
2. Batch Queries: Fetch multiple items in single queries
3. Limit Results: Use LIMIT clauses appropriately

Security

1. Prepare Statements: Always use $wpdb->prepare()
2. Check Capabilities: Verify user permissions
3. Sanitize Input: Sanitize all user input
4. Escape Output: Escape data for display