[ Index ] |
PHP Cross Reference of BuddyPress |
[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 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Sat Mar 6 01:01:37 2021 | Cross-referenced by PHPXref 0.7.1 |