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'
);