BP_Suggestions

Base class for the BuddyPress Suggestions API.

Defined (1)

The class is defined in the following location(s).

/bp-core/classes/class-bp-suggestions.php  
  1. abstract class BP_Suggestions { 
  2.  
  3. /** 
  4. * Default arguments common to all suggestions services. 
  5. * If your custom service requires further defaults, add them here. 
  6. * @since 2.1.0 
  7. * @var array 
  8. */ 
  9. protected $default_args = array( 
  10. 'limit' => 16,  
  11. 'term' => '',  
  12. 'type' => '',  
  13. ); 
  14.  
  15. /** 
  16. * Holds the arguments for the query (about to made to the suggestions service). 
  17. * This includes `$default_args`, as well as the user-supplied values. 
  18. * @since 2.1.0 
  19. * @var array 
  20. */ 
  21. protected $args = array( 
  22. ); 
  23.  
  24.  
  25. /** 
  26. * Constructor. 
  27. * @since 2.1.0 
  28. * @param array $args Optional. If set, used as the parameters for the suggestions service query. 
  29. */ 
  30. public function __construct( array $args = array() ) { 
  31. if ( ! empty( $args ) ) { 
  32. $this->set_query( $args ); 
  33.  
  34. /** 
  35. * Set the parameters for the suggestions service query. 
  36. * @since 2.1.0 
  37. * @param array $args { 
  38. * @type int $limit Maximum number of results to display. Optional, default: 16. 
  39. * @type string $type The name of the suggestion service to use for the request. Mandatory. 
  40. * @type string $term The suggestion service will try to find results that contain this string. 
  41. * Mandatory. 
  42. * } 
  43. */ 
  44. public function set_query( array $args = array() ) { 
  45. $this->args = wp_parse_args( $args, $this->default_args ); 
  46.  
  47. /** 
  48. * Validate and sanitise the parameters for the suggestion service query. 
  49. * Be sure to call this class' version of this method when implementing it in your own service. 
  50. * If validation fails, you must return a WP_Error object. 
  51. * @since 2.1.0 
  52. * @return true|WP_Error If validation fails, return a WP_Error object. On success, return true (bool). 
  53. */ 
  54. public function validate() { 
  55. $this->args['limit'] = absint( $this->args['limit'] ); 
  56. $this->args['term'] = trim( sanitize_text_field( $this->args['term'] ) ); 
  57.  
  58. /** 
  59. * Filters the arguments to be validated for the BP_Suggestions query. 
  60. * @since 2.1.0 
  61. * @param BP_Suggestions $value Arguments to be validated. 
  62. * @param BP_Suggestions $this Current BP_Suggestions instance. 
  63. */ 
  64. $this->args = apply_filters( 'bp_suggestions_args', $this->args, $this ); 
  65.  
  66. // Check for invalid or missing mandatory parameters. 
  67. if ( ! $this->args['limit'] || ! $this->args['term'] ) { 
  68. return new WP_Error( 'missing_parameter' ); 
  69.  
  70. // Check for blocked users (e.g. deleted accounts, or spammers). 
  71. if ( is_user_logged_in() && ! bp_is_user_active( get_current_user_id() ) ) { 
  72. return new WP_Error( 'invalid_user' ); 
  73.  
  74. /** 
  75. * Filters the status of validation for the BP_Suggestions query. 
  76. * @since 2.1.0 
  77. * @param bool $value Whether or not the values are valid. 
  78. * @param BP_Suggestions $this Current BP_Suggestions instance. 
  79. */ 
  80. return apply_filters( 'bp_suggestions_validate_args', true, $this ); 
  81.  
  82. /** 
  83. * Find and return a list of suggestions that match the query. 
  84. * The return type is important. If no matches are found, an empty array must be returned. 
  85. * Matches must be returned as objects in an array. 
  86. * The object format for each match must be: { 'ID': string, 'image': string, 'name': string } 
  87. * For example: { 'ID': 'admin', 'image': 'http://example.com/logo.png', 'name': 'Name Surname' } 
  88. * @since 2.1.0 
  89. * @return array|WP_Error Array of results. If there were problems, returns a WP_Error object. 
  90. */ 
  91. abstract public function get_suggestions();