NAV
php sql

Introduction

Welcome the UserSpice Documentation! Below, you will see information broken down into several categories, including classes, functions, and features.

On the left, you will be able to navigation specific categories and their topics, including search, and on the right you will see both PHP and SQL code snippets.

Here are a few notes regarding the formatting of the documentation:

  1. Parameters are ordered in the format they can be supplied
  2. If you wish to skip a parameter, you should supply the default value
  3. If the Default Value column is empty - it is required
  4. Functions are contained in Helper files in users/helpers - the corresponding helper file is included at the bottom of the function in the docs
  5. Functions are case sensitive in PHP
  6. If the version a function was added in is not included, assume it was added in UserSpice 5.1.6 (this is when the documentation was written)

If you have any recommendations or requests for the documents, we encourage you to make a pull request on GitHub.

Thank you.

Classes

Functions

All functions included below can be overwritten in any of your custom files that are loaded before the helpers by using the function name. Although discouraged, if you require to overwrite our default behavior, you are permitted to do so.

userIdExists

$userCheck = userIdExists(1);

if($userCheck) {
  echo "ID 1 exists";
} else {
  echo "ID 1 does NOT exists";
}

Check if the provided User ID exists in the users table

Parameters

Parameter Type Default Value Description
id int The ID of the user to verify

Expected Return

Result Type Sample
Success boolean true
Error boolean false

Helper: users

fetchAllUsers

$orderBy = 'lname DESC, fname'; //orders by lname desc, fname
$desc = true; //forces last orderBy param to be desc as well, if no order by is passed, this doesnt do anything
$disabled = false; //removes users who are disabled, DB column permissions
$users = fetchAllUsers($orderBy, $desc, $disabled);

foreach($users as $u) {
  dump($u);
}

Fetches an object of users based on the parameters included

Parameters

Parameter Type Default Value Description
orderBy string null Comma seperated params of order by clause to send to the database
desc boolean false An optional value to order the orderBy in a descending fashion
disabled boolean true Pass false to remove disabled users from the return

Expected Return

Result Type Sample
Success Object Collection of User Object
Error Object Empty

Helper: users

fetchUserDetails

//Good Result:
$id = 1;
$fetchedUser = fetchUserDetails(NULL, NULL, $id); //Returns object

$username = 'admin';
$fetchedUser = fetchUserDetails($username); //Returns object

//Bad Result:
$id = 'admin';
$fetchedUser = fetchUserDetails(NULL, NULL, $id); //Returns null

Fetches an object of a user based on the parameters included

Parameters

Parameter Type Default Value Description
username string null Username for lookup
token string null Deprecated feature
id int null User ID for lookup

Expected Return

Result Type Sample
Success Object User Object
Error null

Helper: users

deleteUsers

//Good Result:
$users = [1,2,3];
$deleteUsers = deleteUsers($users); // returns 3 - number of looped users - may not be the actual number deleted

//Bad Result:
$users = ['username'];
$deleteUsers = deleteUsers($users); // returns 0 as "username" cannot be converted to an int

Delete user(s) by ID

Parameters

Parameter Type Default Value Description
users array [] IDs of users in an array

Expected Return

Result Type Sample
Success int Number of users deleted
Error int Number of users deleted

Helper: users

echouser

//Good Result:
echouser(1); //echos info from User ID 1 based on Setting in ACP
echouser(1, 3); //echos Username (FName) from User ID 1

//Bad Result:
echouser('admin'); //echos "Unknown" as not a valid User ID

Echo a user directly in your code as defined in the Setting in your Admin Panel. An optional parameter can be passed to override the type.

Parameters

Parameter Type Default Value Description
id int The ID of the user to return
echoType int null An in-line setting override as described below

echoType

ID Sample
0 FName Lname
1 Username
2 Username (FName LName)
3 Username (FName)
4 FName First Inital of LName

Helper: users

echousername

//Good Result:
$username = echousername(1); //returns username from User ID 1

//Bad Result:
$username = echousername('admin'); //returns "Unknown" as not a valid User ID

Returns the username of a user by ID

Parameters

Parameter Type Default Value Description
id int The ID of the user to return

Expected Return

Result Type Sample
Success string
Error string Unknown

Helper: users

updateUser

//Good Result:
$column = 'fname';
$id = 1;
$value = 'Doe';
$updateUser = updateUser($column, $id, $value); //returns DB result object

$column = 'fname';
$id = 1;
$value = 1;
$updateUser = updateUser($column, $id, $value); //returns DB result object

//Bad Result:
$column = 'fname';
$id = 'jdoe';
$value = 'Doe';
$updateUser = updateUser($column, $id, $value); //returns null, failed as id is not int

Update an attribute of a specific user by ID

Parameters

Parameter Type Default Value Description
column string The name of the column to update
id int The ID of the user to update
value string The value to set the column to for the user ID

Expected Return

Result Type Sample
Success Object Database Result Object
Error null

Helper: users

fetchUserName

//Good Result:
$id = 1;
$fetchedUser = fetchUserName(NULL, NULL, $id); //Returns string of fname and lname

$username = 'admin';
$fetchedUser = fetchUserName($username); //Returns string of fname and lname

//Bad Result:
$id = 'admin';
$fetchedUser = fetchUserName(NULL, NULL, $id); //Returns null

$username = 'abc123'; //bad username (this user shouldnt exist)
$fetchedUser = fetchUserName($username); //Returns "Unknown"

Fetches a concatenation of the FName and LName from the Users Table for the specified user.

Parameters

Parameter Type Default Value Description
username string null Username for lookup
token string null Deprecated feature
id int null User ID for lookup

Expected Return

Result Type Sample
Success String
Error null Invalid query structure, could be a violated parameter type
Error string A string value of Unknown means no user was found

Helper: users

isAdmin

$isAdmin = isAdmin();

if($isAdmin) {
  echo 'Is Admin';
} else {
  echo 'Is NOT Admin';
}

Checks if the current user is:

hasPerm for this function is tested against the default Administrator Permission Level (ID #2)

Expected Return

Result Type Sample
Success boolean true
Error boolean false

Helper: users

name_from_id

//Good Result:
$username = name_from_id(1); //returns username from User ID 1

//Bad Result:
$username = name_from_id('admin'); //returns "-" as not a valid User ID

Returns the username of a user by ID with the first character capitalized

Parameters

Parameter Type Default Value Description
id int The ID of the user to return

Expected Return

Result Type Sample
Success string
Error string -

Helper: users

ipCheck

Helper: us_helpers

Parameters: None

ipCheckBan

Helper: us_helpers

Parameters: None

randomstring

Helper: us_helpers

Parameters: $len

get_gravatar

Helper: us_helpers

Parameters: $email, $s = 120, $d = 'mm', $r = 'pg', $img = false, $atts = array(

fetchGroupsByMenu

Helper: us_helpers

Parameters: $menu_id

updateGroupsMenus

Helper: us_helpers

Parameters: $group_ids, $menu_ids

addGroupsMenus

Helper: us_helpers

Parameters: $group_ids, $menu_ids

usernameExists

Helper: us_helpers

Parameters: $username

getPageFiles

Helper: us_helpers

Parameters: None

getUSPageFiles

Helper: us_helpers

Parameters: None

sanitizedDest

Helper: us_helpers

Parameters: $varname='dest'

resultBlock

Helper: us_helpers

Parameters: $errors,$successes

lang

Helper: us_helpers

Parameters: $key,$markers = NULL

isValidEmail

Helper: us_helpers

Parameters: $email

emailExists

Helper: us_helpers

Parameters: $email

updateEmail

Helper: us_helpers

Parameters: $id, $email

echoId

Helper: us_helpers

Parameters: $id,$table,$column

bin

Helper: us_helpers

Parameters: $number

generateForm

Helper: us_helpers

Parameters: $table,$id, $skip=[]

generateAddForm

Helper: us_helpers

Parameters: $table, $skip=[]

updateFields2

Helper: us_helpers

Parameters: $post, $skip=[]

mqtt

Helper: us_helpers

Parameters: $id,$topic,$message

clean

Helper: us_helpers

Parameters: $string

stripPagePermissions

Helper: us_helpers

Parameters: $id

encodeURIComponent

Helper: us_helpers

Parameters: $str

logger

Helper: us_helpers

Parameters: $user_id,$logtype,$lognote

echodatetime

Helper: us_helpers

Parameters: $ts

time2str

Helper: us_helpers

Parameters: $ts

ipReason

Helper: us_helpers

Parameters: $reason

checkBan

Helper: us_helpers

Parameters: $ip

random_password

Helper: us_helpers

Parameters: $length = 16

returnError

Helper: us_helpers

Parameters: $errorMsg

userHasPermission

Helper: us_helpers

Parameters: $userID,$permissionID

requestCheck

Helper: us_helpers

Parameters: $expectedAr

adminNotifications

Helper: us_helpers

Parameters: $type,$threads,$user_id

lognote

Helper: us_helpers

Parameters: $logid

isLocalhost

Helper: us_helpers

Parameters: None

currentPageStrict

Helper: us_helpers

Parameters: None

UserSessionCount

Helper: us_helpers

Parameters: None

fetchUserSessions

Helper: us_helpers

Parameters: $all=false

fetchAdminSessions

Helper: us_helpers

Parameters: $all=false

killSessions

Helper: us_helpers

Parameters: $sessions,$admin=false

passwordResetKillSessions

Helper: us_helpers

Parameters: $uid=NULL

username_helper

Helper: us_helpers

Parameters: $fname,$lname,$email

oxfordList

Helper: us_helpers

Parameters: $data,$opts=[]

currentFile

Helper: us_helpers

Parameters: None

importSQL

Helper: us_helpers

Parameters: $file

pluginActive

Helper: us_helpers

Parameters: $plugin,$checkOnly = false

languageSwitcher

Helper: us_helpers

Parameters: None

getMyHooks

Helper: us_helpers

Parameters: $opts = []

includeHook

Helper: us_helpers

Parameters: $hooks,$position

registerHooks

Helper: us_helpers

Parameters: $hooks,$plugin_name

deRegisterHooks

Helper: us_helpers

Parameters: $plugin_name

shakerIsInstalled

Helper: us_helpers

Parameters: $type,$reserved

updateReAuth

Helper: us_helpers

Parameters: $id, $re_auth

reAuth

Helper: us_helpers

Parameters: None

verifyadmin

Helper: us_helpers

Parameters: $page

isJson

The isJson function attempts to decode a string and returns if it was successful or failed.

Parameters

Parameter Type Default Value Description
string string The string you want validation on

Expected Returned

Result Type Sample
Success boolean true
Error boolean false

Helper: us_helpers Version: 5.1.7

size

The size function uses PHP native filesize function to determine the size of a file and return it in a readable format. It will return units in the size of B, KB, MB, and GB.

Parameters

Parameter Type Default Value Description
path string Path to the file based on PHP's filesize requirements

Expected Returned

Result Type Sample
Success string
Error int 0

Helper: helpers

sanitize

The sanitize function uses PHP's native htmlentities function to sanitize a string. It is sanitized with the flag ENT_QUOTES and encoded in UTF-8. This function will return the sanitized string.

Parameters

Parameter Type Default Value Description
string string The string to be sanitized

Expected Returned

Result Type Sample
Success string

Helper: helpers

currentPage

The currentPage function will return the current file name without the URL.

Example: If you are visiting https://example.com/test.php it would return test.php

Parameters

None

Expected Returned

Result Type Sample
Success string

Helper: helpers

currentFolder

The currentFolder function will return the current folder name without the URL or file.

Example: If you are visiting https://example.com/test/index.php it would return test

Parameters

None

Expected Returned

Result Type Sample
Success string

Helper: helpers

format_date

The format_date function takes a plain text timestamp and returns it in this format using DateTime: m/d/y ~ h:iA

Parameters

Parameter Type Default Value Description
date string The datetime stamp (expected format: Y-m-d H:i:s) to be converted into a DateTime format
tz string The timezone to configure with DateTime

Expected Returned

Result Type Sample
Success DateTime
Error

Helper: helpers

abrev_date

The abrev_date function will take a plain text timestamp and return it using DateTime in this format: M d, Y

Parameters

Parameter Type Default Value Description
date string The datetime stamp (expected format: Y-m-d H:i:s) to be converted into a DateTime format
tz string The timezone to configure with DateTime

Expected Returned

Result Type Sample
Success DateTime
Error

Helper: helpers

money

They money function will take a raw string that can be converted into decimal or int value and convert it into a formatted money string, prefixed with $ and rounded to 2 decimal places.

Parameters

Parameter Type Default Value Description
ugly string The raw value that can be converted into an int or decimal value

Expected Returned

Result Type Sample
Success string $0.00
Error

Helper: helpers

display_errors

The display_errors function is used in conjunction with the validation class to take an array of strings and produce a error block HTML to be used on your page. This will be in an unordered list with two classes, bg-danger and dangerblock. It will also attach a has-error class to the closest div in the parent.

Parameters

Parameter Type Default Value Description
errors array [] The array of errors

Expected Returned

Result Type Sample
Success string Raw HTML that can be used on your page

Helper: helpers

display_successes

The display_successes function is used in conjunction with the validation class to take an array of strings and produce a success block HTML to be used on your page. This will be in an unordered list with no classes.

Parameters

Parameter Type Default Value Description
errors array [] The array of errors

Expected Returned

Result Type Sample
Success string Raw HTML that can be used on your page

Helper: helpers

email

The email function uses UserSpice's built in PHP Mailer to send an email using the options you have set in your Email Settings in the Dashboard.

Parameters

Parameter Type Default Value Description
to string The recipients email address
subject string The subject of your email
body string The body of your email
opts array [] Any additional options you wish to send to the mailer, currently, the supported keys are email (from email) and name (from name)
attachment file The file you wish to attach

Expected Returned

Result Type Sample
Success Object PHP Mailer Object
Error Object PHP Mailer Object

Helper: helpers

email_body

The email_body function is used in conjunction with the email function to generate a body from the users and usersc view folders. The template is passed along with options to customize the data in the template.

Parameters

Parameter Type Default Value Description
template string The template name (only - do not include the extension) that you wish to send
options array [] The options you wish to pass into the template

Expected Returned

Result Type Sample
Success Raw Data ob_get_clean
Error Raw Data ob_get_clean

Helper: helpers

dump

The dump function is a pre-formatted echo of var_dump with several custom options allowing you to use it for development and administrative only purposes.

Parameters

Parameter Type Default Value Description
var mixed Any data you wish to var_dump
adminOnly boolean false If you wish to only show the dump to users who pass an isAdmin check
localhostOnly boolean false If you wish to only show the dump when a pass is obtained during an isLocalhost check

Helper: helpers

dnd

The dnd function is pointed at the dump function. After the dump is completed, a die is triggered. Parameters are the same as dump.

Helper: helpers

bold

The bold function will echo the supplied text in a:

Parameters

Parameter Type Default Value Description
text string The string you wish to output

Helper: helpers

err

The err function will echo the supplied text in a:

Parameters

Parameter Type Default Value Description
text string The string you wish to output

Helper: helpers

redirect

The redirect function does a simple header redirect to the URL provided. This provides no sanitization or validation and should not be mistaken with the Redirect::to Method

Parameters

Parameter Type Default Value Description
location string The URL you wish to redirect to

Helper: helpers

write_php_ini

Helper: helpers

Parameters: $array, $file

safefilerewrite

Helper: helpers

Parameters: $fileName, $dataToSave

permissionIdExists

Helper: permissions

Parameters: $id

fetchPermissionDetails

Helper: permissions

Parameters: $id

updatePermissionName

Helper: permissions

Parameters: $id, $name

fetchUserPermissions

Helper: permissions

Parameters: $user_id

fetchPermissionUsers

Helper: permissions

Parameters: $permission_id

removePermission

Helper: permissions

Parameters: $permissions, $members

getPathPhpFiles

Helper: permissions

Parameters: $absRoot,$urlRoot,$fullPath

deletePages

Helper: permissions

Parameters: $pages

fetchAllPages

Helper: permissions

Parameters: None

fetchPageDetails

Helper: permissions

Parameters: $id

pageIdExists

Helper: permissions

Parameters: $id

updatePrivate

Helper: permissions

Parameters: $id, $private

createPages

Helper: permissions

Parameters: $pages

addPage

Helper: permissions

Parameters: $page, $permission

securePage

Helper: permissions

Parameters: $uri

fetchPagePermissions

Helper: permissions

Parameters: $page_id

fetchPermissionPages

Helper: permissions

Parameters: $permission_id

removePage

Helper: permissions

Parameters: $pages, $permissions

checkMenu

Helper: permissions

Parameters: $permission, $id = 0

fetchAllPermissions

Helper: permissions

Parameters: None

checkPermission

Helper: permissions

Parameters: $permission

permissionNameExists

Helper: permissions

Parameters: $permission

addPermission

Helper: permissions

Parameters: $permission_ids, $members

deletePermission

Helper: permissions

Parameters: $permission

hasPerm

Helper: permissions

Parameters: $permissions, $id=null

echopage

Helper: permissions

Parameters: $id

getIP

$ip = getIP();

Attempts to retrieve the users IP address. In the event a user is behind a proxy server, this will return the IP based on the following header values. These are retrieved using the get_env function and may not be returned if PHP is running as an ISAPI module.

Expected Return

Result Type Sample
IP String

Helper: audit

fetchUserjsonPIE

$pie = fetchUserjsonPIE();

Returns data for a Pie Chart for Page Permission Counts.

Expected Return

Result Type Sample
Data Unknown

Helper: audit

fetchUserjsonLG2

$loginsBar = fetchUserjsonLG2();

Returns data for a Bar Chart for Login Counts.

Expected Return

Result Type Sample
Data Unknown

Helper: audit

fetchUserjsonLG

$signupCounts = fetchUserjsonLG();

Returns data for a Bar Chart for Signup Counts.

Expected Return

Result Type Sample
Data Unknown

Helper: audit

fetchAllLatest

$auditData = fetchAllLatest($userid, $start, $end, $eventcode);

Retrieves data for Audit Functions

Parameters

Parameter Type Default Value Description
id int User ID for lookup
start datetime
end datetime
eventcode string audit.audit_eventcode

Expected Return

Result Type Sample
Data Unknown

Helper: audit

countStuff

$count = countStuff($query);

This function will count the number of rows for the query.

Parameters

Parameter Type Default Value Description
what string Expected to send raw SQL parameters after FROM

Expected Return

Result Type Sample
Data Unknown

Helper: audit

countLoginsSince

This function will use the audit table to count the number of events since a date based on an eventcode supplied. The audit system isn't heavily maintained, please do not consider this system reliable.

Parameters

Parameter Type Default Value Description
eventcode string
since datetime

Expected Return

Result Type Sample
Count int

Helper: audit

ago

Return a string to how long ago the supplied timestamp occured. A better function to use is time2str.

Parameters

Parameter Type Default Value Description
time datetime

Expected Return

Result Type Sample
Timestamp string

Helper: audit

fetchAllAudit

Helper: audit

Parameters: None

fetchUserAudit

Helper: audit

Parameters: $userid

writeAudit

Helper: audit

Parameters: $userid,$userip,$othus,$event,$action,$itemid=0

csv_to_array

Helper: backup_util

Parameters: $filename='', $delimiter=','

recurse_copy

Helper: backup_util

Parameters: $src,$dst

zipData

Helper: backup_util

Parameters: $source, $destination

rrmdir

Helper: backup_util

Parameters: $src

delete_dir

Helper: backup_util

Parameters: $dir

backupObjects

Helper: backup_util

Parameters: $backupItems,$backupPath

backupZip

Helper: backup_util

Parameters: $backupPath,$delBackupPath=false

backupUsTables

Helper: backup_util

Parameters: $backupPath

backupUsTable

Helper: backup_util

Parameters: $backupPath

extractZip

Helper: backup_util

Parameters: $restoreFile,$restoreDest

importSqlFile

Helper: backup_util

Parameters: $sqlFile

fetchGroupsByMenu

Helper: dbmenu

Parameters: $menu_id

updateGroupsMenus

Helper: dbmenu

Parameters: $group_ids, $menu_ids

addGroupsMenus

Helper: dbmenu

Parameters: $group_ids, $menu_ids

_assert

Helper: menus

Parameters: $expr, $msg

prepareMenuTree

Helper: menus

Parameters: $menuResults

prepareIndentedMenuTree

Helper: menus

Parameters: $menuResults

prepareDropdownString

Helper: menus

Parameters: $menuItem,$user_id

prepareItemString

Helper: menus

Parameters: $menuItem,$user_id

output_message

Helper: deprecated

Parameters: $message

inputBlock

Helper: deprecated

Parameters: $type,$label,$id,$divAttr=array(

currentPageId

Helper: deprecated

Parameters: $uri

getUSPageFiles

Helper: deprecated

Parameters: None

getPageFiles

Helper: deprecated

Parameters: None

permissionNameExists

Helper: deprecated

Parameters: $permission

stripPagePermissions

Helper: deprecated

Parameters: $id

userHasPermission

Helper: deprecated

Parameters: $userID,$permissionID

usernameExists

Helper: deprecated

Parameters: $username

emailExists

Helper: deprecated

Parameters: $email

updateEmail

Helper: deprecated

Parameters: $id, $email

echoId

Helper: deprecated

Parameters: $id,$table,$column

Features

php sql