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