Useful Core Functions

[Jimmi08]

Useful Core Functions

Contents
1 Introduction
1.1 Validation
1.1.1 check_email()
1.1.2 varset(), varsettrue()
1.1.3 defset(), defsettrue()
1.2 User
1.2.1 check_class()
1.2.2 get_user_data()
1.2.3 r_userclass()
1.3 JavaScript
1.3.1 js_location()

Introduction
The e107 core code includes many useful functions that you can use in plugins, themes, and other third-party code integrated into the CMS.

Validation
Data validation functions.

check_email()
Check the validity of an email address against a generic email address format regex.

Parameters

string $email - the email address to be validated
Returns

true for a valid e-mail address, otherwise false
Code: Example call

// Check an email address is valid
$emailAddress = "[email protected]";
if(check_email($emailAddress)){
   echo "The email address appears to be a valid";
}else{
   echo "The email address is not valid";
}

varset(), varsettrue()
function varset(&$val,$default=) function varsettrue(&$val,$default=)

varset() returns the value of $var if set (i.e. the variable exists/is defined), else returns a default value.

varsettrue() is similar to varset(), except that the value of $var is evaluated for true/false. If $val evaluates as 'true', $val is returned; otherwise the default is returned.

Parameters

variable &$var - the variable whose value is to be returned if it is set.
mixed $default - default value to be returned if $var is not set. This defaults to empty string.

Returns

the value of $var if set, else returns a default. Optionally check $var value is not false as well.
Code: Example call

// Fix a bug -- PHP Notice complains that 'pref' is not set
$something = $pref; // Bug if pref not set
$something = varset($pref); // correct

// Why evaluate pref twice?
$something = isset($pref) ? $pref : ""; // This is long and complicated
$something = varset($pref); // Simple

// Same thing but 'default' isn't just blank.
$something = isset($pref) ? $pref : $default;
$something = varset($pref, $default);

// I want pref only if it is set AND has a value...
$something = isset($pref) && $pref ? $pref : $default; // pref is coded 3 times!
$something = varsettrue($pref, $default); // Nice and simple

defset(), defsettrue()
function defset($str,$default=) function defsettrue($str,$default=)

Similar to varset() and varsettrue(), but check whether a named constant has been defined.

defset() returns the value of the named constant value if its defined; else returns a default value.

defsettrue() returns the value of the named constant value if its both defined and evaluates to TRUE; else returns a default value.

Parameters

string $str - the name of the constant whose value is to be returned if it is set.
mixed $default - default value to be returned if $str is not defined. This defaults to empty string.
Returns

the value of $str if defined, else returns a default value. Optionally check $var value is not false as well.
Code: Example call

$landef = defined('THEME_LANGUAGE') ? THEME_LANGUAGE : ""; // complex
$landef = defset('THEME_LANGUAGE'); // easy!

$landef = THEME_LANGUAGE ? THEME_LANGUAGE : ""; // buggy! If not set, PHP notice error
$landef = defset('THEME_LANGUAGE', ""); // correct, and simple

$lan = defined('THEME_LANGUAGE') ? THEME_LANGUAGE : "English"; // once more (with default)
$lan = defset('THEME_LANGUAGE', "English"); // easy!

User
Functions relating to users and user settings.

check_class()
Check whether a user belongs to a userclass Checks whether a class or class list is in a set of allowed classes

Parameters:

string or integer $var - the name or ID of the userclass to which the user should belong, or a language string. If several values, comma separated (typically "language,class").
string $userclass - A string of userclass ID's separated by commas. Defaults to that of the current user - the constant USERCLASS.
boolean $peer - Defaults to FALSE. If FALSE, checks against the predefined E107 user classes - Guest, Member, Public, Nobody, Admin, Read_Only
boolean $debug - switch debug mode on or off. Defaults to FALSE.
Return

TRUE if user is in that class list or (the given class ID Is in the list). FALSE otherwise. (Prior to 0.7.9, returns TRUE if $var is null or empty. From 0.7.9, returns FALSE if $var is null or empty; TRUE if $var is numeric zero - the 'everybody' class)
Note: This description is not yet complete - explanation for language needed

Code: Example usage

// Check that a user belongs to the userclass "Donators", and,
// if so, show gratitude.  If not, give them some encouragement!

if(check_class("Donators")){
   $text = "Thank you for donating!";
}else{
   $text = "Donate today!";
}

// Check that a user of inserted user's class ($post_info['user_class']) belongs to the userclass "Donators"
// this is mainly used in shortcodes
if(check_class('Donators', $post_info['user_class'], TRUE))
{
   $text = "Thank you for donating!";
}else{
   $text = "Donate today!";
}

get_user_data()
Get information for a user from their user ID.

Parameters:

integer $id - the ID of the user to get information for
string $extra - extra information that will be appended to the SQL, defaults to empty string.
Return

an associative array of user information, or false if user not found
User information is retrieved from the user and user_extended tables.

Code: Example usage

if ($user = get_user_data($id)) {
   $text = $user["user_name"];
}

Note: If database fields of the same names exist in both the user and the user_extended tables, the fields from the user table are discarded, and those from user_extended are retained.

r_userclass()
Generates and returns the HTML for a drop down list containing userclasses.

Parameters:

string $fieldname - the name that will be given to the <select> tag. The selected option will be submitted to the server using this name.

• integer $curval - the userclass value that is to be pre-selected in the drop down list. Defaults to 0.
• string $mode - determines if certain userclasses will be shown in the list. Defaults to 'off'. Likely to be deprecated/removed in 0.8 - the $optlist field provides more flexible functionality.
• string $optlist - A comma-delimited list which determines the userclasses to be displayed. Defaults to empty string. Selections are for the 'non-core' user classes, and various 'core' options.

Return

the HTML for a drop down list containing userclasses.
$mode can be set to anything other than off to show the admin and main userclasses in the list. Setting $mode to anything other than off or admin will show the readonly userclass. Note: setting admin, main or readonly in $optlist will cause the respective userclass to be displayed, regardless of the value of $mode. It is recommended to leave this field at its default of 'off', and use $optlist instead.

$optlist can be used to specify which classes are shown in the dropdown. All, any or none of the following can be included:

public
guest
nobody
member
readonly
admin
main - main admin
classes - shows all site defined classes

matchclass - if classes is set, this option will only show the classes that the user is a member of
language - list of languages.
Code: Example usage

// Basic dropdown with standard e107 userclasses, excluding 'admin' and 'main admin'
$ucDropDown = r_userclass('myuserclasses');

// dropdown with most standard e107 userclasses, site defined userclasses
$ucDropDown = r_userclass("userclass_editclass", $userclass_editclass, "off", "main,admin,classes,matchclass,public,nobody")

JavaScript
Functions to help enable PHP/JavaScript integration and core JavaScript functions.

js_location()
Send javascript code to the user's browser which will redirect them to another page, and cease execution of the current script.

Why bother using this? For one thing, it's smart about errors: in debug mode, if an outstanding error needs to be displayed, it will be displayed rather than doing the redirect. Saves a LOT of grief.

Parameters:

string $qry - the URL of the page to which the user will be redirected
Code: Example call

// Redirect the user to your site's base URL
js_location("SITEURL");