Hooks Reference

Hooks Reference

All hooks use the bpquotes_ prefix unless otherwise noted. Add your callbacks in a custom plugin or your theme’s functions.php.

---

Actions

Quote Posting

bpquotes_quote_posted

Fires after any quote activity is saved and metadata is written.

do_action( 'bpquotes_quote_posted', $user_id, $activity_id, $quote_data );

Parameter	Type	Description
$user_id	int	ID of the member who posted
$activity_id	int	BuddyPress activity ID
$quote_data	array	Background metadata (bg-type, bg-value, bg-inverted-value)

This is the primary hook for gamification integrations and any post-posting logic.

---

bpquotes_user_posted_quote

Fires after any quote post. Provides the background type and group context.

do_action( 'bpquotes_user_posted_quote', $user_id, $activity_id, $quote_type, $group_id );

Parameter	Type	Description
$user_id	int	ID of the member who posted
$activity_id	int	BuddyPress activity ID
$quote_type	string	Background type: quotesimg or quotescolor
$group_id	int	BuddyPress group ID, or 0 for non-group posts

---

bpquotes_post_quote

Fires after any quote is posted. Alias used by gamification triggers.

do_action( 'bpquotes_post_quote', $user_id, $activity_id, $quote_data );

---

bpquotes_post_image_quote

Fires when a quote with an image background is posted.

do_action( 'bpquotes_post_image_quote', $user_id, $activity_id, $quote_data );

---

bpquotes_post_color_quote

Fires when a quote with a color or gradient background is posted.

do_action( 'bpquotes_post_color_quote', $user_id, $activity_id, $quote_data );

---

bpquotes_post_group_quote

Fires when a quote is posted inside a BuddyPress group.

do_action( 'bpquotes_post_group_quote', $user_id, $activity_id, $quote_data );

---

bpquotes_user_posted_image_quote

Fires after an image-background quote is posted.

do_action( 'bpquotes_user_posted_image_quote', $user_id, $activity_id );

---

bpquotes_user_posted_color_quote

Fires after a color-background quote is posted.

do_action( 'bpquotes_user_posted_color_quote', $user_id, $activity_id );

---

bpquotes_user_posted_group_quote

Fires after a quote is posted in a group.

do_action( 'bpquotes_user_posted_group_quote', $user_id, $activity_id );

---

bpquotes_after_quote_posted

Fires after every quote post. Provides all context in one action.

do_action( 'bpquotes_after_quote_posted', $user_id, $activity_id, $bg_type, $group_id );

Parameter	Type	Description
$user_id	int	Member ID
$activity_id	int	Activity ID
$bg_type	string	Background type
$group_id	int	Group ID, or 0

---

bpquotes_scheduled_post_published

Fires after a scheduled quote post is successfully published to the activity feed.

do_action( 'bpquotes_scheduled_post_published', $activity_id, $user_id, $id );

Parameter	Type	Description
$activity_id	int	Newly created activity ID
$user_id	int	Member who originally scheduled the post
$id	int	Row ID from the bpquotes_scheduled_posts table

---

Filters

Settings and Configuration

bpquotes_get_setting

Fires for every BPQuote_Settings::get() call. Returning a non-null value overrides the stored setting at runtime.

add_filter( 'bpquotes_get_setting', function( $value, $key, $group ) {
    if ( 'digest_enabled' === $key ) {
        return 'yes'; // Force digest on for all environments.
    }
    return $value;
}, 10, 3 );

Parameter	Type	Description
$value	mixed	Resolved setting value
$key	string	Setting key
$group	string	general or integrations

Returns: mixed — The (optionally modified) setting value.

---

bpquotes_sanitize_settings

Filters the general settings array after user input is sanitised, before saving.

add_filter( 'bpquotes_sanitize_settings', function( $settings ) {
    // Add a custom default.
    $settings['my_custom_key'] = sanitize_text_field( $_POST['my_custom_key'] ?? '' );
    return $settings;
} );

Returns: array — Sanitised settings to persist.

---

bpquotes_sanitize_integration_settings

Filters the integrations settings array (myCred, digest, AI, scheduled) after sanitisation.

add_filter( 'bpquotes_sanitize_integration_settings', function( $settings, $raw_input ) {
    return $settings;
}, 10, 2 );

Returns: array

---

Rendering and Display

bpquotes_background_text_color

Filters the text color resolved for a background spec. Use this to override the auto-detected contrast color.

add_filter( 'bpquotes_background_text_color', function( $color, $spec ) {
    // Force white text on all image backgrounds.
    if ( 'quotesimg' === ( $spec['bg-type'] ?? '' ) ) {
        return '#ffffff';
    }
    return $color;
}, 10, 2 );

Parameter	Type	Description
$color	string	Resolved CSS color string
$spec	array	Background specification array

Returns: string — CSS color value.

---

bpquotes_resolve_preset

Intercepts the preset lookup before the plugin queries the database. Return a non-null value to supply the preset data directly.

add_filter( 'bpquotes_resolve_preset', function( $null, $id ) {
    if ( 42 === $id ) {
        return array( 'name' => 'My Preset', 'bg_type' => 'quotescolor', 'bg_value' => '#ff0000' );
    }
    return $null;
}, 10, 2 );

Parameter	Type	Description
$null	null	Always null on entry
$id	int	Preset ID being looked up

Returns: array|null — Preset data array to use, or null to fall through to the database lookup.

---

bpquotes_watermark_text

Filters the watermark string baked into exported PNG images.

add_filter( 'bpquotes_watermark_text', function( $text, $activity ) {
    $author = bp_core_get_user_displayname( $activity->user_id );
    return $text . ' — ' . $author;
}, 10, 2 );

Parameter	Type	Description
$text	string	Watermark text from settings
$activity	object	BuddyPress activity object

Returns: string

---

bpquotes_share_targets

Filters the share-target array before the share modal renders. Add, remove, or reorder social share buttons.

add_filter( 'bpquotes_share_targets', function( $all, $png_url, $page_url, $text ) {
    // Add a custom Mastodon share button.
    $all['mastodon'] = array(
        'label' => 'Mastodon',
        'url'   => 'https://mastodon.social/share?text=' . rawurlencode( $text . ' ' . $page_url ),
    );
    // Remove Pinterest.
    unset( $all['pinterest'] );
    return $all;
}, 10, 4 );

Parameter	Type	Description
$all	array	Current share-target definitions
$png_url	string	URL of the rendered PNG
$page_url	string	Permalink of the activity
$text	string	Plain-text quote excerpt

Returns: array

---

bpquotes_fonts_by_locale

Filters the font fallback chain used for non-Latin scripts (Devanagari, CJK, Arabic, etc.).

add_filter( 'bpquotes_fonts_by_locale', function( $fonts ) {
    $fonts['hi_IN'] = 'Tiro Devanagari, serif';
    return $fonts;
} );

Returns: array — Locale-to-font-stack map.

---

Digest

bpquotes_digest_landing_url

Filters the “See all top quotes” URL in the digest email footer.

add_filter( 'bpquotes_digest_landing_url', function( $url, $page_id ) {
    return home_url( '/top-quotes/' );
}, 10, 2 );

Parameter	Type	Description
$url	string	Current landing URL
$page_id	int	The page ID set in settings (0 if none)

Returns: string — URL.

---

bpquotes_digest_query_args

Filters the query arguments used to fetch quotes for the digest email.

add_filter( 'bpquotes_digest_query_args', function( $args ) {
    $args['days'] = 14; // Include quotes from the last 14 days.
    return $args;
} );

Returns: array

---

AI

bpquotes_ai_request_timeout

Filters the HTTP timeout (in seconds) for AI provider API calls.

add_filter( 'bpquotes_ai_request_timeout', function( $seconds ) {
    return 20; // Allow more time for large Ollama models.
} );

Returns: int — Timeout in seconds.

---

Admin

bpquote_admin_tabs

Filters the array of admin tab definitions rendered in the admin menu.

add_filter( 'bpquote_admin_tabs', function( $tabs ) {
    $tabs['my_tab'] = array( 'label' => 'My Tab', 'cap' => 'manage_options' );
    return $tabs;
} );

Returns: array

---

bpquote_admin_view_map

Filters the tab-slug to view-file map.

Returns: array

---

bpquote_admin_settings_group_map

Filters the mapping of admin tab slugs to settings option-group names.

Returns: array

---

Statistics

bpquotes_statistics

Filters the statistics array returned by bpquotes_get_statistics().

add_filter( 'bpquotes_statistics', function( $stats ) {
    $stats['custom_metric'] = my_get_custom_metric();
    return $stats;
} );

Returns: array — Statistics array with keys total_quotes, image_quotes, color_quotes, users_using_quotes.

---

bpquotes_logs_retention_days

Filters how many days of activity log entries are kept. Entries older than this are removed by the daily bpquotes_cleanup_logs cron job.

add_filter( 'bpquotes_logs_retention_days', function( $days ) {
    return 180; // Keep 6 months of logs.
} );

Returns: int — Number of days to retain.

---

Activity Meta Helpers

alter_is_quoted_activity

Filters the return value of bpquotes_is_quoted_activity().

Returns: bool

---

alter_bpquotes_get_quote_class

Filters the background type string returned for an activity.

Returns: string — Background type (quotesimg, quotescolor, etc.).

---

alter_bpquotes_get_quote_value

Filters the background value (URL or color) for an activity.

Returns: string

---

alter_bpquotes_get_quote_inverted_value

Filters the inverted (text) color value for an activity.

Returns: string