myCRED_Badge

Description

This object holds all relevant information about a specific myCRED badge, along with a set of methods to manipulate the badge along with assigning it to users.

Available since version 1.7

Interacting with Object

The badge object can be accessed via the mycred_get_badge function.

Object properties

Property Type Description
myCRED_Badge Object (
public $post_id int The badge post object ID.
public $title string The badge title.
public $earnedby int The number of users that has earned this badge.
public $manual bool Indicates if the badge has been set to be manually awarded.
public $levels array Array of all the levels setup for this badge.
public $main_image string The main badge image (if set).
public $level array If a particular level is requested when the object is constructed, that selected levels settings are populated here.
public $level_id int If a particular level is requested when the object is constructed, that selected levels title is populated here.
public $level_label string If a particular level is requested when the object is constructed, that selected levels label is populated here.
public $level_image string If a particular level is requested when the object is constructed, that selected levels image is populated here (if the level has one).
public $image_width int The set value for the MYCRED_BADGE_WIDTH constant.
public $image_height int The set value for the MYCRED_BADGE_HEIGHT constant.
public $references array An array of reference keys that are used as a requirement for this badge.
public $references array An array of point type keys that are used as a requirement for this badge.
protected $user_meta_key string The user meta key that is used to connect this badge with a particular user. This meta key differs if you use Multisites from regular WordPress installs.
public $current_level int If a user is associated with this badge, this will indicate the level a user has reached. Remember that level IDs begin with zero for the first level.
)

Object Methods

public function __construct( $object = NULL, $level = NULL ) {
Description: Constructs and populates the badge object.
Variable Type Required Description
$object int or obj Yes Either the badges post object or the post object ID.
$level int No Option to populate a specific level of the badge.
}
public function get_user_count( $level_id = NULL ) {
Description: Returns the total number of users that has earned this badge. A level ID can be provided to return a count for a specific badge level.
Variable Type Required Description
$level_id int No Option to return the count for a specific badge level.
}
public function get_level( $level_id = false ) {
Description: Returns a specific level of this badge. Note that in it's current form, this is an associative array of data. As of version 1.9, this will be replaced with a new myCRED_Badge_Level object. Returns FALSE if the badge level does not exists or an invalid level ID is provided.
Variable Type Required Description
$level_id int Yes The badge level ID.
}
public function get_level_requirements( $level_id = false ) {
Description: Returns a specific levels requirements as an associative array. Returns FALSE if the badge level does not exists or an invalid level ID is provided.
Variable Type Required Description
$level_id int Yes The badge level ID.
}
public function get_level_reward( $level_id = false ) {
Description: Returns a specific levels reward setup as an associative array. Returns FALSE if the badge level does not exists or an invalid level ID is provided.
Variable Type Required Description
$level_id int Yes The badge level ID.
}
public function user_has_badge( $user_id = false, $level_id = 0 ) {
Description: Checks to see if a specific user has earned this badge with the option to check if the user also has reached a certain level. Returns TRUE or FALSE. Note that if no $user_id is provided, this method will return FALSE.
Variable Type Required Description
$user_id int Yes The users numeric ID.
$level_id int No Option to check if a user has reached a certain level.
}
public function get_users_current_level( $user_id = false ) {
Description: Returns the level ID that a given user has reached with this badge. Will return FALSE if the user has not yet earned this badge.
Variable Type Required Description
$user_id int Yes The users numeric ID.
}
public function query_users_level( $user_id = false ) {
Description: This method will run the badge requirements and query the database for which level a user has reached. Will return FALSE if no level was reached (not yet earned the badge). This should only be used when new log entries have been added to the database and we need to run a new query. If you just need to get the users current level, use the get_users_current_level() method instead.
Variable Type Required Description
$user_id int Yes The users numeric ID.
}
public function get_users_next_level( $user_id = false ) {
Description: Returns the next level user can reach based on their current position. If the user has reached the highest level, that levels is returned.
Variable Type Required Description
$user_id int Yes The users numeric ID.
}
public function assign( $user_id = false, $level_id = 0 ) {
Description: Assigns a specific user to this badge with the option to also set a particular level that the user has reached.
Variable Type Required Description
$user_id int Yes The users numeric ID.
$level_id int Yes The badge level ID the user has reached. For the first level or if no levels are used, use zero.
}
public function payout_reward( $previous_level = -1, $new_level = 0 ) {
Description: This method will payout the reward (if set) set for the levels a user reaches. If the user jumps multiple levels in one event, this method will payout the reward for every level the user jumped over.
Variable Type Required Description
$previous_level int Yes The previous level a user reached with this badge. If the user just now earned the badge, this variable should be -1 since level IDs start from zero.
$new_level int Yes The ID of the new level the user reached.
}
public function assign_all() {
Description: This method will try to assign those users that have earned this badge. This is used when a badge is published for the first time or when the "Assign" button is used when editing a badge. Depending on your log size and user count, this method can require a lot of server resources to run. Please make sure you only run this when necessary!
}
public function divest( $user_id = false ) {
Description: Removes this badge from a given user.
Variable Type Required Description
$user_id int Yes The users numeric ID.
}
public function divest_all() {
Description: Removes this badge from all users.
}
public function delete( $delete_post = false ) {
Description: This method will delete this badge. Note that this method uses divest_all() to delete the badge form your users before deleting the badge's setup.
Variable Type Required Description
$delete_post bool No Option to also delete the WordPress post object. Warning! This will delete the object not trash it!
}
public function get_image( $image = NULL ) {
Description: This method will return either the main badge image (used for when a badge has not yet been earned) or a specific levels image.
Variable Type Required Description
$image int or string Yes Either the keyword main to show the main image or the level ID for the image of a particular level.
}

Object Example

myCRED_Badge Object
    (
        [post_id] => 29
        [title] => Best User
        [earnedby] => 1
        [manual] => 
        [levels] => Array
            (
                [0] => Array
                    (
                        [attachment_id] => 165
                        [image_url] => 
                        [label] => Commended
                        [compare] => AND
                        [requires] => Array
                            (
                                [0] => Array
                                    (
                                        [type] => mycred_default
                                        
    
        
            [1]
        
          
    

	 => manual
                                        [amount] => 1000
                                        [by] => sum
                                    )
                            )
                        [reward] => Array
                            (
                                [type] => mycred_default
                                [log] => 
                                [amount] => 0
                            )
                    )
                [1] => Array
                    (
                        [attachment_id] => 166
                        [image_url] => 
                        [label] => Hero
                        [compare] => AND
                        [requires] => Array
                            (
                                [0] => Array
                                    (
                                        [type] => mycred_default
                                        
    
        
            [1]
        
          
    

	 => manual
                                        [amount] => 5000
                                        [by] => sum
                                    )
                            )
                        [reward] => Array
                            (
                                [type] => mycred_default
                                [log] => 
                                [amount] => 0
                            )
                    )
            )
        [main_image] => ''
        [level] => Array
            (
            )

        [level_id] => 0
        [level_label] => ''
        [level_image] => Best User
        [image_width] => 100
        [image_height] => 100
        [references] => Array
            (
                [0] => manual
            )
        [point_types] => Array
            (
                [0] => mycred_default
            )
        [user_meta_key:protected] => mycred_badge29
        [user_id] => 125
        [current_level] => 0
        [compare] => AND
    )