Skip to:
Content

BuddyPress.org

Changeset 7393


Ignore:
Timestamp:
10/07/2013 09:57:01 PM (10 years ago)
Author:
boonebgorges
Message:

Additional documentation and docs standards adherence in bp-activity-classes.php

See #5022

Props ericlewis

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r7338 r7393  
    1010if ( !defined( 'ABSPATH' ) ) exit;
    1111
     12/**
     13 * Database interaction class for the BuddyPress activity component.
     14 *
     15 * Instance methods are available for creating/editing an activity,
     16 * static methods for querying activities.
     17 *
     18 * @since BuddyPress (1.0)
     19 */
    1220class BP_Activity_Activity {
     21
     22    /** Properties ************************************************************/
     23
     24    /**
     25     * ID of the activity item.
     26     *
     27     * @var int
     28     */
    1329    var $id;
     30
     31    /**
     32     * ID of the associated item.
     33     *
     34     * @var int
     35     */
    1436    var $item_id;
     37
     38    /**
     39     * ID of the associated secondary item.
     40     *
     41     * @var int
     42     */
    1543    var $secondary_item_id;
     44
     45    /**
     46     * ID of user associated with the activity item.
     47     *
     48     * @var int
     49     */
    1650    var $user_id;
     51
     52    /**
     53     * The primary URL for the activity in RSS feeds.
     54     *
     55     * @var string
     56     */
    1757    var $primary_link;
     58
     59    /**
     60     * BuddyPress component the activity item relates to.
     61     *
     62     * @var string
     63     */
    1864    var $component;
     65
     66    /**
     67     * Activity type, eg 'new_blog_post'.
     68     *
     69     * @var string
     70     */
    1971    var $type;
     72
     73    /**
     74     * Description of the activity, eg 'Alex updated his profile.'
     75     *
     76     * @var string
     77     */
    2078    var $action;
     79
     80    /**
     81     * The content of the activity item.
     82     *
     83     * @var string
     84     */
    2185    var $content;
     86
     87    /**
     88     * The date the activity item was recorded, in 'Y-m-d h:i:s' format.
     89     *
     90     * @var string
     91     */
    2292    var $date_recorded;
     93
     94    /**
     95     * Whether the item should be hidden in sitewide streams.
     96     *
     97     * @var int
     98     */
    2399    var $hide_sitewide = false;
     100
     101    /**
     102     * Node boundary start for activity or activity comment.
     103     *
     104     * @var int
     105     */
    24106    var $mptt_left;
     107
     108    /**
     109     * Node boundary end for activity or activity comment.
     110     *
     111     * @var int
     112     */
    25113    var $mptt_right;
     114
     115    /**
     116     * Whether this item is marked as spam.
     117     *
     118     * @var int
     119     */
    26120    var $is_spam;
    27121
     122    /**
     123     * Constructor method.
     124     *
     125     * @param int $id Optional. The ID of a specific activity item.
     126     */
    28127    public function __construct( $id = false ) {
    29128        if ( !empty( $id ) ) {
    … …  
    33132    }
    34133
     134    /**
     135     * Populate the object with data about the specific activity item.
     136     */
    35137    public function populate() {
    36138        global $wpdb, $bp;
    … …  
    56158    }
    57159
     160    /**
     161     * Save the activity item to the database.
     162     *
     163     * @return bool True on success.
     164     */
    58165    public function save() {
    59166        global $wpdb, $bp;
    … …  
    105212    }
    106213
    107     // Static Functions
     214    /** Static Methods ***************************************************/
    108215
    109216    /**
    110217     * Get activity items, as specified by parameters
    111218     *
    112      * @param array $args See $defaults for explanation of arguments
     219     * @param array $args {
     220     *     An array of arguments. Optional.
     221     *     @int $page The current page number. Default: 1.
     222     *     @int $per_page The number of items to display per page. Default: 25.
     223     *     @int $max Maximum number of items to show. Default: false.
     224     *     @string $sort ASC or DESC. Default: 'DESC'.
     225     *     @array $exclude Array of activity IDs to exclude. Default: false.
     226     *     @array $in Array of ids to limit query by (IN). Default: false.
     227     *     @array $meta_query
     228     *     @array $filter
     229     *     @string $search_terms Limit results by a search term. Default: false.
     230     *     @bool $display_comments Whether to include activity comments. Default: false.
     231     *     @bool $show_hidden Whether to show items marked hide_sitewide. Default: false.
     232     *     @string $spam Spam status. Default: 'ham_only'
     233     * }
    113234     * @return array
    114235     */
    … …  
    296417
    297418    /**
    298      * Get the SQL for the 'meta_query' param in BP_Activity_Activity::get()
     419     * Get the SQL for the 'meta_query' param in BP_Activity_Activity::get().
    299420     *
    300421     * We use WP_Meta_Query to do the heavy lifting of parsing the
    … …  
    308429     * @param array $meta_query An array of meta_query filters. See the
    309430     *   documentation for WP_Meta_Query for details.
    310      * @return array $sql_array 'join' and 'where' clauses
     431     * @return array $sql_array 'join' and 'where' clauses.
    311432     */
    312433    public static function get_meta_query_sql( $meta_query = array() ) {
    … …  
    337458    /**
    338459     * In BuddyPress 1.2.x, this was used to retrieve specific activity stream items (for example, on an activity's permalink page).
     460     *
    339461     * As of 1.5.x, use BP_Activity_Activity::get() with an 'in' parameter instead.
     462     *
     463     * @since BuddyPress (1.2)
    340464     *
    341465     * @deprecated 1.5
    342466     * @deprecated Use BP_Activity_Activity::get() with an 'in' parameter instead.
     467     *
    343468     * @param mixed $activity_ids Array or comma-separated string of activity IDs to retrieve
    344469     * @param int $max Maximum number of results to return. (Optional; default is no maximum)
    … …  
    348473     * @param bool $display_comments Retrieve an activity item's associated comments or not. (Optional; default is false)
    349474     * @return array
    350      * @since BuddyPress (1.2)
    351475     */
    352476    public static function get_specific( $activity_ids, $max = false, $page = 1, $per_page = 25, $sort = 'DESC', $display_comments = false ) {
    … …  
    355479    }
    356480
     481    /**
     482     * Get the first activity ID that matches a set of criteria.
     483     *
     484     * @param int $user_id The user ID to filter by.
     485     * @param string $component The component to filter by.
     486     * @param string $type The activity type to filter by.
     487     * @param int $item_id The associated item to filter by.
     488     * @param int $secondary_item_id The secondary associated item to filter by.
     489     * @param string $action The action to filter by.
     490     * @param string $content The content to filter by.
     491     * @param string $date_recorded The date to filter by.
     492     * @return int|bool Activity ID on success, false if none is found.
     493     */
    357494    public static function get_id( $user_id, $component, $type, $item_id, $secondary_item_id, $action, $content, $date_recorded ) {
    358495        global $bp, $wpdb;
    … …  
    392529    }
    393530
     531    /**
     532     * Delete activity items from the database.
     533     *
     534     * To delete a specific activity item, pass an 'id' parameter.
     535     * Otherwise use the filters.
     536     *
     537     * @param array $args {
     538     *     @int $id Optional. The ID of a specific item to delete.
     539     *     @string $action Optional. The action to filter by.
     540     *     @string $content Optional. The content to filter by.
     541     *     @string $component Optional. The component name to filter by.
     542     *     @string $type Optional. The activity type to filter by.
     543     *     @string $primary_link Optional. The primary URL to filter by.
     544     *     @int $user_id Optional. The user ID to filter by.
     545     *     @int $item_id Optional. The associated item ID to filter by.
     546     *     @int $secondary_item_id Optional. The secondary associated item ID to filter by.
     547     *     @string $date_recorded Optional. The date to filter by.
     548     *     @int $hide_sitewide Optional. Default: false.
     549     * }
     550     * @return array|bool An array of deleted activity IDs on success, false on failure.
     551     */
    394552    public static function delete( $args = array() ) {
    395553        global $wpdb, $bp;
    … …  
    467625    }
    468626
     627    /**
     628     * Delete the comments associated with a set of activity items.
     629     *
     630     * @param array $activity_ids Activity IDs whose comments should be deleted.
     631     * @return bool True on success.
     632     */
    469633    public static function delete_activity_item_comments( $activity_ids = array() ) {
    470634        global $bp, $wpdb;
    … …  
    475639    }
    476640
     641    /**
     642     * Delete the meta entries associated with a set of activity items.
     643     *
     644     * @param array $activity_ids Activity IDs whose meta should be deleted.
     645     * @return bool True on success.
     646     */
    477647    public static function delete_activity_meta_entries( $activity_ids = array() ) {
    478648        global $bp, $wpdb;
    … …  
    488658
    489659    /**
    490      * Append activity comments to their associated activity items
     660     * Append activity comments to their associated activity items.
     661     *
     662     * @since BuddyPress (1.2)
    491663     *
    492664     * @global wpdb $wpdb WordPress database object
    493      * @param array $activities
    494      * @param bool $spam Optional; 'ham_only' (default), 'spam_only' or 'all'.
    495      * @return array The updated activities with nested comments
    496      * @since BuddyPress (1.2)
     665     *
     666     * @param array $activities Activities to fetch comments for.
     667     * @param bool $spam Optional. 'ham_only' (default), 'spam_only' or 'all'.
     668     * @return array The updated activities with nested comments.
    497669     */
    498670    public static function append_comments( $activities, $spam = 'ham_only' ) {
    … …  
    514686
    515687    /**
    516      * Get activity comments that are associated with a specific activity ID
    517      *
    518      * @global BuddyPress $bp The one true BuddyPress instance
    519      * @global wpdb $wpdb WordPress database object
    520      * @param int $activity_id Activity ID to fetch comments for
    521      * @param int $left Left-most node boundary
    522      * @param into $right Right-most node boundary
    523      * @param bool $spam Optional; 'ham_only' (default), 'spam_only' or 'all'.
    524      * @param int $top_level_parent_id The id of the root-level parent activity item
    525      * @return array The updated activities with nested comments
     688     * Get activity comments that are associated with a specific activity ID.
     689     *
    526690     * @since BuddyPress (1.2)
     691     *
     692     * @global BuddyPress $bp The one true BuddyPress instance.
     693     * @global wpdb $wpdb WordPress database object.
     694     *
     695     * @param int $activity_id Activity ID to fetch comments for.
     696     * @param int $left Left-most node boundary.
     697     * @param into $right Right-most node boundary.
     698     * @param bool $spam Optional. 'ham_only' (default), 'spam_only' or 'all'.
     699     * @param int $top_level_parent_id Optional. The id of the root-level parent activity item.
     700     * @return array The updated activities with nested comments.
    527701     */
    528702    public static function get_activity_comments( $activity_id, $left, $right, $spam = 'ham_only', $top_level_parent_id = 0 ) {
    … …  
    583757    }
    584758
     759    /**
     760     * Rebuild nested comment tree under an activity or activity comment.
     761     *
     762     * @since BuddyPress (1.2)
     763     *
     764     * @global BuddyPress $bp The one true BuddyPress instance.
     765     * @global wpdb $wpdb WordPress database object.
     766     *
     767     * @param int $parent_id ID of an activty or activity comment.
     768     * @param int $left Node boundary start for activity or activity comment.
     769     * @return int Right node boundary of activity or activity comment.
     770     */
    585771    public static function rebuild_activity_comment_tree( $parent_id, $left = 1 ) {
    586772        global $wpdb, $bp;
    … …  
    607793    }
    608794
     795    /**
     796     * Get child comments of an activity or activity comment.
     797     *
     798     * @since BuddyPress (1.2)
     799     *
     800     * @global BuddyPress $bp The one true BuddyPress instance.
     801     * @global wpdb $wpdb WordPress database object.
     802     *
     803     * @param int $parent_id ID of an activty or activity comment.
     804     * @return object Numerically indexed array of child comments.
     805     */
    609806    public static function get_child_comments( $parent_id ) {
    610807        global $bp, $wpdb;
    … …  
    614811
    615812    /**
    616      * Fetch a list of all components that have activity items recorded
    617      *
    618      * @return array
     813     * Get a list of components that have recorded activity associated with them
     814     *
     815     * @return array List of component names.
    619816     */
    620817    public static function get_recorded_components() {
    … …  
    623820    }
    624821
     822    /**
     823     * Get sitewide activity items for use in an RSS feed.
     824     *
     825     * @param int $limit Optional. Number of items to fetch. Default: 35.
     826     * @return array $activity_feed List of activity items, with RSS data added.
     827     */
    625828    public static function get_sitewide_items_for_feed( $limit = 35 ) {
    626829        $activities    = bp_activity_get_sitewide( array( 'max' => $limit ) );
    … …  
    628831
    629832        for ( $i = 0, $count = count( $activities ); $i < $count; ++$i ) {
    630                 $title                            = explode( '<span', $activities[$i]['content'] );
    631                 $activity_feed[$i]['title']       = trim( strip_tags( $title[0] ) );
    632                 $activity_feed[$i]['link']        = $activities[$i]['primary_link'];
    633                 $activity_feed[$i]['description'] = @sprintf( $activities[$i]['content'], '' );
    634                 $activity_feed[$i]['pubdate']     = $activities[$i]['date_recorded'];
     833            $title                            = explode( '<span', $activities[$i]['content'] );
     834            $activity_feed[$i]['title']       = trim( strip_tags( $title[0] ) );
     835            $activity_feed[$i]['link']        = $activities[$i]['primary_link'];
     836            $activity_feed[$i]['description'] = @sprintf( $activities[$i]['content'], '' );
     837            $activity_feed[$i]['pubdate']     = $activities[$i]['date_recorded'];
    635838        }
    636839
    … …  
    638841    }
    639842
     843    /**
     844     * Create SQL IN clause for filter queries.
     845     *
     846     * @since BuddyPress (1.3)
     847     *
     848     * @see BP_Activity_Activity::get_filter_sql()
     849     *
     850     * @param string $field The database field.
     851     * @param array|bool $items The values for the IN clause, or false when none are found.
     852     */
    640853    public static function get_in_operator_sql( $field, $items ) {
    641854        global $wpdb;
    … …  
    662875    }
    663876
     877    /**
     878     * Create filter SQL clauses.
     879     *
     880     * @since BuddyPress (1.3)
     881     *
     882     * @param array $filter_array Multidimensional array of fields to filter and values.
     883     * @return string The filter clause, for use in a SQL query.
     884     */
    664885    public static function get_filter_sql( $filter_array ) {
    665886
    … …  
    702923    }
    703924
     925    /**
     926     * Get the date/time of last recorded activity.
     927     *
     928     * @since BuddyPress (1.2)
     929     *
     930     * @return string ISO timestamp.
     931     */
    704932    public static function get_last_updated() {
    705933        global $bp, $wpdb;
    … …  
    708936    }
    709937
     938    /**
     939     * Get favorite count for a given user.
     940     *
     941     * @since BuddyPress (1.2)
     942     *
     943     * @param int The ID of the user whose favorites you're counting.
     944     * @return int A count of the user's favorites.
     945     */
    710946    public static function total_favorite_count( $user_id ) {
    711947        if ( !$favorite_activity_entries = bp_get_user_meta( $user_id, 'bp_favorite_activities', true ) )
    … …  
    715951    }
    716952
     953    /**
     954     * Check whether an activity item exists with a given string content.
     955     *
     956     * @param string $content The content to filter by.
     957     * @return int|bool The ID of the first matching item if found, otherwise false.
     958     */
    717959    public static function check_exists_by_content( $content ) {
    718960        global $wpdb, $bp;
    … …  
    721963    }
    722964
     965    /**
     966     * Hide all activity for a given user.
     967     *
     968     * @param int $user_id The ID of the user whose activity you want to mark hidden.
     969     * @param int
     970     */
    723971    public static function hide_all_for_user( $user_id ) {
    724972        global $wpdb, $bp;
    … …  
    8591107    /**
    8601108     * Setup and validate the class properties.
     1109     *
     1110     * @access protected
    8611111     */
    8621112    protected function setup_properties() {
    … …  
    8811131     * Currently, these hooks are used to maintain backwards compatibility with
    8821132     * the RSS feeds previous to BP 1.8.
     1133     *
     1134     * @access protected
    8831135     */
    8841136    protected function setup_hooks() {
    … …  
    8901142    /** BACKPAT HOOKS ********************************************************/
    8911143
     1144    /**
     1145     * Fire a hook to ensure backward compatibility for RSS attributes.
     1146     */
    8921147    public function backpat_rss_attributes() {
    8931148        do_action( 'bp_activity_' . $this->id . '_feed' );
    8941149    }
    8951150
     1151    /**
     1152     * Fire a hook to ensure backward compatibility for channel elements.
     1153     */
    8961154    public function backpat_channel_elements() {
    8971155        do_action( 'bp_activity_' . $this->id . '_feed_head' );
    8981156    }
    8991157
     1158    /**
     1159     * Fire a hook to ensure backward compatibility for item elements.
     1160     */
    9001161    public function backpat_item_elements() {
    9011162        switch ( $this->id ) {
    … …  
    9211182    /**
    9221183     * Output the feed's item content.
     1184     *
     1185     * @access protected
    9231186     */
    9241187    protected function feed_content() {
    … …  
    9481211    /**
    9491212     * Output the RSS feed.
     1213     *
     1214     * @access protected
    9501215     */
    9511216    protected function output() {
Note: See TracChangeset for help on using the changeset viewer.