myCRED_Settings

Description

This class constructs and enables a set of core tools that allows you to execute point related actions or retrieve points related details.

Multiple point type support was added in version 1.4. Older versions of this class differ significantly and are no longer supported!

Available since version 1.0

Interacting with the Class

While the class can be called directly, it is highly recommended that you instead use the mycred function. 

				
					// Default usage
$mycred = mycred();

// Setup for a custom point type
$mycred = mycred( 'customtypekey' );
				
			

Class Properties

Property Declared Type Description
$core Public array The settings array for the current point type.
$log_table Public string The database table name based on your Network settings (if you use Multisite).
$cred_id Public string The meta key ID of the current point type.
$is_multisite Public bool The value of the is_multisite function.
$use_master_template Public bool True if the master template feature is enabled. False if not using multisite.
$use_central_logging Public bool True if the central logging is enabled. False if not using multisite.

Class Parameters

The class has only one parameter that can be used.

Parameter Type Required Description
$typekey string No The point type key to construct.

Class Methods

While you can interact with balances without using this class, the methods offered here will make sure your interaction happens faster and safer. Using these methods also ensures that you always have access to all point related features in myCRED.

public function defaults() {
Description: Returns the default settings array which is used when compiling the point type's settings.
Variable Type Required Description
No variables
}
public function singular() {
Description: Returns the current point types name in singular form.
Variable Type Required Description
No variables
}

Example 1: Display the point types given name in singular form

				
					$mycred = mycred();
echo $mycred->singular();
				
			
public function plural() {
Description: Returns the current point types name in plural form.
Variable Type Required Description
No variables
}

Example 1: Display the point types given name in plural form

				
					$mycred = mycred();
echo $mycred->plural();
				
			
public function zero() {
Description: Returns zero formatted according to the point type setup.
Variable Type Required Description
No variables
}
public function number( $number = '' ) {
Description: Returns the given value formatted according to the point types setup. Should be used when points are used in calculations.
Variable Type Required Description
number int or float Yes The value to format.
}
public function format_number( $number = '' ) {
Description: Returns a given value formatted based on the point types settings as a string. Should be used when points are intended to be displayed and not used in calculations.
Variable Type Required Description
number int or float Yes The value to format.
}
public function format_creds( $creds = 0, $before = '', $after = '', $force_in = false ) {
Description: Returns a given value formatted based on the point types settings with prefix / suffix added (if used). Can not be used in calculations!
Variable Type Required Description
creds int or float Yes The value to format.
before string No Optional string to attach before the formatted point value. If you use a prefix, this string is appended before the prefix.
after string No Optional string to attach after the formatted point value. If you use a suffix, this string is appended after the suffix.
force_in bool No Option to force the $before or $after variables before / after the prefix / suffix.
}

Example 1: Display a users balance formatted with a prefix / suffix (if used)

				
					$mycred  = mycred();
$balance = $mycred->get_users_balance( get_current_user_id() );
echo $mycred->format_creds( $balance );
				
			
public function round_value( $amount = 0, $up_down = false, $precision = 0 ) {
Description: Rounds a given value either up or down with an option to set the precision.
Variable Type Required Description
amount int or float Yes The value to round.
up_down string Yes Either "up" to round up or "down" to round down.
precision int No Rounding precision. Defaults to zero.
}
public function get_lowest_value() {
Description: Returns the lowest possible points value above zero based on the point type setup. A point type setup that does not uses any decimals would return 1 while a point type using for example 2 decimal places would return 0.01. Mainly used to prevent users from sending partial points.
Variable Type Required Description
No variables
}
public function apply_exchange_rate( $amount = 0, $rate = 1, $round = true ) {
Description: Divides the amount by the given rate.
Variable Type Required Description
amount int or float Yes The initial point amount.
rate int or float Yes The exchange rate that are applied to the amount.
round bool No Option to round the value. Uses PHP round.
}
public function parse_template_tags( $content = '', $log_entry ) {
Description: Parses template tags in a given string. Can only be used when a log entry object is available. Based on the data column details, this method loads the appropriate template tag processor (see below).
Variable Type Required Description
content string Yes The string that potentially contain template tags.
log_entry object Yes The log entry object.
}
public function template_tags_general( $content = '' ) {
Description: Converts general template tags into their appropriate values.
Variable Type Required Description
content string Yes The string that potentially contain template tags.
}
public function template_tags_amount( $content = '', $amount = 0 ) {
Description: Converts amount related template tags into their appropriate values. Uses template_tags_general().
Variable Type Required Description
content string Yes The string that potentially contain template tags.
amount int or float Yes The amount to use when replacing amount related template tags.
}
public function template_tags_post( $content = '', $ref_id = NULL, $data = '' ) {
Description: Converts post related template tags into their appropriate values. Uses template_tags_general().
Variable Type Required Description
content string Yes The string that potentially contain template tags.
ref_id int Yes The reference ID stored with the log entry, usually the post object ID.
data string or array No The data stored with the log entry. Mainly used when a post has been deleted as the old past data is stored in the data column.
}
public function template_tags_user( $content = '', $ref_id = NULL, $data = '' ) {
Description: Converts user related template tags into their appropriate values. Uses template_tags_general().
Variable Type Required Description
content string Yes The string that potentially contain template tags.
ref_id int Yes The reference ID stored with the log entry, usually the user object ID.
data string or array No The data stored with the log entry.
}
public function template_tags_comment( $content = '', $ref_id = NULL, $data = '' ) {
Description: Converts comment related template tags into their appropriate values. Uses template_tags_general().
Variable Type Required Description
content string Yes The string that potentially contain template tags.
ref_id int Yes The reference ID stored with the log entry, usually the comment object ID.
data string or array No The data stored with the log entry.
}
public function has_tags( $type = '', $tags = '', $content = '' ) {
Description: Checks if a given string contains any template tags based on a set type e.g. comment, post or user. Returns true or false.
Variable Type Required Description
type string Yes The template tag type.
tags string Yes List of template tags to check for. This list is passed on to preg_match so if more then one tag needs to be checked for, this must be separated with a horizontal line |.
content string Yes The content string that needs to be checked.
}
public function available_template_tags( $available = array(), $custom = '' ) {
Description: Returns a string indicating the available template tags that can be used.
Variable Type Required Description
available array Yes An array or template tag types. These will be listed after the sentence: Available Template Tags:.
custom string No Optional list of additional / special template tags that are appended at the end of the string.
}
public function allowed_tags( $data = '', $allow = '' ) {
Description: Strips HTML tags of a given string based on the allowed html tags list provided by the allowed_html_tags method.
Variable Type Required Description
data string Yes The string that contains HTML tags that needs to be stripped.
allow array or bool No Either false to strip all tags, an array or allowed HTML tags not to strip of or if left empty, a default set of tags are removed.
}
public function edit_creds_cap() {
Description: Returns the capability set for point editors.
Variable Type Required Description
No variables
}

Example 1: Make sure the current user is a point editor.

				
					$mycred = mycred();

// If the current user is a "point editor"
if ( current_user_can( $mycred->edit_creds_cap() ) ) {

}
				
			
public function can_edit_creds( $user_id = '' ) {
Description: Checks if a given user is a "point editor" based on the current point type. Uses user_can.
Variable Type Required Description
user_id int Yes The user ID to check.
}
public function edit_plugin_cap() {
Description: Returns the capability set for point administrators.
Variable Type Required Description
No variables
}

Example 1: Make sure the current user is a point editor.

				
					$mycred = mycred();

// If the current user is a "point administrator"
if ( current_user_can( $mycred->edit_plugin_cap() ) ) {

}
				
			
public function can_edit_plugin( $user_id = '' ) {
Description: Checks if a given user is a "point administrator" based on the current point type. Uses user_can.
Variable Type Required Description
user_id int Yes The user ID to check.
}
public function in_exclude_list( $user_id = '' ) {
Description: Checks if a given user is in the list of excluded users. The ID is checked against the comma separated list of IDs you might have set to the current point type.
Variable Type Required Description
user_id int Yes The user ID to check.
}
public function exclude_plugin_editors() {
Description: Checks if the current point type has been set to exclude "point administrators". Returns true or false.
Variable Type Required Description
No variables
}
public function exclude_creds_editors() {
Description: Checks if the current point type has been set to exclude "point editors". Returns true or false.
Variable Type Required Description
No variables
}
public function exclude_user( $user_id = NULL ) {
Description: Checks if the given user is excluded from the current point type.
Variable Type Required Description
user_id int Yes The user object ID.
}

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

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

if ( ! $mycred->exclude_user( $user_id ) ) {

	// User is not excluded

}
				
			
public function count_members() {
Description: Returns the total number of users with a balance of the current point type.
Variable Type Required Description
No variables
}
public function get_cred_id() {
Description: Returns ID of the current point type.
Variable Type Required Description
No variables
}
public function max() {
Description: Returns the highest value allowed for the current point type.
Variable Type Required Description
No variables
}
public function get_users_balance( $user_id = NULL, $type = NULL ) {
Description: Returns the given users current balance for either a given point type or the current point type.
Variable Type Required Description
user_id int Yes The users numeric ID.
type string No Option to retrieve a users balance for a different point type then the current one. If you are want the current point types balance then this should not be used.
}

Example 1: Get the current users balance for the current point type

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

// Get the balance if the user is not excluded
if ( ! $mycred->exclude_user( $user_id ) )
	$balance = $mycred->get_users_balance( $user_id );
				
			

It is highly recommended that you always check if a user is excluded before attempting to get their balance or before you introduce the user to balance related features. You might not be excluding a user right now but might do so at a later stage.

public function update_users_balance( $user_id = NULL, $amount = NULL, $type = NULL ) {
Description: Updates a given users points balance by a given value. This value can be positive to increase a users balance or negative to reduce a balance.
Variable Type Required Description
user_id int Yes The users numeric ID.
amount int or float Yes The point amount to adjust the balance with. This value must be properly formatted. If the point type does not use decimals, then the amount can not use decimals either.
type string No Option to update a different point balance then the current point type.
}

Example 1: Add 10 points to the current users balance.

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

// Update the balance if the user is not excluded
if ( ! $mycred->exclude_user( $user_id ) )
	$mycred->update_users_balance( $user_id, $amount );
				
			

Example 2: Deduct 50 points to the current users balance.

				
					$user_id = get_current_user_id();
$mycred  = mycred();
$amount  = -50;

// Update the balance if the user is not excluded
if ( ! $mycred->exclude_user( $user_id ) )
	$mycred->update_users_balance( $user_id, $amount );
				
			

This method does not check if the user you are adjusting the balance for is excluded or not! This needs to be done before using this method.

public function set_users_balance( $user_id = NULL, $new_balance = NULL ) {
Description: Changes a users balance to the given value. Added in 1.7.3. Can only be used for the current point type.
Variable Type Required Description
user_id int Yes The users numeric ID.
new_balance int or float Yes The point amount to adjust the balance with. This value must be properly formatted. If the point type does not use decimals, then the amount can not use decimals either.
}

Example 1: Change the current users balance to 100 points.

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

// Update the balance if the user is not excluded
if ( ! $mycred->exclude_user( $user_id ) )
	$mycred->set_users_balance( $user_id, $new_balance );
				
			
public function add_creds( $ref = '', $user_id = '', $amount = '', $entry = '', $ref_id = '', $data = '', $type = MYCRED_DEFAULT_TYPE_KEY ) {
Description: Adds or deducts points from a given users account and saves a log entry of the transaction. Contrarily to what the name suggests, this method can be used to adding points as well as deducting points.
Variable Type Required Description
ref string Yes The reference to log the transaction under.
user_id int Yes The users numeric ID.
amount int or float Yes The point amount to adjust the balance with. This value must be properly formatted. If the point type does not use decimals, then the amount can not use decimals either.
entry string Yes The log entry of the transaction. This is what is shown to users in the logs.
ref_id int No Optional reference ID to save with the log entry.
data string or array No Optional data to save with the log entry. This can be a string or an array. Note that arrays will be serialized before saved to the log.
type string No The point type to adjust and log the transaction under. Should only be used if the point type is not the current point type set in this class.
}

Example 1: Give a user 10 points and log it as a “Donation“.

				
					$user_id = 1;
$amount  = 10;
$mycred  = mycred();

if ( ! $mycred->exclude_user( $user_id ) )
	$mycred->add_creds(
		'donation',
		$user_id,
		$amount,
		'%plural% donation'
	);