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

  1. <?php 
  2. /** 
  3. * Core component classes. 
  4. * 
  5. * @package BuddyPress 
  6. * @subpackage Core 
  7. * @since 2.1.0 
  8. */ 
  9.  
  10. // Exit if accessed directly. 
  11. defined( 'ABSPATH' ) || exit; 
  12.  
  13. /** 
  14. * Base class for the BuddyPress Suggestions API. 
  15. * 
  16. * Originally built to power BuddyPress' at-mentions suggestions, it's flexible enough to be used 
  17. * for similar kinds of future core requirements, or those desired by third-party developers. 
  18. * 
  19. * To implement a new suggestions service, create a new class that extends this one, and update 
  20. * the list of default services in {@link bp_core_get_suggestions()}. If you're building a plugin,  
  21. * it's recommend that you use the `bp_suggestions_services` filter to do this. :) 
  22. * 
  23. * While the implementation of the query logic is left to you, it should be as quick and efficient 
  24. * as possible. When implementing the abstract methods in this class, pay close attention to the 
  25. * recommendations provided in the phpDoc blocks, particularly the expected return types. 
  26. * 
  27. * @since 2.1.0 
  28. */ 
  29. abstract class BP_Suggestions { 
  30.  
  31. /** 
  32. * Default arguments common to all suggestions services. 
  33. * 
  34. * If your custom service requires further defaults, add them here. 
  35. * 
  36. * @since 2.1.0 
  37. * @var array 
  38. */ 
  39. protected $default_args = array( 
  40. 'limit' => 16,  
  41. 'term' => '',  
  42. 'type' => '',  
  43. ); 
  44.  
  45. /** 
  46. * Holds the arguments for the query (about to made to the suggestions service). 
  47. * 
  48. * This includes `$default_args`, as well as the user-supplied values. 
  49. * 
  50. * @since 2.1.0 
  51. * @var array 
  52. */ 
  53. protected $args = array( 
  54. ); 
  55.  
  56.  
  57. /** 
  58. * Constructor. 
  59. * 
  60. * @since 2.1.0 
  61. * 
  62. * @param array $args Optional. If set, used as the parameters for the suggestions service query. 
  63. */ 
  64. public function __construct( array $args = array() ) { 
  65. if ( ! empty( $args ) ) { 
  66. $this->set_query( $args ); 
  67.  
  68. /** 
  69. * Set the parameters for the suggestions service query. 
  70. * 
  71. * @since 2.1.0 
  72. * 
  73. * @param array $args { 
  74. * @type int $limit Maximum number of results to display. Optional, default: 16. 
  75. * @type string $type The name of the suggestion service to use for the request. Mandatory. 
  76. * @type string $term The suggestion service will try to find results that contain this string. 
  77. * Mandatory. 
  78. * } 
  79. */ 
  80. public function set_query( array $args = array() ) { 
  81. $this->args = wp_parse_args( $args, $this->default_args ); 
  82.  
  83. /** 
  84. * Validate and sanitise the parameters for the suggestion service query. 
  85. * 
  86. * Be sure to call this class' version of this method when implementing it in your own service. 
  87. * If validation fails, you must return a WP_Error object. 
  88. * 
  89. * @since 2.1.0 
  90. * 
  91. * @return true|WP_Error If validation fails, return a WP_Error object. On success, return true (bool). 
  92. */ 
  93. public function validate() { 
  94. $this->args['limit'] = absint( $this->args['limit'] ); 
  95. $this->args['term'] = trim( sanitize_text_field( $this->args['term'] ) ); 
  96.  
  97. /** 
  98. * Filters the arguments to be validated for the BP_Suggestions query. 
  99. * 
  100. * @since 2.1.0 
  101. * 
  102. * @param BP_Suggestions $value Arguments to be validated. 
  103. * @param BP_Suggestions $this Current BP_Suggestions instance. 
  104. */ 
  105. $this->args = apply_filters( 'bp_suggestions_args', $this->args, $this ); 
  106.  
  107. // Check for invalid or missing mandatory parameters. 
  108. if ( ! $this->args['limit'] || ! $this->args['term'] ) { 
  109. return new WP_Error( 'missing_parameter' ); 
  110.  
  111. // Check for blocked users (e.g. deleted accounts, or spammers). 
  112. if ( is_user_logged_in() && ! bp_is_user_active( get_current_user_id() ) ) { 
  113. return new WP_Error( 'invalid_user' ); 
  114.  
  115. /** 
  116. * Filters the status of validation for the BP_Suggestions query. 
  117. * 
  118. * @since 2.1.0 
  119. * 
  120. * @param bool $value Whether or not the values are valid. 
  121. * @param BP_Suggestions $this Current BP_Suggestions instance. 
  122. */ 
  123. return apply_filters( 'bp_suggestions_validate_args', true, $this ); 
  124.  
  125. /** 
  126. * Find and return a list of suggestions that match the query. 
  127. * 
  128. * The return type is important. If no matches are found, an empty array must be returned. 
  129. * Matches must be returned as objects in an array. 
  130. * 
  131. * The object format for each match must be: { 'ID': string, 'image': string, 'name': string } 
  132. * For example: { 'ID': 'admin', 'image': 'http://example.com/logo.png', 'name': 'Name Surname' } 
  133. * 
  134. * @since 2.1.0 
  135. * 
  136. * @return array|WP_Error Array of results. If there were problems, returns a WP_Error object. 
  137. */ 
  138. abstract public function get_suggestions(); 
.