Contents

Code Reference Classes BP_Suggestions

BP_Suggestions

Base class for the BuddyPress Suggestions API.

Description

Originally built to power BuddyPress’ at-mentions suggestions, it’s flexible enough to be used for similar kinds of future core requirements, or those desired by third-party developers.

To implement a new suggestions service, create a new class that extends this one, and update the list of default services in bp_core_get_suggestions(). If you’re building a plugin, it’s recommend that you use the bp_suggestions_services filter to do this. 🙂

While the implementation of the query logic is left to you, it should be as quick and efficient as possible. When implementing the abstract methods in this class, pay close attention to the recommendations provided in the phpDoc blocks, particularly the expected return types.

Source

File: bp-core/classes/class-bp-suggestions.php

28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
abstract class BP_Suggestions {
 
    /**
     * Default arguments common to all suggestions services.
     *
     * If your custom service requires further defaults, add them here.
     *
     * @since BuddyPress 2.1.0
     * @var array
     */
    protected $default_args = array(
        'limit' => 16,
        'term'  => '',
        'type'  => '',
    );
 
    /**
     * Holds the arguments for the query (about to made to the suggestions service).
     *
     * This includes `$default_args`, as well as the user-supplied values.
     *
     * @since BuddyPress 2.1.0
     * @var array
     */
    protected $args = array(
    );
 
 
    /**
     * Constructor.
     *
     * @since BuddyPress 2.1.0
     *
     * @param array $args Optional. If set, used as the parameters for the suggestions service query.
     */
    public function __construct( array $args = array() ) {
        if ( ! empty( $args ) ) {
            $this->set_query( $args );
        }
    }
 
    /**
     * Set the parameters for the suggestions service query.
     *
     * @since BuddyPress 2.1.0
     *
     * @param array $args {
     *     @type int    $limit Maximum number of results to display. Optional, default: 16.
     *     @type string $type  The name of the suggestion service to use for the request. Mandatory.
     *     @type string $term  The suggestion service will try to find results that contain this string.
     *                         Mandatory.
     * }
     */
    public function set_query( array $args = array() ) {
        $this->args = wp_parse_args( $args, $this->default_args );
    }
 
    /**
     * Validate and sanitise the parameters for the suggestion service query.
     *
     * Be sure to call this class' version of this method when implementing it in your own service.
     * If validation fails, you must return a WP_Error object.
     *
     * @since BuddyPress 2.1.0
     *
     * @return true|WP_Error If validation fails, return a WP_Error object. On success, return true (bool).
     */
    public function validate() {
        $this->args['limit'] = absint( $this->args['limit'] );
        $this->args['term']  = trim( sanitize_text_field( $this->args['term'] ) );
 
        /**
         * Filters the arguments to be validated for the BP_Suggestions query.
         *
         * @since BuddyPress 2.1.0
         *
         * @param BP_Suggestions $value Arguments to be validated.
         * @param BP_Suggestions $this  Current BP_Suggestions instance.
         */
        $this->args          = apply_filters( 'bp_suggestions_args', $this->args, $this );
 
        // Check for invalid or missing mandatory parameters.
        if ( ! $this->args['limit'] || ! $this->args['term'] ) {
            return new WP_Error( 'missing_parameter' );
        }
 
        // Check for blocked users (e.g. deleted accounts, or spammers).
        if ( is_user_logged_in() && ! bp_is_user_active( get_current_user_id() ) ) {
            return new WP_Error( 'invalid_user' );
        }
 
        /**
         * Filters the status of validation for the BP_Suggestions query.
         *
         * @since BuddyPress 2.1.0
         *
         * @param bool           $value Whether or not the values are valid.
         * @param BP_Suggestions $this  Current BP_Suggestions instance.
         */
        return apply_filters( 'bp_suggestions_validate_args', true, $this );
    }
 
    /**
     * Find and return a list of suggestions that match the query.
     *
     * The return type is important. If no matches are found, an empty array must be returned.
     * Matches must be returned as objects in an array.
     *
     * The object format for each match must be: { 'ID': string, 'image': string, 'name': string }
     * For example: { 'ID': 'admin', 'image': 'http://example.com/logo.png', 'name': 'Name Surname' }
     *
     * @since BuddyPress 2.1.0
     *
     * @return array|WP_Error Array of results. If there were problems, returns a WP_Error object.
     */
    abstract public function get_suggestions();
}

Expand full source code Collapse full source code

Changelog

Changelog
Version Description
BuddyPress 2.1.0 Introduced.
Used By
Used By Description
bp-core/classes/class-bp-members-suggestions.php: BP_Members_Suggestions

Adds support for user at-mentions to the Suggestions API.

Methods

  • __construct — Constructor.
  • get_suggestions — Find and return a list of suggestions that match the query.
  • set_query — Set the parameters for the suggestions service query.
  • validate — Validate and sanitise the parameters for the suggestion service query.

Questions?

We're always happy to help with code or other questions you might have! Search our developer docs, contact support, or connect with our sales team.