Functions

Estimated reading: 57 minutes 1447 views

buycred_complete_pending_payment

Package: mycred/purchase Category: Functions
 

Description

This function will process a pending point purchase and “complete” it by paying the buyer the point they purchased. This processing is done using the payment gateway set in the pending payment object, by using the gateways complete_payment() method.

Returns

(bool) Returns TRUE if the transaction was completed successfully else FALSE.

Parameters

ParamTypeRequiredDescription
function buycred_complete_pending_payment(
$payment_idINT or STRINGYes

The pending payment public ID in string format or the WordPress post object ID.

) { ... }

buycred_gateway

Package: mycred/purchase Category: Functions
 

Description

This function will construct a given buyCRED Payment Gateway.

 

Returns

(bool | class) Returns either false or the given payment gateway class.

Parameters

ParamTypeRequiredDescription
function buycred_gateway(
$gateway_idSTRINGYes

The buyCRED Payment Gateway ID.

) { ... }

buycred_get_pending_payment

Package: mycred/purchase Category: Functions
 

Description

This function retrieves the buyCRED pending payment object based on a given pending payment ID.

 

Returns

(bool | object) Returns either the payment object or FALSE if the payment is not found.

Parameters

ParamTypeRequiredDescription
function buycred_get_pending_payment(
$payment_idSTRINGYes

The buyCRED pending payment ID.

) { ... }

Pending Payment Object Example

				
					Std Object
(
    [payment_id] => 1
    [public_id] => 'ABC123'
    [point_type] => 'mycred_default'
    [amount] => 250
    [cost] => 100
    [currency] => 'USD'
    [buyer_id] => 2
    [recipient_id] => 2
    [gateway_id] => 'paypal-standard'
    [transaction_id] => ''
    [cancel_url] => 'https://www.yourwebsite.com/cancelled/'
    [pay_now_url] => 'https://www.yourwebsite.com/buy/?mycred_buy=paypal-standard&revisit=ABC123'
)
				
			

Example

Example 1: Basic usage example

				
					$payment_id      = sanitize_text_field( $_GET['id'] );
$pending_payment = buycred_get_pending_payment( $payment_id );

if ( $pending_payment !== false ) {
	// Payment was found.
}
				
			

 

buycred_get_pending_payment_id

Package: mycred/purchase Category: Functions
 

Description

This function attempts to get the WordPress post object ID for a given buyCRED pending payment ID.

Returns

(bool | int) Returns either the WordPress post object ID or FALSE on failure.

Parameters

ParamTypeRequiredDescription
function buycred_get_pending_payment_id(
$payment_idSTRINGYes

The buyCRED pending payment ID.

) { ... }

Example

Example 1: Check if a given ID is a pending payment or not.

				
					$payment_id = sanitize_text_field( $_GET['id'] );
$payment_id = buycred_get_pending_payment_id( $payment_id );

if ( $payment_id !== false ) {
	// This is a pending payment
}
				
			

 

buycred_get_users_pending_payments

Package: mycred/purchase Category: Functions
 

Description

This function will return all a given users currently pending buyCRED point purchases. The function will return an associative array sorted based on the point types you have enabled to sell.

 

Returns

(array) Returns an associative array of pending payment objects sorted by point type. Returns FALSE if no pending payment exists.

Parameters

ParamTypeRequiredDescription
function buycred_get_users_pending_payments(
$user_idINTYes

The users numeric WordPress ID.

$point_typeSTRINGNo

Option to only return pending payments for a given point type.

) { ... }

buycred_trash_pending_payment

Package: mycred/purchase Category: Functions
 

Description

This function will trash a pending buyCRED point purchase payment. This means the buycred_payment post type object will get trashed.

 

Returns

(bool) TRUE if the post was trashed else FALSE.

Parameters

ParamTypeRequiredDescription
function buycred_trash_pending_payment(
$payment_idINT or STRINGYes

The pending payment public ID in string format or the WordPress post object ID.

) { ... }

mycred

Package: mycred/core Category: Functions
 

Description

This function constructs and returns the myCRED_Settings object that you can use to access a large variety of methods for processing points or displaying points. Using this function ensures that the class methods are all set to use the same point type and to honour that selected point type’s format and styling setup.

 

Returns

(object) Returns the myCRED_Settings object.

Parameters

ParamTypeRequiredDescription
function mycred(
$point_type_keySTRINGNo

Used be used when you need to load a custom point type setup instead of the default one.

) { ... }
Examples

Example 1: Default usage, accessing the default point type.

				
					$mycred = mycred();

				
			

Example 2: Load a custom point type.

				
					$mycred = mycred( 'customtypekey' );

				
			

Example 3: Adjust a users balance by removing 10 points from it without a log entry.

				
					$user_id = get_current_user_id();
$mycred  = mycred();

if ( ! $mycred->exclude_user( $user_id ) )
	$mycred->update_users_balance( $user_id, 10 );
				
			

 

mycred_add

Package: mycred/balance Category: Functions
 

Description

This function allows you to increment a users balance by adding a specific amount to it. Furthermore this function will save a log entry of this adjustment and requires that you provide a reference and a log entry at a bare minimum.

 

Returns

(bool) true on success or false on declined transaction.

Parameters

ParamTypeRequiredDescription
function mycred_add(
$referenceSTRINGYes

The reference to log this entry under. You can use your own custom reference or one of the built-in ones.

$user_idINTYes

The ID of the user getting the points.

$amountINT or FLOATYes

The point amount to give to the user. This can be a positive or negative value.

$entrySTRINGYes

The entry to save in the log for this adjustment.

$ref_idINTNo

Optional reference ID to save with the log entry.

$dataSTRINGNo

Optional data to save with the log entry. Note that if you are supply an array, this will be serialized.

$typeSTRINGNo

The point type key. Should only be used if you are adjusting a custom point type and not the default one.

) { ... }

Examples

Example 1: Add a user 10 points, logged as if it was for an approved comment.

				
					mycred_add( 'approved_comment', $user_id, 10, 'Points for approved comment' );

				
			

Example 2: Deduct 5 points of a custom point type from the users account.

				
					mycred_add( 'payment', $user_id, -5, 'Some custom event' );

				
			

 

mycred_add_new_notice

Package: mycred/notice Category: Functions
 

Description

This function allows you to add a new notification for a specific user. Notifications are shown when the user logs in (if the notice is generated when they are not online) or on the next page reload (if they are logged in).


Returns

void

Parameters
Param Type Required Description
function mycred_add_new_notice(
$notice ARRAY Yes

An associative array containing the message and the ID of the user that it is intended for.

$lifespan INT No

The lifespan of the message. The value is multiplied with the number of seconds there is in a day.

) { ... }

mycred_add_user_meta

Package: mycred/core Category: Functions
 

Description

A wrapper function for add_user_meta, it assures that point related data is saved under the correct meta key structure

Returns

(int | bool) Primary key id for success. FALSE for failure.

Parameters

ParamTypeRequiredDescription
function mycred_add_user_meta(
$user_idINTYes

The users numeric ID.

$meta_keySTRINGYes

The meta key id.

$endSTRINGNo

Optional ending to append to the meta key id. In certain situation on Multisites, the meta key gets the blogs ID appended. The value of $end is then appended after the blog ID, whilst the value of $meta_key is before the blog id. On regular WordPress installations $end is appended onto $meta_key.

$valueSTRINGYes

The meta value.

$uniqueBOOLNo

TRUE if the meta data is unique or FALSE if not. Defaults to TRUE.

) { ... }

Example

Example 1: Save the total number of times a user has gained points for approved comments.

				
					$user_id       = get_current_user_id();
$comment_count = mycred_count_ref_instances( 'approved_comment', $user_id );

mycred_add_user_meta( $user_id, 'comment_point_count', '', $comment_count );
				
			

 

mycred_assign_badge

Package: mycred/badge Category: Functions
 

Description

This function assigns a given badge to all users that meet the set requirements.

 

Returns

(array) Returns an array of User IDs and the level their reached for this badge.

Parameters

ParamTypeRequiredDescription
function mycred_assign_badge(
$badge_idINTYes

The badge post object ID.

) { ... }

Example

Example 1: Assign a badge and show the number of users that received it.

 
				
					$badge_id = 1;

$results  = mycred_assign_badge( $badge_id );
printf( '%d users earned this badge.', count( $results ) );
				
			

 

mycred_assign_badge_to_user

Package: mycred/badge Category: Functions
 

Description

This function assigns a given badge and badge level to a specific user. It is used by other badge assignment functions to connect a badge with a user.

 

Returns

void

Parameters

ParamTypeRequiredDescription
function mycred_assign_badge_to_user(
$user_idINTYes

The users numeric ID.

$badge_idINTYes

The badge post objects ID.

$levelINTYes

The badge level to assign.

) { ... }

Example

Example 1: Assign a badge with the id of 1 to the current user.

				
					$user_id  = get_current_user_id();
$badge_id = 1;

mycred_assign_badge_to_user( $user_id, $badge_id, 1 );
				
			

 

mycred_assign_ranks

Package: mycred/rank Category: Functions
 

Description

This function assigns ranks for a given point type. The function will assign ranks starting with the rank that has the lowest point requirement. Used when clicking on the “Assign users to Ranks” button in the admin area.

 

Returns

(int) Returns the total number of users that successfully received a rank.

Parameters

ParamTypeRequiredDescription
function mycred_assign_ranks(
$point_typeSTRINGNo

The point type key. Should only be used if assigning ranks of a custom point type.

) { ... }

Example

Example 1: Default usage

				
					$count = mycred_assign_ranks();
printf( '%d ranks were assigned.', $count );
				
			

 

mycred_badge_level_reached

Package: mycred/badge Category: Functions
 

Description

This function checks if a user has reached the badge requirements set for a given badge. If the requirements have been met, the function will return the level they should have. This function does not assign the badge to the user, it only checks if there should be one.

 

Returns

(bool | int) FALSE if the user has not earned the badge yet or if incorrect parameters are provided. If the badge is earned, the badges level is returned instead.

Parameters

ParamTypeRequiredDescription
function mycred_badge_level_reached(
$user_idINTYes

The users numeric ID.

$badge_idINTYes

The badge post object ID.

) { ... }

Example

Example 1: Check if the current user has reached level 4 of a badge.

				
					$badge_id          = 1;
$user_id           = get_current_user_id();
$level_requirement = 4;

$level_reached     = mycred_badge_level_reached( $user_id, $badge_id );

if ( $level_reached !== false && $level_reached >= $level_requirement ) {

	// User has earned the badge and is on level 4 or higher

}
				
			

 

mycred_centralize_log

Package: mycred/core Category: Functions
 

Description

This function checks if the central log feature is enabled on a Multisite installation. Will return FALSE if Multisite are not being used.

 

Returns

(bool) TRUE if the central log feature is enabled else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_centralize_log(
No params
) { ... }

Example

Example 1: Default usage

				
					if ( mycred_centralize_log() ) {

	// Central logging is enabled

}
				
			

 

mycred_content_purchase_has_expired

Package: mycred/content Category: Functions
 

Description

This function will check if a content payment has expired or not.

Returns

(bool) TRUE if the purchase as expired else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_content_purchase_has_expired(
$paymentOBJYes

The payment log entry object.

) { ... }

mycred_count_all_ref_instances

Package: mycred/log Category: Functions
 

Description

This function returns an associative array of references and their individual counts from the log.

Returns

(array) Associative array of references and counts.

Parameters

ParamTypeRequiredDescription
function mycred_count_all_ref_instances(
$numberINTYes

The number of references to return a count for. Use -1 to return all. Defaults to 5.

$orderSTRINGNo

Sorting order. Either Ascending (ASC) or Descending (DESC). Defaults to DESC.

$typeSTRINGNo

Option to filter the count based on a point type. Must be either a point type key or the string all.

) { ... }

Examples

Example 1: Get all references with their count no matter which point type they belong to.

				
					$references = mycred_count_all_ref_instances( -1, 'DESC', 'all' );

if ( ! empty( $references ) ) {
	foreach ( $references as $reference => $count ) {

		echo $reference . ' ' . $count;

	}
}
				
			

Example 2: Get the top 10 references for the default point type.

				
					$count = mycred_count_all_ref_instances( 10 );

if ( ! empty( $references ) ) {
	foreach ( $references as $reference => $count ) {

		echo $reference . ' ' . $count;

	}
}

				
			

 

mycred_count_ref_id_instances

Package: mycred/log Category: Functions
 

Description

Returns the number of times a specific reference, in combination with a reference ID occurs in the log, with the option to filter by user ID or by point type.

 

Returns

(int) Returns the number of found records.

Parameters

ParamTypeRequiredDescription
function mycred_count_ref_id_instances(
$referenceSTRINGYes

The reference to count.

$ref_idINTYes

The reference ID.

$user_idINTNo

Option to filter the count by a user ID.

$typeSTRINGNo

Option to filter results by a particular point type.

) { ... }

Example

Example 1: Check if a user has a log entry for receiving points for a particular comment.

				
					$user_id    = 1;
$comment_id = 10;

if ( mycred_count_ref_id_instances( 'approved_comment', $comment_id, $user_id ) > 0 ) {

	// User has received points for this comment

}
				
			

 

mycred_count_ref_instances

Package: mycred/log Category: Functions
 

Description

Returns the number of times a specific reference occurs in the log, with the option to filter by user ID or by point type.

 

Returns

(int) Returns the number of found records.

Parameters

ParamTypeRequiredDescription
function mycred_count_ref_instances(
$referenceSTRINGYes

The reference to count.

$user_idINTNo

Option to filter the count by a user ID.

$typeSTRINGNo

Option to filter results by a particular point type.

) { ... }

Examples

Example 1: Count the number of times a user has received points for approved comments

				
					$user_id = 1;
$count   = mycred_count_ref_instances( 'approved_comment', $user_id );
				
			

Example 2: Count the number of times points have been spent on paying for a WooCommerce order.

				
					$payments = mycred_count_ref_instances( 'woocommerce_payment' );

				
			

 

mycred_count_users_with_badge

Package: mycred/badge Category: Functions
 

Description

This function counts the number of users that has a given badge with the option to count badge level.

 

Returns

(int) The number of users that has a badge or badge level.

Parameters

ParamTypeRequiredDescription
function mycred_count_users_with_badge(
$badge_idINTYes

The badge post object ID.

$levelINTNo

Option to count a specific level for the given badge.

) { ... }

Example

Example 1: Count the number of users that have a badge with the id 1.

				
					$badge_id = 1;
$count    = mycred_count_users_with_badge( $badge_id );

printf( '%d users have earned this badge', $count );
				
			

 

mycred_count_users_without_badge

Package: mycred/badge Category: Functions
 

Description

This function counts the number of users that has not earned a given badge.

 

Returns

(int) The number of users that has not earned the badge.

Parameters

ParamTypeRequiredDescription
function mycred_count_users_without_badge(
$badge_idINTYes

The badge post object ID.

) { ... }

Example

Example 1: Count the number of users that have not earned the badge 2 yet.

				
					$badge_id = 2;
$count    = mycred_count_users_without_badge( $badge_id );

printf( '%d users has not yet earned this badge', $count );
				
			

 

mycred_coupon_was_successfully_used

Package: mycred/coupon Category: Functions
 

Description

This function checks if a coupon was successfully applied or not. Should be used in combination with the mycred_use_coupon function.

Returns

(bool) TRUE if the coupon was successfully applied else FALSE.

Parameters

Param Type Required Description
function mycred_coupon_was_successfully_used(
$code Yes

The results of the mycred_use_coupon function.

) { ... }

Example

Example 1: Apply a posted coupon code to the current user.

				
					$user_id = get_current_user_id();
$code    = $_POST['coupon'];

$results = mycred_use_coupon( $code, $user_id );

if ( mycred_coupon_was_successfully_used( $results ) ) {

	// Coupon was successfully used

}
else {

	// Something went wrong

}
				
			

 

mycred_create_chart

Package: mycred/stats Category: Functions
 

Description

Returns an instance of the myCRED_Chart object for building charts using the Statistics add-on.

 

Returns

(obj) Returns the myCRED_Chart object.

Parameters

ParamTypeRequiredDescription
function mycred_create_chart(
$argsARRAYNo

An array of global arguments for charts.

) { ... }

Example

Example 1: Generate a pie chart based on the points in circulation on our website.

				
					$global_args = array(
	'title' => 'Points in Circulation'
);

$chart       = mycred_create_chart( $global_args );

// The data to show in the chart.
$data        = mycred_get_circulation_data();

if ( ! empty( $data ) ) {

	echo $chart->pie_chart( $data );

}
				
			

 

mycred_create_new_coupon

Package: mycred/coupon Category: Functions
 

Description

This function creates a new myCRED Coupon post object. Uses wp_insert_post.

 

Returns

(int | WP_Error) Returns either the coupon post object ID or a WP_Error object.

Parameters

ParamTypeRequiredDescription
function mycred_create_new_coupon(
$argsARRAYYes

Associative array of coupon arguments.

) { ... }

New Coupon Arguments

ArgumentTypeRequiredDescription
codestringNoThe coupon code. If not set, the function will generate a random code.
valueINT or FLOATYesThe amount of points this coupon generates when redeemed.
typestringNoThe point type that this coupon generates. Defaults to the default type key.
global_maxINTNoThe maximum number of times the coupon can be redeemed. Defaults to 1. Can not be zero!
user_maxINTNoThe maximum number of times the coupon can be redeemed by a single user. Defaults to 1.
min_balanceINT or FLOATNoOptional minimum balance requirement for redeeming this coupon. Users who have less points then this value will not be able to redeem this coupon.
min_balance_typestringNoOptional point type key for the minimum balance requirement.
max_balanceINT or FLOATNoOptional maximum balance requirement for redeeming this coupon. Users who have more points then this value will not be able to redeem this coupon.
max_balance_typestringNoOptional point type key for the maximum balance requirement.
expiresINTNoOptional expiration date for the coupon. Uses strtotime to convert the date into a UNIX timestamp. Do not use if the coupon never expires / expires when used up.

Examples

Example 1: Create a new coupon that can be used 10 times in total and gives 5 points when redeemed.

				
					$args = array(
	'value'      => 5,
	'global_max' => 10
);
$new_coupon = mycred_create_new_coupon( $args );

if ( $new_coupon !== false && ! is_wp_error( $new_coupon ) ) {

	// Coupon was successfully created

}
				
			

Example 2: Create a new coupon called “XMASOFFER“ that gives 100 points when redeemed. In order to use the coupon, the user must have less than 100 points. Make sure the coupon can not be used more than 500 times.

				
					$args = array(
	'code'        => 'XMASOFFER'
	'value'       => 100,
	'global_max'  => 500,
	'max_balance' => 100
);
$new_coupon = mycred_create_new_coupon( $args );

if ( $new_coupon !== false && ! is_wp_error( $new_coupon ) ) {

	// Coupon was successfully created

}
				
			

 

mycred_date_to_gmt_timestamp

Package: mycred/core Category: Functions
 

Description

This function will convert a well formatted date to a GMT unix timestamp. Uses strtotime.

 

Returns

(int | bool) Returns a UNIX timestamp or FALSE if the date provided if incorrectly formatted.

Parameters

ParamTypeRequiredDescription
function mycred_date_to_gmt_timestamp(
$dateSTRINGYes

A well formatted date that strtotime understands.

) { ... }

Example

Example 1: Convert a given date into a GMT unix timestamp

				
					$date = '2016-12-01';

$timestamp = mycred_date_to_gmt_timestamp( $date );
				
			

 

mycred_delete_recurring_payout

Package: mycred/banking Category: Functions
 

Description

Deletes a given recurring payout in the Banking add-on.

Returns

(bool) TRUE if the schedule was deleted else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_delete_recurring_payout(
$idSTRINGYes

The recurring payout ID.

$point_typeSTRINGNo

Optional point type key if we are not deleting a recurring payout for the default point type.

) { ... }

Example

Example 1: Delete the recurring payout with the ID 1.

				
					$payout = 1;

mycred_delete_recurring_payout( $payout );
				
			

 

mycred_delete_user_meta

Package: mycred/core Category: Functions
 

Description

A wrapper function for delete_user_meta, it assures that point related data is deleted under the correct meta key structure.

 

Returns

(bool) TRUE if user meta was deleted else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_delete_user_meta(
$user_idINTYes

The users numeric ID.

$meta_keySTRINGYes

The meta key id.

$endSTRINGNo

Optional ending to append to the meta key id. In certain situation on Multisites, the meta key gets the blogs ID appended. The value of $end is then appended after the blog ID, whilst the value of $meta_key is before the blog id. On regular WordPress installations $end is appended onto $meta_key.

$valueSTRINGNo

The meta value. Should be left empty unless the meta data being deleted is not unique.

) { ... }

mycred_display_badge_requirements

Package: mycred/badge Category: Functions
 

Description

This function will return the requirements you set for a particular badge in readable format.

 

Returns

(string) Returns an unorganized list.

Parameters

ParamTypeRequiredDescription
function mycred_display_badge_requirements(
$badge_idINTYes

The badge post object ID.

) { ... }

Example

Example 1: Display the requirements for a badge.

 
				
					$badge_id = 1;

echo mycred_display_badge_requirements( $badge_id );
				
			

 

mycred_display_users_badges

Package: mycred/badge Category: Functions
 

Description

This function renders a list of all the badges a give user has earned.

 

Returns

All badge images a user has earned.

Parameters

ParamTypeRequiredDescription
function mycred_display_users_badges(
$user_idINTYes

The users numeric ID.

) { ... }

Example

Example 1: Show the current users badges.

				
					$user_id = get_current_user_id();

echo '<h3>Your badges</h3>';
mycred_display_users_badges( $user_id );
				
			

 

mycred_display_users_balance

Package: mycred/balance Category: Functions
 

Description

Returns a given users current balance for a specific point type formatted. This means the balance will be applied the appropriate separator characters you have defined along with any prefix / suffix that might be set. If you are looking to display a user’s total balance, consider using the mycred_display_users_total_balance function instead.

 

Returns

(string | bool) The users current balance formatted with prefix / suffix (if used). If the user ID is invalid or the user is excluded, this function will return FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_display_users_balance(
$user_idINTYes

The users numeric ID.

$point_typeSTRINGNo

The point type key. Should only be used if you require the balance of a custom point type.

) { ... }

Example

Example 1: Show the current users balance.

				
					$user_id = get_current_user_id();
echo mycred_display_users_balance( $user_id );
				
			

Example 2: Get the BuddyPress profiles custom point type current balance.

 
				
					$profile_id = bp_displayed_user_id();
echo mycred_display_users_balance( $profile_id, 'customtypekey' );
				
			

 

mycred_display_users_total_balance

Package: mycred/balance Category: Functions
 

Description

Returns a given users total balance for a specific point type formatted. This means the balance will be applied the appropriate separator characters you have defined along with any prefix / suffix that might be set. If you are looking to display a user’s current balance, consider using the mycred_display_users_balance function instead.

 

Returns

(string | bool) The users total balance formatted with prefix / suffix (if used). If the user ID is invalid or the user is excluded, this function will return FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_display_users_total_balance(
$user_idINTYes

The users numeric ID.

$point_typeSTRINGNo

The point type key. Should only be used if you require the balance of a custom point type.

) { ... }

Examples

Example 1: Get the current users total balance.

 
				
					$user_id = get_current_user_id();
echo mycred_display_users_total_balance( $user_id );
				
			

Example 2: Get the BuddyPress profiles custom point type total balance.

 
				
					$profile_id = bp_displayed_user_id();
echo mycred_display_users_total_balance( $profile_id, 'customtypekey' );
				
			

 

mycred_exclude_user

Package: mycred/core Category: Functions
 

Description

Checks if a given user is excluded from using a particular point type.

 

Returns

(bool) TRUE if the user is excluded else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_exclude_user(
$user_idINTYes

The numeric ID of the user.

$point_typeSTRINGNo

The point type to check for.

) { ... }

Example

Example 1: Check if the current user is excluded from the default point type.

 
				
					$user_id = get_current_user_id();

if ( mycred_exclude_user( $user_id ) ) {

	// User is excluded

}
				
			

 

mycred_find_users_rank

Package: mycred/rank Category: Functions
 

Description

This function will attempt to find a given users rank of a specific point type. This function can be used to just query which rank a user should have or also save this rank.

 

Returns

(object | bool) Returns either FALSE if no rank was found or an object containing the users current rank, the rank they should have and the ranks requirements.

Object example:

				
					Std Object
(
    [rank_id] => 1	// The rank post object ID a user should have
    [minimum] => 0	// The ranks minimum point requirement
    [maximum] => 999	// The ranks maximum point requirement
    [current_id] => 1	// The rank post object ID the user currently has assigned
)
				
			
 

Parameters

ParamTypeRequiredDescription
function mycred_find_users_rank(
$user_idINTYes

The users numeric ID.

$point_typeSTRINGNo

The point type key.

$actBOOLNo

TRUE if the rank should be saved or FALSE if not. Defaults to TRUE.

) { ... }

Example

Example 1: Check what rank a user should have without saving the results.

 
				
					$user_id = get_current_user_id();
$rank    = mycred_find_users_rank( $user_id, 'mycred_default', false );

if ( $rank === false && $rank->rank_id !== $rank->current_id ) {

	// The user should have a new rank

}
				
			

 

mycred_flush_widget_cache

Package: mycred/core Category: Functions
 

Description

Wrapper function for wp_cache_delete for deleting widget caches. Used when myCRED widget settings are saved.

 

Returns

void

Parameters

Param Type Required Description
function mycred_flush_widget_cache(
$id STRING Yes

The widget ID to flush.

) { ... }

Example

Example 1: Flush the cache for a widget with the ID “mycred_widget“.

				
					mycred_flush_widget_cache( 'mycred_widget' );

				
			

 

mycred_force_singular_session

Package: mycred/core Category: Functions
 

Description

This function is used throughout myCRED to prevent users from attempting to submit AJAX forms multiple times. The minimum time that has to pass between AJAX calls is controlled by the MYCRED_MIN_TIME_LIMIT constant.


Returns

(bool) TRUE if an AJAX call was made within the timelimit else FALSE. A task should be terminated if this function returns TRUE.

Parameters

Param Type Required Description
function mycred_force_singular_session(
$user_id INT Yes

The users numeric ID.

$key STRING Yes

A unique meta key that identifies the current transaction.

$timelimit INT No

The number of seconds that has to pass between AJAX calls. Defaults to the value of the MYCRED_MIN_TIME_LIMIT constant.

) { ... }

mycred_get_account

Package: mycred/core Category: Functions
 

Description

Retrives the myCRED_Account object for a given user.

 

Returns

(bool | object) Returns either FALSE or the myCRED_Account object for the given user.

Parameters

ParamTypeRequiredDescription
function mycred_get_account(
$user_idINTNo

The users numeric ID.  If no ID is provided and the function is used after the WordPress init instance has run, the current users ID is used instead. Will return false if the user ID is invalid or if the current user is not logged in.

) { ... }

Example

Example 1: Get the account object for the user with the ID 3.

				
					$user_id = 3;
$account = mycred_get_account( $user_id );
if ( $account !== false ) {

	// Object exists

}
				
			

L

mycred_get_badge

Package: mycred/badge Category: Functions
 

Description

This function returns the myCRED Badge Object for a given badge ID.

 

Returns

(bool | object) Returns either the Badge object or FALSE if the ID is invalid or does not belong to a badge post type.

Parameters

ParamTypeRequiredDescription
function mycred_get_badge(
$badge_idINTYes

The badge post object ID.

$levelINTNo

Option to construct the object around a particular badge level. This in turn pre-loads level related details like the level image.

) { ... }

Example

Example 1: Display a given badges main image.

				
					$badge_id = 1;
$badge    = mycred_get_badge( $badge_id );

echo $badge->main_image;
				
			

 

mycred_get_badge_ids

Package: mycred/badge Category: Functions
 

Description

This function returns an array of published badge IDs.

 

Returns

(array) Array of post object IDs.

Parameters

ParamTypeRequiredDescription
function mycred_get_badge_ids(
No params
) { ... }

Example

Example 1: Count the number of published badges that exists on our website.

 
				
					$badge_ids = mycred_get_badge_ids();

printf( 'This website has %d badges you can earn.', count( $badge_ids ) );
				
			

 

mycred_get_badge_references

Package: mycred/badge Category: Functions
 

Description

This function will return an associative array of references and badge IDs that exists on your website. This function is mainly used for quick checks if a particular reference has badges associated with it.

 

Returns

(array) Associative array of references and the badge post object IDs belonging to each reference.

Parameters

ParamTypeRequiredDescription
function mycred_get_badge_references(
$point_typeSTRINGNo

Option to query badges for a particular point type. Defaults to the main point type.

$forceBOOLNo

By default, badge references are cached to minimize database queries. This cache is reset each time you save a badge but you can use this parameter to force a new query, which in turn will reset the current cached results.

) { ... }

Example

Example 1: Check if the reference “approved_comment“ exists among published badges.

 
				
					$reference  = 'approved_comment';
$badge_refs = mycred_get_badge_references();

if ( ! empty( $badge_refs ) && array_key_exists( $reference, $badge_refs ) ) {

	// Values are always an array since a reference might exists
	// in more than one badge
	$badge_ids = $badge_refs[ $reference ];

}
				
			

 

mycred_get_content_buyers_count

Package: mycred/content Category: Functions
 

Description

This function returns the total number of unique users that have purchased a given post.

 

Returns

(int) The total number of users that has bought this post.

Parameters

Param Type Required Description
function mycred_get_content_buyers_count(
$post_id INT Yes

The post object ID.

) { ... }

Example

Example 1: Get the current posts total buyers count.

				
					global $post;

printf( 'A total of %d users have bought access to this post!', mycred_get_content_buyers_count( $post->ID ) );

				
			

 

mycred_get_content_price

Package: mycred/content Category: Functions
 

Description

This function returns the set price for a post that has been set for sale using the Sell Content add-on.

 

Returns

(int | float) Returns the price set for the given point type.

Parameters

ParamTypeRequiredDescription
function mycred_get_content_price(
$post_idINTYes

The post object ID.

$point_typeSTRINGNo

Option to get a price of a specific point type. Should only be used if posts are set for sale using a custom point type.

) { ... }

Example

Example 1: Get the current posts price

 
				
					global $post;

if ( mycred_post_is_for_sale( $post ) )
	printf( 'This post costs %s points', mycred_get_content_price( $post->ID ) );
				
			

 

mycred_get_content_sales_count

Package: mycred/content Category: Functions
 

Description

This function returns the total number of times a particular posts content has been purchased.

 

Returns

(int) The total number of logged transactions.

Parameters

ParamTypeRequiredDescription
function mycred_get_content_sales_count(
$post_idINTYes

The post object ID.

) { ... }

Example

Example 1: Get the current posts total buyers count.

 
				
					global $post;

printf( 'This post has been purchased %d times.', mycred_get_content_sales_count( $post->ID ) );
				
			

 

mycred_get_coupon

Package: mycred/coupon Category: Functions
 

Description

This function returns a coupon object based on a coupon post ID.

 

Returns

(bool | object) Returns the coupon object or FALSE if the coupon post ID is invalid.

Coupon Object Example

				
					Std Object
(
    [post_id] => 1
    [code] => 'ABC123'
    [value] => 10.00
    [point_type] => 'mycred_default'
    [max_global] => 100
    [max_user] => 1
    [requires_min] => 0
    [requires_min_type] => 'mycred_default'
    [requires_max] => 0
    [requires_max_type] => 'mycred_default'
    [used] => 0
    [expires] => false
    [expires_unix] => false
)
				
			
 

Parameters

ParamTypeRequiredDescription
function mycred_get_coupon(
$coupon_post_idINTYes

The coupon post object ID.

) { ... }

Example

Example 1: Get a coupons point value.

				
					$coupon_id = 1;
$coupon    = mycred_get_coupon( $coupon_id );

printf( 'This coupon gives %d points.', $coupon->value );
				
			

 

mycred_get_email_notice

Package: mycred/email Category: Functions
 

Description

Returns an instance of the myCRED_Email object based on a given email notice post ID.

 

Returns

(bool | obj) Returns FALSE if an invalid email ID is provided else the myCRED_Email object.

Parameters

ParamTypeRequiredDescription
function mycred_get_email_notice(
$notice_idINTYes

The email notifications post ID.

) { ... }

Example

Example 1: Get an instance for the email notice ID 123

				
					$notice_id = 123;
$email     = mycred_get_email_notice( $notice_id );
if ( $email !== false ) {

	// do something

}
				
			

 

mycred_get_global_coupon_count

Package: mycred/coupon Category: Functions
 

Description

This function returns the total number of times a given coupon has been redeemed on your website.

 

Returns

(int) The total number of times the coupon has been used.

Parameters

ParamTypeRequiredDescription
function mycred_get_global_coupon_count(
$coupon_post_idINTYes

The coupon post object ID.

) { ... }

Example

Example 1: Count the number of times a coupon has been used.

 
				
					$coupon_id = 1;
$count     = mycred_get_global_coupon_count( $coupon_id );

printf( 'The coupon %s has been used %d times.', get_the_title( $coupon_id ), $count );
				
			

 

mycred_get_module

Package: mycred/core Category: Functions
 

Description

This function  will return a specific myCRED Module object.

 

Returns

(bool | object) Returns the module object or FALSE if the module is not found.

Parameters

ParamTypeRequiredDescription
function mycred_get_module(
$moduleSTRINGYes

The module ID.

$typeSTRINGYes

If the module supports multiple point types, you can use this to get the module under a specific point type. If the module however only supports one type, the correct value would be solo.

) { ... }

mycred_get_my_rank

Package: mycred/rank Category: Functions
 

Description

This function returns the current users myCRED rank object. Uses the mycred_get_users_rank function.

 

Returns

(object) Returns the current users rank object. If the user is not logged in, the function returns NULL.

Parameters

ParamTypeRequiredDescription
function mycred_get_my_rank(
No params
) { ... }

Example

Example 1: Show the current users rank.

 
				
					if ( is_user_logged_in() ) {

	$rank = mycred_get_my_rank();
	if ( isset( $rank->post_id ) ) {
		printf( 'Your current rank is: %s', $rank->title );
	}
	else {
		echo 'You do not have a rank yet.';
	}

}
				
			

 

mycred_get_point_type_name

Package: mycred/core Category: Functions
 

Description

This function returns a specific point type’s given name in singular or plural form.

 

 

Returns

(string) The point types name.

Parameters

ParamTypeRequiredDescription
function mycred_get_point_type_name(
$point_typeSTRINGNo

The point type key. Defaults to the default point type.

$singularBOOLNo

TRUE for singular form else FALSE.

) { ... }

mycred_get_rank

Package: mycred/rank Category: Functions
 

Description

This function will return the myCRED Rank Object for a given rank ID. Uses the mycred_get_rank_object_id function to convert rank names to rank IDs.

Returns

(bool | object) FALSE if the provided rank ID is invalid or the myCRED_Rank object.

Parameters

ParamTypeRequiredDescription
function mycred_get_rank(
$rank_identifierYes

Either the rank post object ID or the ranks name (case sensitive).

) { ... }

Example

Example 1: Get the rank object for the rank called “Master“.

				
					$rank_id = 'Master';
$rank    = mycred_get_rank( $rank_id );
				
			

 

mycred_get_rank_logo

Package: mycred/rank Category: Functions
 

Description

This function will return a given ranks logo image. Note that this function will return an image HTML element if the rank is found.

 

Returns

(bool | string) FALSE if the rank ID is invalid or if the logo is not set else the logo HTML image element.

Parameters

ParamTypeRequiredDescription
function mycred_get_rank_logo(
$rank_identifierINT or STRINGYes

Either the rank post object ID or the rank name (case sensitive).

$sizeSTRING or ARRAYNo

The image size. See the get_the_post_thumbnail function for possible values.

$attrARRAYNo

Optional image attributes to pass on to get_the_post_thumbnail function.

) { ... }

Example

Example 1: Get a ranks logo in thumbnail size (default).

 
				
					$rank_id   = 1;
$rank_logo = mycred_get_rank_logo( $rank_id );

echo $rank_logo;
				
			

Example 2: Get a ranks logo in full size.

 
				
					$rank_id   = 'Master';
$rank_logo = mycred_get_rank_logo( $rank_id, 'full' );

echo $rank_logo;
				
			

 

mycred_get_rank_object_id

Package: mycred/rank Category: Functions
 

Description

This function attempts to convert a given rank name into it’s post object ID. If a post ID is provided, this ID is returned instead. When providing a rank name, make sure the name is exact as names are case sensitive. Supports the Multisite Master Template feature.

 

Returns

(int | bool) The rank post object ID else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_get_rank_object_id(
$identifierINT or STRINGYes

Either a rank post object ID or a rank Name

) { ... }

Example

Example 1: Get the rank post ID for the rank “Beginner“.

 
				
					$rank_name = 'Beginner';
$rank_id   = mycred_get_rank_object_id( $rank_name );
				
			

 

mycred_get_ranks

Package: mycred/rank Category: Functions
 

Description

This function allows you to query existing ranks for a specific point type.

 

Returns

(array) Returns an associative array of rank objects or an empty array if no ranks were found.

Parameters

ParamTypeRequiredDescription
function mycred_get_ranks(
$statusSTRINGYes

Rank post object status to query. Defaults to publish for published ranks.

$numberINTYes

Number of ranks to get. Use -1 to return all. Defaults to -1.

$orderSTRINGNo

Sorting order of ranks. Accepts ASC for ascending or DESC for descending order. Defaults to DESC.

$point_typeSTRINGNo

Option to return ranks only for a particular point type. By default, this function will return all ranks no matter which point type they belong to. Should only be used if you need to get ranks of a custom point type.

) { ... }

Example

Example 1: Get all published ranks.

				
					$ranks = mycred_get_ranks();

				
			

Example 2: Get all published ranks for a custom point type

				
					$ranks = mycred_get_ranks( 'publish', -1, 'DESC', 'customtypekey' );

				
			

Example 3: Get the 5 lowest ranks.

				
					$ranks = mycred_get_ranks( 'publish', 5, 'ASC' );

				
			

 

mycred_get_recurring_payout

Package: mycred/banking Category: Functions
 

Description

This function returns the settings and status of a given scheduled recurring payout in the Banking add-on.

Returns

(array) Returns the setup and status array.

Schedule Setup Example

				
					Array
(
    [job_title]       => '',
    [status]          => 0,
    [payout]          => '',
    [frequency]       => 'daily',
    [last_run]        => '',
    [total_runs]      => 1,
    [runs_remaining]  => 0,
    [min_balance]     => 0,
    [max_balance]     => 0,
    [id_exclude]      => 'exclude',
    [id_list]         => '',
    [role_exclude]    => 'exclude',
    [role_list]       => array(),
    [log_template]    => '%plural% payout',
    [total_completed] => 0,
    [total_misses]    => 0,
    [ignore_central]  => 0
)
				
			

 

Parameters

ParamTypeRequiredDescription
function mycred_get_recurring_payout(
$schedule_idSTRINGYes

The recurring payout schedule ID.

$point_typeSTRINGNo

The point type key the schedule belongs to. Defaults to the default point type.

) { ... }

Example

Example 1: Show the total completed runs a given schedule has made so far.

 
				
					$schedule_id      = 'abc124';
$recurring_payout = mycred_get_recurring_payout( $schedule_id );

printf( 'A total of %d recurring payouts have run so far.', $recurring_payout['total_completed'] );
				
			

 

mycred_get_recurring_payout_schedules

Package: mycred/banking Category: Functions
 

Description

This function will return all currently existing recurring payout schedules in the Banking add-on.

 

Returns

(array) Returns an associative array of schedule IDs and the associated setup for each schedule.

Parameters

ParamTypeRequiredDescription
function mycred_get_recurring_payout_schedules(
$point_typeSTRINGNo

The point type key to return schedules for. Defaults to the default point type.

) { ... }

Example

Example 1: Count the total number of recurring schedules currently in use on our website.

 
				
					$schedules = mycred_get_recurring_payout_schedules();

printf( 'There are %d recurring payouts currently running on this website', count( $schedule ) );
				
			

 

mycred_get_remote

Package: mycred/core Category: Functions
 

Description

This function returns the Remove API (version 1.0) settings.

 

Returns

(array) Associative array.

Settings example:

				
					Array
(
    [enabled] => 0
    [key]     => 'abc123'
    [uri]     => 'api-dev'
    [debug]   => 0
)
				
			

 

Parameters

ParamTypeRequiredDescription
function mycred_get_remote(
No params
) { ... }

mycred_get_settings_network

Package: mycred/core Category: Functions
 

Description

This function returns the network settings on a Multisite installation.

 

Returns

(array | bool) Returns either the network settings array or FALSE if mulsite is not being used.

Network Settings Example

				
					Array
(
    [master]  => 0
    [central] => 0
    [block]   => ''
)
				
			

 

Parameters

ParamTypeRequiredDescription
function mycred_get_settings_network(
No params
) { ... }

mycred_get_total_by_time

Package: mycred/log Category: Functions
 

Description

This function will return the total number of points logged in the log table between two dates, either in total, for a specific reference or for a specific user.

 

Returns

(int | float) The total amount of points resulting from this query.

Parameters

ParamTypeRequiredDescription
function mycred_get_total_by_time(
$fromINT or STRINGNo

A timestamp or keyword that indicates from what date/time we should start counting. Uses strtotime to convert a start date/time into a UNIX timestamp. Defaults to the keyword today.

$untilINT or STRINGNo

A timestamp or keyword that indicates the date/time where counting should end. Uses strtotime to convert a end date/time into a UNIX timestamp. Defaults to the keyword now.

$referenceSTRINGNo

Option to filter the query to sum up only entries of a particular reference.

$user_idINTNo

Option to filter the query to sum up only entries of a particular user.

$point_typeSTRINGNo

Option to filter the query to sum up only entries of a particular point type. Defaults to the default point type.

) { ... }

Examples

Example 1: Get the total amount of points that users have gained/lost from start of today until now

				
					$total = mycred_get_total_by_time();

printf( 'A total of %d points have been gained today.', $total );
				
			

Example 2: Get the total amount of points that users have gained/lost from January 1st until November 30th.

 
				
					$total = mycred_get_total_by_time( '2016-01-01', '2016-11-30' );

echo $total . ' points';
				
			

Example 3: Get the total amount of points that has been spent on WooCommerce order payments the last 7 days.

 
				
					$total = mycred_get_total_by_time( '-1 week', 'now', 'woocommerce_payment' );

printf( 'A total of %d points have been spent in the store in the past 7 days', abs( $total ) );
				
			

 

mycred_get_transfer

Package: mycred/transfer Category: Functions
 

Description

This function retrieves the myCRED_Transfer object, populated based on the given transfer ID. This function can only be used for transfers that have been processed.

 

Returns

(bool | object) Either the myCRED_Transfer object or FALSE if the transfer was not found.

Parameters

ParamTypeRequiredDescription
function mycred_get_transfer(
$transfer_idSTRINGYes

The transfer ID.

) { ... }

Example

Example 1: Get the transfer object for a transfer ID.

 
				
					$transfer_id = 'TXT384723943843';
if ( function_exists( 'mycred_get_transfer' ) ) {

	$transfer = mycred_get_transfer( $transfer_id );
	if ( $transfer !== false ) {

		// found transfer

	}

}
				
			

 

mycred_get_unique_coupon_code

Package: mycred/coupon Category: Functions
 

Description

This function will generate a unique random code for coupons. The generated value is ensured to be unique.

 

Returns

(string) Random coupon code, 12 characters long.

Parameters

ParamTypeRequiredDescription
function mycred_get_unique_coupon_code(
No params
) { ... }

Example

Example 1: Generate a unique coupon code.

 
				
					$code       = mycred_get_unique_coupon_code();
$args       = array(
	'code'       => $code,
	'global_max' => 100,
	'value'      => 10,
	'expires'    => '2020-01-01'
);
$new_coupon = mycred_create_new_coupon( $args );
				
			

 

mycred_get_user_id

Package: mycred/core Category: Functions
 

Description

This function will attempt to return a user ID based on either an identifying piece of information (email, login or slug) or based on keywords.

 

Returns

(int | string) Returns either the users ID or the parameter passed to this function if nothing was found.

Parameters

ParamTypeRequiredDescription
function mycred_get_user_id(
$identifierINT or STRINGYes

Either a keyword or a piece of information that can be used to get a user from the database.

) { ... }

Keywords

KeywordDescription
currentRetrieves the current users ID. This will be zero if the user is not logged in.
authorReturns the current posts author ID. Can only be used inside the loop.
replyauthorReturns the bbPress topic reply authors ID. Can only be used inside a bbPress loop.
bbprofileReturns the displayed profiles ID. Can only be used in BuddyPress profile pages.

mycred_get_users_badges

Package: mycred/badge Category: Functions
 

Description

This function returns an array badge IDs that a given user has earned.

 

Returns

(string | array) Returns either an array of post IDs or an empty string if the user ID provided is invalid.

Parameters

ParamTypeRequiredDescription
function mycred_get_users_badges(
$user_idINTYes

The users numeric ID.

) { ... }

Example

Example 1: Count the number of badges the current user has earned

 
				
					$user_id   = get_current_user_id();
$badge_ids = mycred_get_users_badges( $user_id );

$badge_count = 0;
if ( ! empty( $badge_ids ) )
	$badge_count = count( $badge_ids );
				
			

 

mycred_get_users_balance

Package: mycred/balance Category: Functions
 

Description

This function returns a given user’s current point balance for a specific point type. If you are looking to get a users total balance, consider using the mycred_get_users_total_balance function instead.

 

Returns

(int | float | bool) Returns a users balance without any prefix or suffix formatting. If the user ID is invalid or the user is excluded, the function will return FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_get_users_balance(
$user_idINTYes

The users numeric ID.

$point_typeSTRINGNo

The point type key. Should only be used if you require the balance of a custom point type.

) { ... }

Examples

Example 1: Get the current users balance.

 
				
					$user_id = get_current_user_id();
$balance = mycred_get_users_balance( $user_id );
				
			

Example 2: Get the BuddyPress profiles custom point type balance.

 
				
					$profile_id = bp_displayed_user_id();
$balance    = mycred_get_users_balance( $profile_id, 'customtypekey' );
				
			

 

mycred_get_users_coupon_count

Package: mycred/coupon Category: Functions
 

Description

This function returns the total number of times a user has redeemed a specific coupon.

 

Returns

(int) The number of times the coupon has been used.

Parameters

ParamTypeRequiredDescription
function mycred_get_users_coupon_count(
$codeSTRINGYes

The coupon code. Note that this function checks the code and not the post ID.

$user_idINTYes

The users numeric ID.

) { ... }

Example

Example 1: Check the number of times a user has used our holiday coupon.

 
				
					$coupon_code = 'XMASOFFER';
$user_id     = get_current_user_id();
$count       = mycred_get_users_coupon_count( $coupon_code, $user_id );

printf( 'You have used this coupon %d times', $count );
				
			

 

mycred_get_users_of_rank

Package: mycred/rank Category: Functions
 

Description

This function allows you to query users of a specific rank. Users will be sorted based on their balance.

 

Returns

(array) Returns an array of objects with users ID and their current balance or an empty array if no users were found.

Parameters

ParamTypeRequiredDescription
function mycred_get_users_of_rank(
$rank_identifierINT or STRINGYes

Either the rank post object ID or the ranks name (case sensitive).

$numberINTYes

The number of users to return. Use -1 to return all users. Defaults to -1.

$orderSTRINGNo

The sorting order. Accepts ASC for ascending or DESC for descending order. Defaults to DESC.

$point_typeSTRINGNo

Point type key. Should only be used if you want to show users with a rank of a custom point type.

) { ... }

Example

Example 1: Get the top 10 users with the rank “Master“.

 
				
					$users = mycred_get_users_of_rank( 'Master', 10 );

				
			

 

mycred_get_users_profile_url

Package: mycred/core Category: Functions
 

Description

This function will return a given users profile URL based on your websites setup. If you have BuddyPress or bbPress installed, the function will return the profile URL these plugins provide. Supports setups where the author_base has been changed.

 

Returns

Returns the profile url string of the given user or an empty string if the user ID is blank or zero.

Parameters

ParamTypeRequiredDescription
function mycred_get_users_profile_url(
$user_idINTYes

The numeric user ID.

) { ... }

Example

Example 1: Echo the current users profile URL.

 
				
					if ( function_exists( 'mycred_get_users_profile_url' ) ) {

	$user_id     = get_current_user_id();
	$profile_url = mycred_get_users_profile_url( $user_id );

	echo '<a href="' . esc_url( $profile_url ) . '">View Profile</a>';

}
				
			

 

mycred_get_users_rank

Package: mycred/rank Category: Functions
 

Description

This function will retrieve a given users current rank object for a specific point type. If you only need the rank post object ID, consider instead using the mycred_get_users_rank_id function instead.

 

Returns

(object | string) Returns either the rank object or an empty string if the user does not have a rank.

Parameters

ParamTypeRequiredDescription
function mycred_get_users_rank(
$user_idINTYes

The numeric ID of the user.

$point_typeSTRINGNo

The point type key to return a rank for. Should only be used when you have ranks setup for more than one point type.

) { ... }

Example

Example 1: Get a users rank object.

 
				
					$user_id = 1;

// Always make sure the function exists to prevent crashes
// If the ranks add-on gets disabled or myCRED gets disabled
// this function will no longer exist!
if ( function_exists( 'mycred_get_users_rank' ) ) {

	// Get rank object
	$rank = mycred_get_users_rank( $user_id );
	
	// If the user has a rank, $rank will be an object
	if ( is_object( $rank ) ) {
	
		// Show rank title
		echo $rank->title;
	
		// Show rank logo (if one exists)
		if ( $rank->has_logo )
			echo $rank->get_image( 'logo' );
	
		// Show total number of users with this rank
		echo $rank->count;
	
	}

}
				
			

 

mycred_get_users_rank_id

Package: mycred/rank Category: Functions
 

Description

This function returns a given users current rank post object ID of a specific point type. If you are looking to get the users rank object, consider using mycred_get_users_rank instead.

 

Returns

(string | int) Returns either the rank post object ID or an empty string if no rank is found.

Parameters

ParamTypeRequiredDescription
function mycred_get_users_rank_id(
$user_idINTYes

The users numeric ID.

$point_typeSTRINGNo

The point type key to return a rank for. Should only be used when you have ranks setup for more than one point type.

) { ... }

Example

Example 1: Get the current users rank and display the ranks title.

 
				
					$user_id = get_current_user_id();
$rank_id = mycred_get_users_rank_id( $user_id );

if ( $rank_id != '' )
	printf( 'Your current rank is: %s', get_the_title( $rank_id ) );
else
	echo 'You do not have a rank yet';
				
			

 

mycred_get_users_reference_sum

Package: mycred/log Category: Functions
 

Description

This function will return an array of all point instances a user has based on the log. The array will include the reference and the amount of points that have been gained / spent for that reference.

 

Returns

(array) Associative array of references and points.

Results example where a user has a history of getting points for comments, publishing content and has spent points in a WooCommerce store

				
					Array
(
    [approved_comment]    => 25
    [publishing_content]  => 150
    [woocommerce_payment] => -3200
)
				
			
 

Parameters

ParamTypeRequiredDescription
function mycred_get_users_reference_sum(
$user_idINTYes

The users numeric ID.

$point_typeSTRINGNo

The point type to query. Note that a point type must be set in order to use this function. You can not query points for all point types with this function. Defaults to the default point type.

) { ... }

Example

Example 1: Check if the current user has gained myCRED points for publishing content, and if they have gained more than 1000 points and are not yet authors, promote them to the Author role.

 
				
					$user_id  = get_current_user_id();
$ref_sums = mycred_get_users_reference_sum( $user_id );

// Check if user has gained points for published content
if ( ! empty( $ref_sums ) && array_key_exists( 'publishing_content', $ref_sums ) ) {

	// If they have, check if it's over 1000 points and that they are not yet "Authors"
	if ( $ref_sums['publishing_content'] >= 1000 && ! user_can( $user_id, 'publish_posts' ) )
		wp_update_user( array(
			'ID'   => $user_id,
			'role' => 'author'
		) );

}
				
			

 

mycred_get_users_total_balance

Package: mycred/balance Category: Functions
 

Description

This function returns a given user’s total point balance for a specific point type. If you are looking to get a users current balance, consider using the mycred_get_users_balance function instead.

 

Returns

(int | float | bool) Returns a users balance without any prefix or suffix formatting. If the user ID is invalid or the user is excluded, the function will return FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_get_users_total_balance(
$user_idINTYes

The users numeric ID.

$point_typeSTRINGNo

The point type key. Should only be used if you require the balance of a custom point type.

) { ... }

Examples

Example 1: Get the current users total balance.

 
				
					$user_id = get_current_user_id();
$balance = mycred_get_users_total_balance( $user_id );
				
			

Example 2: Get the BuddyPress profiles custom point type total balance.

 
				
					$profile_id = bp_displayed_user_id();
$balance    = mycred_get_users_total_balance( $profile_id, 'customtypekey' );
				
			

 

mycred_get_woo_product_reward

Package: mycred/payment Category: Functions
 

Description

This function will retrieve the amount of points a WooCommerce product is set to reward when purchased, or an array of point types with their associated values if more than one point type exists. Supports both single or variable product types.

 
 

 

Returns

(bool) FALSE if the product ID is invalid, an array of the reward setup for all point types or the point value in string form when used to retrieve a particular point type.

Parameters

ParamTypeRequiredDescription
function mycred_get_woo_product_reward(
$product_idINTYes

The WooCommerce product post object ID.

$variation_idINTNo

Should be set to NULL if the product is not a variable product, otherwise the variations numeric ID.

$requested_typeBOOL or STRINGNo

Use FALSE to retrieve values for multiple point types in a associative array format or provide the point type key to retrieve the value for a particular type.

) { ... }

Example

Example 1: Basic usage example where we show how much points a product rewards (if set).

 
				
					if ( function_exists( 'mycred_get_woo_product_reward' ) ) {

	$product_id = 1;
	$point_type = MYCRED_DEFAULT_TYPE_KEY;
	$reward     = mycred_get_woo_product_reward( $product_id, NULL, $point_type );

	if ( $reward !== false && $reward != '' )
		printf( 'Earn %s Points buying this product.', $reward );

}
				
			

 

mycred_have_ranks

Package: mycred/rank Category: Functions
 

Description

This function checks if there are published rank post objects for a particular point type.

 

Returns

(bool) TRUE if there are published ranks else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_have_ranks(
$point_typeSTRINGNo

The point type key to check ranks for. Defaults to the default point type.

) { ... }

mycred_is_admin

Package: mycred/core Category: Functions
 

Description

This function checks if a specific user is to be considered an “administrator”. Administrators are users that have one of the capabilities you have set for “Point Editors” or “Point Administrators”.

 

 

Returns

(bool) TRUE if the user is an administrator else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_is_admin(
$user_idINTNo

The users numeric ID. If no ID is provided, the current user will be checked.

$point_typeSTRINGNo

The point type key. Should only be used if you are checking for a custom point type.

) { ... }

Example

Example 1: Check if the current user is an administrator.

 
				
					if ( mycred_is_admin() ) {

	// User is an admin

}
				
			

 

mycred_label

Package: mycred/core Category: Functions
 

Description

This function returns the myCRED label as defined either via the mycred_label filter or by the MYCRED_DEFAULT_LABEL constant.

 

Returns

(string) The plugin name.

Parameters

ParamTypeRequiredDescription
function mycred_label(
$trimBOOLNo

TRUE to strip HTML tags of the name (if used) else FALSE.

) { ... }

mycred_new_transfer

Package: mycred/transfer Category: Functions
 

Description

This function attempts to process a transfer request that has been submitted by a transfer form. If no transfer form is used and you need to process a new transfer artificially, make sure you simulate a form submission by providing an array of form names and values.

 

Returns

(bool | string | array) Returns either an error code if the request could not be processed, FALSE if the request was valid but the transaction could not be completed else an array of transfer results.

Parameters

ParamTypeRequiredDescription
function mycred_new_transfer(
$requestARRAYYes

The transfer request array.

$postedARRAYYes

An array of the transfer form that was submitted.

) { ... }

mycred_override_settings

Package: mycred/core Category: Functions
 

Description

This function checks if the master template feature is enabled on a Multisite installation. Will return FALSE if Multisite are not being used.

 

Returns

(bool) TRUE if the master template feature is enabled else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_override_settings(
No params
) { ... }

Example

Example 1: Default usage

 
				
					if ( mycred_override_settings() ) {

	// Master Template is enabled

}
				
			

 

mycred_post_is_for_sale

Package: mycred/content Category: Functions
 

Description

This function checks if a specific post is set for sale in the Sell Content add-on. This can be due to all posts of this type is set for sale or in manual mode, if the post has been selected to be for sale.

 

Returns

(bool) TRUE if the post is for sale else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_post_is_for_sale(
$post_idINT or OBJYes

Either a post object ID or a post object.

) { ... }

Example

Example 1: Check if the current post, based on the $post global, is set for sale.

 
				
					global $post;

if ( mycred_post_is_for_sale( $post ) ) {

	// Post is set for sale

}
				
			

 

mycred_post_type_for_sale

Package: mycred/content Category: Functions
 

Description

This function checks if a given post type is set for sale in the Sell Content settings.

 

Returns

(bool) TRUE if the post type is set for sale else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_post_type_for_sale(
$post_typeSTRINGYes

The WordPress post type to check.

) { ... }

Example

Example 1: Check if the custom post type “Book“ is set for sale.

 
 
				
					$post_type = 'book';

if ( mycred_post_type_for_sale( $post_type ) ) {

	// Post type is set for sale

}
				
			

 

mycred_query_users_total

Package: mycred/balance Category: Functions
 

Description

This function will query the myCRED log in order to get a given users total balance for a particular point type.

 

Returns

(int | float) The users total balance.

Parameters

ParamTypeRequiredDescription
function mycred_query_users_total(
$user_idINTYes

The users numeric WordPress ID.

$point_typeSTRINGNo

The point type key indicating the point type we want to calculate a total for.

) { ... }

Example

Example 1: Get the current users default point type total. (recommended usage when you only have one point type setup).

 
				
					$user_id = get_current_user_id();
$total   = mycred_query_users_total( $user_id );
				
			

 

mycred_rank_has_logo

Package: mycred/rank Category: Functions
 

Description

This function checks if a given rank has a logo using the has_post_thumbnail function.

 

Returns

(bool) Returns TRUE if the rank has a logo else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_rank_has_logo(
$rank_identifierINT or STRINGYes

Either the ranks post object ID or the ranks exact name.

) { ... }

Example

Example 1: Get the current users rank and check if the rank has a logo.

 
				
					$user_id = get_current_user_id();
$rank_id = mycred_get_users_rank( $user_id );

if ( mycred_rank_has_logo( $rank_id ) ) {

	// Rank has logo

}
				
			

 

mycred_refund_transfer

Package: mycred/transfer Category: Functions
 

Description

This function attempts to refund a completed transfer.

 

Returns

(bool) Returns TRUE if the refund was successful else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_refund_transfer(
$transfer_idSTRINGYes

The transfer ID.

) { ... }

Example

Example 1: Basic usage example.

 
				
					$transfer_id = 'TXT384723943843';
if ( function_exists( 'mycred_get_transfer' ) ) {

	$transfer = mycred_refund_transfer( $transfer_id );
	if ( $transfer === true ) {

		// transfer was refunded

	}
	else {

		// Refund failed

	}

}
				
			

 

mycred_sell_content_new_purchase

Package: mycred/content Category: Functions
 

Description

This function will attempt to charge a given user for a piece of content that has been set for sale using the Sell Content add-on. If profit sharing is enabled, the function will also payout the post author their share if the user was successfully charged.

 

Returns

(bool) TRUE if the purchase completed successfully else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_sell_content_new_purchase(
$postOBJYes

The post object being purchased.

$user_idINTYes

The users numeric ID.

$point_typeSTRINGYes

The point type used as payment.

) { ... }

Example

Example 1: Attempt to charge the current user for purchasing a post.

 
				
					$post_id = 1;
$post    = get_post( $post_id );
$user_id = get_current_user_id();

// Make sure the post is for sale and we have not paid for it
if ( mycred_post_is_for_sale( $post ) && ! mycred_user_paid_for_content( $user_id, $post->ID ) ) {

	// Now charge
	$result = mycred_sell_content_new_purchase( $post, $user_id, 'mycred_default' );

	// Payment successfull!
	if ( $result ) {

	}

	// Payment declined for some reason
	else {

	}

}
				
			

 

mycred_sell_content_payment_buttons

Package: mycred/content Category: Functions
 

Description

This function will return all available payment buttons that a user can use, in order to pay for a posts content. This function will check if the user can afford to pay, are not excluded. This function will however not check if the post is set for sale. This needs to be done before using this function.

 

Returns

(bool | string) Returns a string containing button elements for each point type that can be used by the user. Else returns FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_sell_content_payment_buttons(
$user_idINTYes

The users numeric ID.

$post_idINTYes

The post object ID.

) { ... }

mycred_sell_content_post_id

Package: mycred/content Category: Functions
 

Description

This function attempts to get the current posts ID. It can be used inside a bbPress forum loop in which case the function will attempt to get the forum / topic or replies ID. Must be used inside the loop.

 

Returns

(int | bool) Either the current post objects ID or FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_sell_content_post_id(
No params
) { ... }

Example

Example 1: Default usage.

 
				
					$post_id = mycred_sell_content_post_id();

if ( $post_id !== false ) {

}
				
			

 

mycred_subtract

Package: mycred/balance Category: Functions
 

Description

This function allows you to decrease a users balance by deducting a specific amount from it. This function uses mycred_add to adjust the balance but forces any value you provide to be a negative value.

 

Returns

(bool) true on success or false on declined transaction.

Parameters

ParamTypeRequiredDescription
function mycred_subtract(
$referenceSTRINGYes

The reference to log this entry under. You can use your own custom reference or one of the built-in ones.

$user_idINTYes

The users numeric ID.

$amountINT or FLOATYes

The point amount to deduct from the user. Positive values will be turned negative.

$entrySTRINGYes

The entry to save in the log for this adjustment.

$ref_idINTNo

Optional reference ID to save with the log entry.

$dataSTRINGNo

Optional data to save with the log entry. Note that if you are supply an array, this will be serialized.

$typeSTRINGNo

The point type key. Should only be used if you are adjusting a custom point type and not the default one.

) { ... }

Example

Example 1: Deduct 10 points from a user.

 
				
					$user_id = get_current_user_id();
mycred_subtract( 'penalty', $user_id, -10, 'Points penalty' );
				
			

 

mycred_transfer

Package: mycred/transfer Category: Functions
 

Description

This function will returns the myCRED_Transfer object. Note that this function will not populate the object.

 

Returns

(object) Returns the myCRED_Transfer object.

Parameters

ParamTypeRequiredDescription
function mycred_transfer(
$transfer_idSTRINGNo

The transfer ID if you plan on using the object to manipulate or process a transfer. Can be ignored when using the object to render a new transfer form.

) { ... }

mycred_use_coupon

Package: mycred/coupon Category: Functions
 

Description

This function will validate and a given coupon code and if the coupon can be used, redeems the coupon.

 

Returns

(int | float | bool | string) Returns FALSE if the coupon can not be used, a string if the coupon is not valid or the users balance after the coupon was applied if the coupon is valid and was successfully used.

Error Codes

You can use the mycred_get_coupon_error_message function to convert an error code into a readable message.

Error CodeDescription
invalidThe coupon code or user ID is invalid. Remember that codes are case sensitive.
expiredThe coupon has expired. This occurs if an expiration date has been reached or the maximum usage limit has been reached.
user_limitUser limit reached.
minThe user does not meet the minimum balance requirement set for this coupon.
maxThe user does not meet the maximum balance requirement set for this coupon.
excludedThe user is excluded from the point type that the coupon is set to payout.

Parameters

ParamTypeRequiredDescription
function mycred_use_coupon(
$codeSTRINGYes

The coupon code.

$user_idINTYes

A numeric user ID that will receive the points if the coupon is valid.

) { ... }

Example

Example 1: Apply a posted coupon code to the current user.

 
				
					$user_id = get_current_user_id();
$code    = $_POST['coupon'];

$results = mycred_use_coupon( $code, $user_id );

if ( mycred_coupon_was_successfully_used( $results ) ) {

	// Coupon was successfully used

}
else {

	// Something went wrong

}
				
			

 

mycred_user_can_transfer

Package: mycred/transfer Category: Functions
 

Description

This function checks if a user can afford or allowed to make a transfer, of a specified amount of points. The function will check to make sure:

  • A users balance does not go below zero if the transaction would be approved. You can use the mycred_transfer_limit filter to adjust this and allow transfers that would bring a users balance into the negative.
  • The transfer is within the users limit (if limits are enforced).

 

Returns

(int | float | string) Returns TRUE if the user can make a transfer and there is no transfer limit set. If a limit is set but the user can make the transfer, the function will return the amount remaining. Else returns an error code.

Error Codes

Error CodeDescription
lowThe user can not afford to transfer the given amount or the users balance has reached zero.
limitThe set limit has been reached.

Parameters

ParamTypeRequiredDescription
function mycred_user_can_transfer(
$user_idINTYes

The users numeric ID.

$amountINT or FLOATNo

Optional amount that the user is requesting to transfer. If not set the users current balance is used to check for solvency.

$point_typeSTRINGNo

The point type key used for this transfer. Defaults to the default point type.

$referenceSTRINGNo

Optional reference to check for limits. This should only be used when a limit is being enforced.

) { ... }

Example

Example 1: Check if the current user can make a 10 point transfer.

				
					$user_id = get_current_user_id();

if ( mycred_user_can_transfer( $user_id, 10 ) ) {

	// User can transfer

}
				
			

 

mycred_user_paid_for_content

Package: mycred/content Category: Functions
 

Description

This function checks if a given user has a valid and active payment for a specific post that is set for sale.

 

Returns

(bool) TRUE if the user has paid and the purchase has not expired else FALSE.

Parameters

ParamTypeRequiredDescription
function mycred_user_paid_for_content(
$user_idINTYes

The users numeric ID.

$post_idINTYes

The post objects ID.

) { ... }

Example

Example 1: Check if the current post is set for sale and if it is, if the current user has paid for it.

				
					global $post;

$user_id = get_current_user_id();
if ( mycred_post_is_for_sale( $post ) && mycred_user_paid_for_content( $user_id, $post->ID ) ) {

	// Post is for sale and the user has paid

}