[Summary view] [Print] [Text view]

   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  
  70      /**
  71       * Set the parameters for the suggestions service query.
  72       *
  73       * @since 2.1.0
  74       *
  75       * @param array $args {
  76       *     @type int    $limit Maximum number of results to display. Optional, default: 16.
  77       *     @type string $type  The name of the suggestion service to use for the request. Mandatory.
  78       *     @type string $term  The suggestion service will try to find results that contain this string.
  79       *                         Mandatory.
  80       * }
  81       */
  82  	public function set_query( array $args = array() ) {
  83          $this->args = bp_parse_args(
  84              $args,
  85              $this->default_args
  86          );
  87      }
  88  
  89      /**
  90       * Validate and sanitise the parameters for the suggestion service query.
  91       *
  92       * Be sure to call this class' version of this method when implementing it in your own service.
  93       * If validation fails, you must return a WP_Error object.
  94       *
  95       * @since 2.1.0
  96       *
  97       * @return true|WP_Error If validation fails, return a WP_Error object. On success, return true (bool).
  98       */
  99  	public function validate() {
 100          $this->args['limit'] = absint( $this->args['limit'] );
 101          $this->args['term']  = trim( sanitize_text_field( $this->args['term'] ) );
 102  
 103          /**
 104           * Filters the arguments to be validated for the BP_Suggestions query.
 105           *
 106           * @since 2.1.0
 107           *
 108           * @param BP_Suggestions $value Arguments to be validated.
 109           * @param BP_Suggestions $this  Current BP_Suggestions instance.
 110           */
 111          $this->args          = apply_filters( 'bp_suggestions_args', $this->args, $this );
 112  
 113          // Check for invalid or missing mandatory parameters.
 114          if ( ! $this->args['limit'] || ! $this->args['term'] ) {
 115              return new WP_Error( 'missing_parameter' );
 116          }
 117  
 118          // Check for blocked users (e.g. deleted accounts, or spammers).
 119          if ( is_user_logged_in() && ! bp_is_user_active( get_current_user_id() ) ) {
 120              return new WP_Error( 'invalid_user' );
 121          }
 122  
 123          /**
 124           * Filters the status of validation for the BP_Suggestions query.
 125           *
 126           * @since 2.1.0
 127           *
 128           * @param bool           $value Whether or not the values are valid.
 129           * @param BP_Suggestions $this  Current BP_Suggestions instance.
 130           */
 131          return apply_filters( 'bp_suggestions_validate_args', true, $this );
 132      }
 133  
 134      /**
 135       * Find and return a list of suggestions that match the query.
 136       *
 137       * The return type is important. If no matches are found, an empty array must be returned.
 138       * Matches must be returned as objects in an array.
 139       *
 140       * The object format for each match must be: { 'ID': string, 'image': string, 'name': string }
 141       * For example: { 'ID': 'admin', 'image': 'http://example.com/logo.png', 'name': 'Name Surname' }
 142       *
 143       * @since 2.1.0
 144       *
 145       * @return array|WP_Error Array of results. If there were problems, returns a WP_Error object.
 146       */
 147      abstract public function get_suggestions();
 148  }