Skip to:
Content

BuddyPress.org


Ignore:
Timestamp:
12/04/2013 02:07:20 AM (11 years ago)
Author:
boonebgorges
Message:

Improve documentation in the Groups component. See #5022

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/bp-groups/bp-groups-classes.php

    r7616 r7645  
    1111if ( !defined( 'ABSPATH' ) ) exit;
    1212
     13/**
     14 * BuddyPress Group object.
     15 */
    1316class BP_Groups_Group {
     17
     18    /**
     19     * ID of the group.
     20     *
     21     * @access public
     22     * @var int
     23     */
    1424    public $id;
     25
     26    /**
     27     * User ID of the group's creator.
     28     *
     29     * @access public
     30     * @var int
     31     */
    1532    public $creator_id;
     33
     34    /**
     35     * Name of the group.
     36     *
     37     * @access public
     38     * @var string
     39     */
    1640    public $name;
     41
     42    /**
     43     * Group slug.
     44     *
     45     * @access public
     46     * @var string
     47     */
    1748    public $slug;
     49
     50    /**
     51     * Group description.
     52     *
     53     * @access public
     54     * @var string
     55     */
    1856    public $description;
     57
     58    /**
     59     * Group status.
     60     *
     61     * Core statuses are 'public', 'private', and 'hidden'.
     62     *
     63     * @access public
     64     * @var string
     65     */
    1966    public $status;
     67
     68    /**
     69     * Should (legacy) bbPress forums be enabled for this group?
     70     *
     71     * @access public
     72     * @var int
     73     */
    2074    public $enable_forum;
     75
     76    /**
     77     * Date the group was created.
     78     *
     79     * @access public
     80     * @var string
     81     */
    2182    public $date_created;
    2283
     84    /**
     85     * Data about the group's admins.
     86     *
     87     * @access public
     88     * @var array
     89     */
    2390    public $admins;
     91
     92    /**
     93     * Data about the group's moderators.
     94     *
     95     * @access public
     96     * @var array
     97     */
    2498    public $mods;
     99
     100    /**
     101     * Total count of group members.
     102     *
     103     * @access public
     104     * @var int
     105     */
    25106    public $total_member_count;
    26107
    … …  
    28109     * Is the current user a member of this group?
    29110     *
    30      * @since BuddyPress (1.2)
     111     * @since BuddyPress (1.2.0)
    31112     * @var bool
    32113     */
    … …  
    52133     * Timestamp of the last activity that happened in this group.
    53134     *
    54      * @since BuddyPress (1.2)
     135     * @since BuddyPress (1.2.0)
    55136     * @var string
    56137     */
    … …  
    60141     * If this is a private or hidden group, does the current user have access?
    61142     *
    62      * @since BuddyPress (1.6)
     143     * @since BuddyPress (1.6.0)
    63144     * @var bool
    64145     */
    65146    public $user_has_access;
    66147
     148    /**
     149     * Constructor method.
     150     *
     151     * @param int $id Optional. If the ID of an existing group is provided,
     152     *        the object will be pre-populated with info about that group.
     153     */
    67154    public function __construct( $id = null ) {
    68155        if ( !empty( $id ) ) {
    … …  
    72159    }
    73160
     161    /**
     162     * Set up data about the current group.
     163     */
    74164    public function populate() {
    75165        global $wpdb, $bp;
    … …  
    115205    }
    116206
     207    /**
     208     * Save the current group to the database.
     209     *
     210     * @return bool True on success, false on failure.
     211     */
    117212    public function save() {
    118213        global $wpdb, $bp;
    … …  
    186281    }
    187282
     283    /**
     284     * Delete the current group.
     285     *
     286     * @return bool True on success, false on failure.
     287     */
    188288    public function delete() {
    189289        global $wpdb, $bp;
    … …  
    213313    }
    214314
    215     /** Static Methods ********************************************************/
    216 
     315    /** Static Methods ****************************************************/
     316
     317    /**
     318     * Get whether a group exists for a given slug.
     319     *
     320     * @param string $slug Slug to check.
     321     * @param string $table_name Optional. Name of the table to check
     322     *        against. Default: $bp->groups->table_name.
     323     * @return string|null ID of the group, if one is found, else null.
     324     */
    217325    public static function group_exists( $slug, $table_name = false ) {
    218326        global $wpdb, $bp;
    … …  
    227335    }
    228336
     337    /**
     338     * Get the ID of a group by the group's slug.
     339     *
     340     * Alias of {@link BP_Groups_Group::group_exists()}.
     341     *
     342     * @param string $slug See {@link BP_Groups_Group::group_exists()}.
     343     * @return string|null See {@link BP_Groups_Group::group_exists()}.
     344     */
    229345    public static function get_id_from_slug( $slug ) {
    230346        return BP_Groups_Group::group_exists( $slug );
    231347    }
    232348
     349    /**
     350     * Get IDs of users with outstanding invites to a given group from a specified user.
     351     *
     352     * @param int $user_id ID of the inviting user.
     353     * @param int $group_id ID of the group.
     354     * @return array IDs of users who have been invited to the group by the
     355     *         user but have not yet accepted.
     356     */
    233357    public static function get_invites( $user_id, $group_id ) {
    234358        global $wpdb, $bp;
    … …  
    236360    }
    237361
     362    /**
     363     * Get a list of a user's groups, filtered by a search string.
     364     *
     365     * @param string $filter Search term. Matches against 'name' and
     366     *        'description' fields.
     367     * @param int $user_id ID of the user whose groups are being searched.
     368     *        Default: the displayed user.
     369     * @param mixed $order Not used.
     370     * @param int $limit Optional. The max number of results to return.
     371     *        Default: null (no limit).
     372     * @param int $page Optional. The page offset of results to return.
     373     *        Default: null (no limit).
     374     * @return array {
     375     *     @type array $groups Array of matched and paginated group objects.
     376     *     @type int $total Total count of groups matching the query.
     377     * }
     378     */
    238379    public static function filter_user_groups( $filter, $user_id = 0, $order = false, $limit = null, $page = null ) {
    239380        global $wpdb, $bp;
    … …  
    264405
    265406    /**
    266      * @todo Deprecate in favor of get()
     407     * Get a list of groups, filtered by a search string.
     408     *
     409     * @param string $filter Search term. Matches against 'name' and
     410     *        'description' fields.
     411     * @param int $limit Optional. The max number of results to return.
     412     *        Default: null (no limit).
     413     * @param int $page Optional. The page offset of results to return.
     414     *        Default: null (no limit).
     415     * @param string $sort_by Column to sort by. Default: false (default
     416     *        sort).
     417     * @param string $order ASC or DESC. Default: false (default sort).
     418     * @return array {
     419     *     @type array $groups Array of matched and paginated group objects.
     420     *     @type int $total Total count of groups matching the query.
     421     * }
    267422     */
    268423    public static function search_groups( $filter, $limit = null, $page = null, $sort_by = false, $order = false ) {
    … …  
    291446    }
    292447
     448    /**
     449     * Check for the existence of a slug.
     450     *
     451     * @param string $slug Slug to check.
     452     * @return string|null The slug, if found. Otherwise null.
     453     */
    293454    public static function check_slug( $slug ) {
    294455        global $wpdb, $bp;
    … …  
    297458    }
    298459
     460    /**
     461     * Get the slug for a given group ID.
     462     *
     463     * @param int $group_id ID of the group.
     464     * @return string|null The slug, if found. Otherwise null.
     465     */
    299466    public static function get_slug( $group_id ) {
    300467        global $wpdb, $bp;
    … …  
    303470    }
    304471
     472    /**
     473     * Check whether a given group has any members.
     474     *
     475     * @param int $group_id ID of the group.
     476     * @return bool True if the group has members, otherwise false.
     477     */
    305478    public static function has_members( $group_id ) {
    306479        global $wpdb, $bp;
    … …  
    314487    }
    315488
     489    /**
     490     * Check whether a group has outstanding membership requests.
     491     *
     492     * @param int $group_id ID of the group.
     493     * @return int|null The number of outstanding requests, or null if
     494     *         none are found.
     495     */
    316496    public static function has_membership_requests( $group_id ) {
    317497        global $wpdb, $bp;
    … …  
    320500    }
    321501
     502    /**
     503     * Get outstanding membership requests for a group.
     504     *
     505     * @param int $group_id ID of the group.
     506     * @param int $limit Optional. Max number of results to return.
     507     *        Default: null (no limit).
     508     * @param int $page Optional. Page offset of results returned. Default:
     509     *        null (no limit).
     510     * @return array {
     511     *     @type array $requests The requested page of located requests.
     512     *     @type int $total Total number of requests outstanding for the
     513     *           group.
     514     * }
     515     */
    322516    public static function get_membership_requests( $group_id, $limit = null, $page = null ) {
    323517        global $wpdb, $bp;
    … …  
    333527    }
    334528
     529    /**
     530     * Query for groups.
     531     *
     532     * @see WP_Meta_Query::queries for a description of the 'meta_query'
     533     *      parameter format.
     534     *
     535     * @param array {
     536     *     Array of parameters. All items are optional.
     537     *     @type string $type Optional. Shorthand for certain orderby/
     538     *           order combinations. 'newest', 'active', 'popular',
     539     *           'alphabetical', 'random'. When present, will override
     540     *           orderby and order params. Default: null.
     541     *     @type string $orderby Optional. Property to sort by.
     542     *           'date_created', 'last_activity', 'total_member_count',
     543     *           'name', 'random'. Default: 'date_created'.
     544     *     @type string $order Optional. Sort order. 'ASC' or 'DESC'.
     545     *           Default: 'DESC'.
     546     *     @type int $per_page Optional. Number of items to return per page
     547     *           of results. Default: null (no limit).
     548     *     @type int $page Optional. Page offset of results to return.
     549     *           Default: null (no limit).
     550     *     @type int $user_id Optional. If provided, results will be limited
     551     *           to groups of which the specified user is a member. Default:
     552     *           null.
     553     *     @type string $search_terms Optional. If provided, only groups
     554     *           whose names or descriptions match the search terms will be
     555     *           returned. Default: false.
     556     *     @type array $meta_query Optional. An array of meta_query
     557     *           conditions. See {@link WP_Meta_Query::queries} for
     558     *           description.
     559     *     @type array|string Optional. Array or comma-separated list of
     560     *           group IDs. Results will be limited to groups within the
     561     *           list. Default: false.
     562     *     @type bool $populate_extras Whether to fetch additional
     563     *           information (such as member count) about groups. Default:
     564     *           true.
     565     *     @type array|string Optional. Array or comma-separated list of
     566     *           group IDs. Results will exclude the listed groups.
     567     *           Default: false.
     568     *     @type bool $show_hidden Whether to include hidden groups in
     569     *           results. Default: false.
     570     * }
     571     * @return array {
     572     *     @type array $groups Array of group objects returned by the
     573     *           paginated query.
     574     *     @type int $total Total count of all groups matching non-
     575     *           paginated query params.
     576     * }
     577     */
    335578    public static function get( $args = array() ) {
    336579        global $wpdb, $bp;
    … …  
    547790     * AND keyword from the 'where' clause).
    548791     *
    549      * @since BuddyPress (1.8)
     792     * @since BuddyPress (1.8.0)
    550793     * @access protected
    551794     *
    552795     * @param array $meta_query An array of meta_query filters. See the
    553      *   documentation for WP_Meta_Query for details.
    554      * @return array $sql_array 'join' and 'where' clauses
     796     *        documentation for {@link WP_Meta_Query} for details.
     797     * @return array $sql_array 'join' and 'where' clauses.
    555798     */
    556799    protected static function get_meta_query_sql( $meta_query = array() ) {
    … …  
    599842
    600843    /**
    601      * Convert the 'type' parameter to 'order' and 'orderby'
    602      *
    603      * @since BuddyPress (1.8)
     844     * Convert the 'type' parameter to 'order' and 'orderby'.
     845     *
     846     * @since BuddyPress (1.8.0)
    604847     * @access protected
    605      * @param string $type The 'type' shorthand param
    606      * @return array 'order' and 'orderby'
     848     *
     849     * @param string $type The 'type' shorthand param.
     850     * @return array {
     851     *  @type string $order SQL-friendly order string.
     852     *  @type string $orderby SQL-friendly orderby column name.
     853     * }
    607854     */
    608855    protected static function convert_type_to_order_orderby( $type = '' ) {
    … …  
    640887
    641888    /**
    642      * Convert the 'orderby' param into a proper SQL term/column
    643      *
    644      * @since BuddyPress (1.8)
     889     * Convert the 'orderby' param into a proper SQL term/column.
     890     *
     891     * @since BuddyPress (1.8.0)
    645892     * @access protected
    646      * @param string $orderby
    647      * @return string $order_by_term
     893     *
     894     * @param string $orderby Orderby term as passed to get().
     895     * @return string $order_by_term SQL-friendly orderby term.
    648896     */
    649897    protected static function convert_orderby_to_order_by_term( $orderby ) {
Note: See TracChangeset for help on using the changeset viewer.