Skip to:
Content

BuddyPress.org


Ignore:
Timestamp:
10/10/2013 02:44:05 PM (10 years ago)
Author:
boonebgorges
Message:

Inline docs improvements in Blogs component:

  • bp-blogs-actions.php
  • bp-blogs-activity.php
  • bp-blogs-buddybar.php
  • bp-blogs-cache.php
  • bp-blogs-classes.php

See #5022

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/bp-blogs/bp-blogs-classes.php

    r7317 r7407  
    22
    33/**
    4  * BuddyPress Blogs Classes
     4 * BuddyPress Blogs Classes.
    55 *
    66 * @package BuddyPress
     
    1212
    1313/**
    14  * The main BuddyPress blog class
     14 * The main BuddyPress blog class.
     15 *
     16 * A BP_Blogs_Object represents a link between a specific WordPress blog on a
     17 * network and a specific user on that blog.
    1518 *
    1619 * @since BuddyPress (1.0)
    17  * @package BuddyPress
    18  * @subpackage BlogsClasses
    1920 */
    2021class BP_Blogs_Blog {
     
    2324    public $blog_id;
    2425
     26    /**
     27     * Constructor method.
     28     *
     29     * @param int $id Optional. The ID of the blog.
     30     */
    2531    public function __construct( $id = null ) {
    2632        if ( !empty( $id ) ) {
     
    3036    }
    3137
     38    /**
     39     * Populate the object with data about the specific activity item.
     40     */
    3241    public function populate() {
    3342        global $wpdb, $bp;
     
    3948    }
    4049
     50    /**
     51     * Save the BP blog data to the database.
     52     *
     53     * @return bool True on success, false on failure.
     54     */
    4155    public function save() {
    4256        global $wpdb, $bp;
     
    7488    }
    7589
     90    /**
     91     * Check whether an association between this user and this blog exists.
     92     *
     93     * @return int The number of associations between the user and blog
     94     *         saved in the blog component tables.
     95     */
    7696    public function exists() {
    7797        global $bp, $wpdb;
     
    80100    }
    81101
    82     /* Static Functions */
    83 
     102    /** Static Methods ***************************************************/
     103
     104    /**
     105     * Retrieve a set of blog-user associations.
     106     *
     107     * @param string $type The order in which results should be returned.
     108     *        'active', 'alphabetical', 'newest', or 'random'.
     109     * @param int|bool $limit Optional. The maximum records to return.
     110     *        Default: false.
     111     * @param int|bool $page Optional. The page of records to return.
     112     *        Default: false (unlimited results).
     113     * @param int $user_id Optional. ID of the user whose blogs are being
     114     *        retrieved. Default: 0.
     115     * @param string|bool $search_terms Optional. Search by text stored in
     116     *        blogmeta (such as the blog name). Default: false.
     117     * @return array Multidimensional results array, structured as follows:
     118     *           'blogs' - Array of located blog objects
     119     *           'total' - A count of the total blogs matching the filter params
     120     */
    84121    public static function get( $type, $limit = false, $page = false, $user_id = 0, $search_terms = false ) {
    85122        global $bp, $wpdb;
     
    128165    }
    129166
     167    /**
     168     * Delete the record of a given blog for all users.
     169     *
     170     * @param int $blog_id The blog being removed from all users.
     171     * @return int|bool Number of rows deleted on success, false on failure.
     172     */
    130173    public static function delete_blog_for_all( $blog_id ) {
    131174        global $wpdb, $bp;
     
    135178    }
    136179
     180    /**
     181     * Delete the record of a given blog for a specific user.
     182     *
     183     * @param int $blog_id The blog being removed.
     184     * @param int $user_id Optional. The ID of the user from whom the blog
     185     *        is being removed. If absent, defaults to the logged-in user ID.
     186     * @return int|bool Number of rows deleted on success, false on failure.
     187     */
    137188    public static function delete_blog_for_user( $blog_id, $user_id = null ) {
    138189        global $wpdb, $bp;
     
    144195    }
    145196
     197    /**
     198     * Delete all of a user's blog associations in the BP tables.
     199     *
     200     * @param int $user_id Optional. The ID of the user whose blog
     201     *        associations are being deleted. If absent, defaults to
     202     *        logged-in user ID.
     203     * @return int|bool Number of rows deleted on success, false on failure.
     204     */
    146205    public static function delete_blogs_for_user( $user_id = null ) {
    147206        global $wpdb, $bp;
     
    153212    }
    154213
     214    /**
     215     * Get all of a user's blogs, as tracked by BuddyPress.
     216     *
     217     * Note that this is different from the WordPress function {@link get_blogs_of_user()};
     218     * the current method returns only those blogs that have been recorded
     219     * by BuddyPress, while the WP function does a true query of a user's
     220     * blog capabilities.
     221     *
     222     * @param int $user_id Optional. ID of the user whose blogs are being
     223     *        queried. Defaults to logged-in user.
     224     * @param bool $show_hidden Optional. Whether to include blogs that are
     225     *        not marked public. Defaults to true when viewing one's own
     226     *        profile.
     227     * @return array Multidimensional results array, structured as follows:
     228     *           'blogs' - Array of located blog objects
     229     *           'total' - A count of the total blogs for the user.
     230     */
    155231    public static function get_blogs_for_user( $user_id = 0, $show_hidden = false ) {
    156232        global $bp, $wpdb;
     
    179255    }
    180256
     257    /**
     258     * Get IDs of all of a user's blogs, as tracked by BuddyPress.
     259     *
     260     * This method always includes hidden blogs.
     261     *
     262     * @param int $user_id Optional. ID of the user whose blogs are being
     263     *        queried. Defaults to logged-in user.
     264     * @return int The number of blogs associated with the user.
     265     */
    181266    public static function get_blog_ids_for_user( $user_id = 0 ) {
    182267        global $bp, $wpdb;
     
    188273    }
    189274
     275    /**
     276     * Check whether a blog has been recorded by BuddyPress.
     277     *
     278     * @param int $blog_id ID of the blog being queried.
     279     * @return int|null The ID of the first located entry in the BP table
     280     *         on success, otherwise null.
     281     */
    190282    public static function is_recorded( $blog_id ) {
    191283        global $bp, $wpdb;
     
    194286    }
    195287
     288    /**
     289     * Return a count of associated blogs for a given user.
     290     *
     291     * Includes hidden blogs when the logged-in user is the same as the
     292     * $user_id parameter, or when the logged-in user has the bp_moderate
     293     * cap.
     294     *
     295     * @param int $user_id Optional. ID of the user whose blogs are being
     296     *        queried. Defaults to logged-in user.
     297     * @return int Blog count for the user.
     298     */
    196299    public static function total_blog_count_for_user( $user_id = null ) {
    197300        global $bp, $wpdb;
     
    208311    }
    209312
     313    /**
     314     * Return a list of blogs matching a search term.
     315     *
     316     * Matches against blog names and descriptions, as stored in the BP
     317     * blogmeta table.
     318     *
     319     * @param string $filter The search term.
     320     * @param int $limit Optional. The maximum number of items to return.
     321     *        Default: null (no limit).
     322     * @param int $page Optional. The page of results to return. Default:
     323     *        null (no limit).
     324     * @return array Multidimensional results array, structured as follows:
     325     *           'blogs' - Array of located blog objects
     326     *           'total' - A count of the total blogs matching the query.
     327     */
    210328    public static function search_blogs( $filter, $limit = null, $page = null ) {
    211329        global $wpdb, $bp;
     
    227345    }
    228346
     347    /**
     348     * Retrieve a list of all blogs.
     349     *
     350     * Query will include hidden blogs if the logged-in user has the
     351     * 'bp_moderate' cap.
     352     *
     353     * @param int $limit Optional. The maximum number of items to return.
     354     *        Default: null (no limit).
     355     * @param int $page Optional. The page of results to return. Default:
     356     *        null (no limit).
     357     * @return array Multidimensional results array, structured as follows:
     358     *           'blogs' - Array of located blog objects
     359     *           'total' - A count of the total blogs.
     360     */
    229361    public static function get_all( $limit = null, $page = null ) {
    230362        global $bp, $wpdb;
     
    239371    }
    240372
     373    /**
     374     * Retrieve a list of blogs whose names start with a given letter.
     375     *
     376     * Query will include hidden blogs if the logged-in user has the
     377     * 'bp_moderate' cap.
     378     *
     379     * @param string $letter. The letter you're looking for.
     380     * @param int $limit Optional. The maximum number of items to return.
     381     *        Default: null (no limit).
     382     * @param int $page Optional. The page of results to return. Default:
     383     *        null (no limit).
     384     * @return array Multidimensional results array, structured as follows:
     385     *           'blogs' - Array of located blog objects.
     386     *           'total' - A count of the total blogs matching the query.
     387     */
    241388    public static function get_by_letter( $letter, $limit = null, $page = null ) {
    242389        global $bp, $wpdb;
     
    257404    }
    258405
     406    /**
     407     * Fetch blog data not caught in the main query and append it to results array.
     408     *
     409     * Gets the following information, which is either unavailable at the
     410     * time of the original query, or is more efficient to look up in one
     411     * fell swoop:
     412     *   - The latest post for each blog, include Featured Image data
     413     *   - The blog description
     414     *
     415     * @param array $paged_blogs Array of results from the original query.
     416     * @param array $blog_ids Array of IDs returned from the original query.
     417     * @param string|bool $type Not currently used. Default: false.
     418     * @return array $paged_blogs The located blogs array, with the extras added.
     419     */
    259420    public static function get_blog_extras( &$paged_blogs, &$blog_ids, $type = false ) {
    260421        global $bp, $wpdb;
     
    311472    }
    312473
     474    /**
     475     * Check whether a given blog is hidden.
     476     *
     477     * Checks the 'public' column in the wp_blogs table.
     478     *
     479     * @param int $blog_id The ID of the blog being checked.
     480     * @return bool True if hidden (public = 0), false otherwise.
     481     */
    313482    public static function is_hidden( $blog_id ) {
    314483        global $wpdb;
Note: See TracChangeset for help on using the changeset viewer.