class CRM_Utils_System

System wide utilities.

Provides a collection of Civi utilities + access to the CMS-dependant utilities

FIXME: This is a massive and random collection that could be split into smaller services

Properties

static $_callbacks
static string $title

Methods

static mixed
__callStatic($name, $arguments)

Access methods in the appropriate CMS class

static string
makeURL(string $urlVar, bool $includeReset = FALSE, bool $includeForce = TRUE, string $path = NULL, bool|string $absolute = FALSE)

Compose a new URL string from the current URL string.

static string
getLinksUrl(string $urlVar, bool $includeReset = FALSE, bool $includeForce = TRUE, bool $skipUFVar = TRUE)

Get the query string and clean it up.

static string
theme(string $content, bool $print = FALSE, bool $maintenance = FALSE)

If we are using a theming system, invoke theme, else just print the content.

static string
makeQueryString(array|string $query)

Generate a query string if input is an array.

static string
url(string $path = NULL, array|string $query = NULL, bool $absolute = FALSE, string $fragment = NULL, bool $htmlize = TRUE, bool $frontend = FALSE, bool $forceBackend = FALSE)

Generate an internal CiviCRM URL.

static string|null
getUrlPath()

Path of the current page e.g. 'civicrm/contact/view'

static string
href(string $text, string $path = NULL, string|array $query = NULL, bool $absolute = TRUE, string $fragment = NULL, bool $htmlize = TRUE, bool $frontend = FALSE, bool $forceBackend = FALSE)

Get href.

static string
currentPath()

What menu path are we currently on. Called for the primary tpl.

static string
crmURL(array $params)

Called from a template to compose a url.

static 
setTitle(string $title, string $pageTitle = NULL)

Sets the title of the page.

static 
setUserContext(array $names, string $default = NULL)

Figures and sets the userContext.

static string
getClassName(object $object)

Gets a class name for an object.

static 
redirect(string $url = NULL, array $context = [])

Redirect to another URL.

static 
jsRedirect(string $url = NULL, string $title = NULL, string $message = NULL)

Redirect to another URL using JavaScript.

static string
baseURL()

Get the base URL of the system.

static bool
authenticateAbort(string $message, bool $abort)

Authenticate or abort.

static bool
authenticateKey(bool $abort = TRUE)

Authenticate key.

static bool
authenticateScript(bool $abort = TRUE, string $name = NULL, string $pass = NULL, bool $storeInSession = TRUE, bool $loadCMSBootstrap = TRUE, bool $requireKey = TRUE)

Authenticate script.

static false|array
authenticate(string $name, string $password, bool $loadCMSBootstrap = FALSE, string $realPath = NULL)

Authenticate the user against the uf db.

static 
setUFMessage(string $message)

Set a message in the UF to display to a user.

static bool
isNull(mixed $value)

Determine whether a value is null-ish.

static string
mungeCreditCard(string $number, int $keep = 4)

Obscure all but the last few digits of a credit card number.

static mixed
getModuleSetting(string $pModuleName, string $pSetting)

Get a setting from a loaded PHP module.

static mixed|string
memory(string $title = NULL)

Do something no-one bothered to document.

static 
download(string $name, string $mimeType, string $buffer, string $ext = NULL, bool $output = TRUE, string $disposition = 'attachment')

Download something or other.

static 
xMemory(string $title = NULL, bool $log = FALSE)

Gather and print (and possibly log) amount of used memory.

static string
fixURL(string $url)

Take a URL (or partial URL) and make it better.

static bool
validCallback(string $callback)

Make sure a callback is valid in the current context.

static string[]
explode(string $separator, string $string, int $limit)

Like PHP's built-in explode(), but always return an array of $limit items.

static mixed
checkURL(string $url, bool $addCookie = FALSE)

Check url.

static bool
checkPHPVersion(int $ver = 5, bool $abort = TRUE)

Assert that we are running on a particular PHP version.

static string
formatWikiURL(string $string, bool $encode = FALSE)

Format wiki url.

static null|string
urlEncode(string $url)

Encode url.

static string
version()

Return the running civicrm version.

static string
majorVersion()

Gives the first two parts of the version string E.g. 6.1.

static bool
isVersionFormatValid(string $version)

Determines whether a string is a valid CiviCRM version string.

static 
getAllHeaders()

Wraps or emulates PHP's getallheaders() function.

static array|false
getRequestHeaders()

Get request headers.

static 
isSSL()

Determine whether this is an SSL request.

static 
redirectToSSL(bool|FALSE $abort = FALSE)

Redirect to SSL.

static string
ipAddress(bool $strictIPV4 = TRUE)

Get logged in user's IP address.

static string
refererPath()

Get the referring / previous page URL.

static string
getDocBaseURL()

Get the documentation base URL.

static string
getWikiBaseURL()

Returns wiki (alternate) documentation URL base.

static string
docURL2(string $page, bool $URLonly = FALSE, string $text = NULL, string $title = NULL, string $style = NULL, null $resource = NULL)

Returns URL or link to documentation page, based on provided parameters.

static null|string
docURL(array $params)

Returns URL or link to documentation page, based on provided parameters.

static mixed
formatDocUrl($url)

Add language and version parameters to the doc url.

static 
civiExit(int $status = 0, array $testParameters = [])

Exit with provided exit code.

static 
flushCache()

Reset the various system caches and some important static variables.

static 
loadBootStrap(array $params = [], bool $loadUser = TRUE, bool $throwError = TRUE, string $realPath = NULL)

Load CMS bootstrap.

static mixed|string
baseCMSURL()

Get Base CMS url.

static string
relativeURL(string $url)

Given a URL, return a relative URL if possible.

static string
absoluteURL(string $url, bool $removeLanguagePart = FALSE)

Produce an absolute URL from a possibly-relative URL.

static string
cleanUrl(string $url)

Clean url, replaces first '&' with '?'.

static string
languageNegotiationURL(string $url, bool $addLanguagePart = TRUE, bool $removeLanguagePart = FALSE)

Format the url as per language Negotiation.

static 
appendTPLFile(string $fileName, string $content, string $overideFileName = NULL)

Append the contents of an 'extra' smarty template file.

static array
listIncludeFiles(string $relpath)

Get a list of all files that are found within the directories.

static array
getPluginList(string $relpath, string $fext = '.php', array $skipList = [])

Get a list of all "plugins".

static 
executeScheduledJobs()

Execute scheduled jobs.

static string|FALSE
evalUrl(string|FALSE $url)

Evaluate any tokens in a URL.

static string
getSiteID()

Returns the unique identifier for this site, as used by community messages.

static bool
isDevelopment()

Determine whether this is a developmental system.

static bool
isInUpgradeMode()

Is in upgrade mode.

static array|NULL
createDefaultCrudLink(array $crudLinkSpec)

Determine the standard URL for viewing or editing the specified link.

static 
sendResponse(ResponseInterface $response)

Return an HTTP Response with appropriate content and status code set.

static
appendBreadCrumb(array $breadCrumbs)

Append an additional breadcrumb tag to the existing breadcrumbs.

static
resetBreadCrumb()

Reset an additional breadcrumb tag to the existing breadcrumb.

static
addHTMLHead(string $bc)

Append a string to the head of the HTML file.

static
setHttpHeader(string $name, string $value)

Set http header.

static
appendCoreResources(GenericHookEvent $e)

Callback for hook_civicrm_coreResourceList.

static
alterAssetUrl(GenericHookEvent $e)

Callback for hook_civicrm_getAssetUrl.

Details

at line 74
static mixed __callStatic($name, $arguments)

Access methods in the appropriate CMS class

Parameters

$name
$arguments

Return Value

mixed

at line 99
static string makeURL(string $urlVar, bool $includeReset = FALSE, bool $includeForce = TRUE, string $path = NULL, bool|string $absolute = FALSE)

Compose a new URL string from the current URL string.

Used by all the framework components, specifically, pager, sort and qfc

Parameters

string $urlVar The url variable being considered (i.e. crmPageID, crmSortID etc).
bool $includeReset (optional) Whether to include the reset GET string (if present).
bool $includeForce (optional) Whether to include the force GET string (if present).
string $path (optional) The path to use for the new url.
bool|string $absolute (optional) Whether to return an absolute URL.

Return Value

string The URL fragment.

at line 135
static string getLinksUrl(string $urlVar, bool $includeReset = FALSE, bool $includeForce = TRUE, bool $skipUFVar = TRUE)

Get the query string and clean it up.

Strips some variables that should not be propagated, specifically variables like 'reset'. Also strips any side-affect actions (e.g. export).

This function is copied mostly verbatim from Pager.php (_getLinksUrl)

Parameters

string $urlVar The URL variable being considered (e.g. crmPageID, crmSortID etc).
bool $includeReset (optional) By default this is FALSE, meaning that the reset parameter is skipped. Set to TRUE to leave the reset parameter as-is.
bool $includeForce (optional)
bool $skipUFVar (optional)

Return Value

string

at line 214
static string theme(string $content, bool $print = FALSE, bool $maintenance = FALSE)

If we are using a theming system, invoke theme, else just print the content.

Parameters

string $content The content that will be themed.
bool $print (optional) Are we displaying to the screen or bypassing theming?
bool $maintenance (optional) For maintenance mode.

Return Value

string

at line 229
static string makeQueryString(array|string $query)

Generate a query string if input is an array.

Parameters

array|string $query

Return Value

string

at line 263
static string url(string $path = NULL, array|string $query = NULL, bool $absolute = FALSE, string $fragment = NULL, bool $htmlize = TRUE, bool $frontend = FALSE, bool $forceBackend = FALSE)

Generate an internal CiviCRM URL.

Parameters

string $path The path being linked to, such as "civicrm/add".
array|string $query A query string to append to the link, or an array of key-value pairs.
bool $absolute Whether to force the output to be an absolute link (beginning with a URI-scheme such as 'http:'). Useful for links that will be displayed outside the site, such as in an RSS feed.
string $fragment A fragment identifier (named anchor) to append to the link.
bool $htmlize Whether to encode special html characters such as &.
bool $frontend This link should be to the CMS front end (applies to WP & Joomla).
bool $forceBackend This link should be to the CMS back end (applies to WP & Joomla).

Return Value

string An HTML string containing a link to the given path.

at line 308
static string|null getUrlPath()

Path of the current page e.g. 'civicrm/contact/view'

Return Value

string|null

at line 329
static string href(string $text, string $path = NULL, string|array $query = NULL, bool $absolute = TRUE, string $fragment = NULL, bool $htmlize = TRUE, bool $frontend = FALSE, bool $forceBackend = FALSE)

Get href.

Parameters

string $text
string $path
string|array $query
bool $absolute
string $fragment
bool $htmlize
bool $frontend
bool $forceBackend

Return Value

string

at line 343
static string currentPath()

What menu path are we currently on. Called for the primary tpl.

Return Value

string the current menu path

at line 357
static string crmURL(array $params)

Called from a template to compose a url.

Parameters

array $params List of parameters.

Return Value

string url

at line 382
static setTitle(string $title, string $pageTitle = NULL)

Sets the title of the page.

Parameters

string $title Document title - plain text only
string $pageTitle Page title (if different) - may include html

at line 398
static setUserContext(array $names, string $default = NULL)

Figures and sets the userContext.

Uses the referrer if valid else uses the default.

Parameters

array $names Referrer should match any str in this array.
string $default (optional) The default userContext if no match found.

at line 427
static string getClassName(object $object)

Gets a class name for an object.

Parameters

object $object Object whose class name is needed.

Return Value

string The class name of the object.

at line 439
static redirect(string $url = NULL, array $context = [])

Redirect to another URL.

Parameters

string $url The URL to provide to the browser via the Location header.
array $context Optional additional information for the hook.

at line 478
static jsRedirect(string $url = NULL, string $title = NULL, string $message = NULL)

Redirect to another URL using JavaScript.

Use an html based file with javascript embedded to redirect to another url This prevent the too many redirect errors emitted by various browsers

Parameters

string $url (optional) The destination URL.
string $title (optional) The page title to use for the redirect page.
string $message (optional) The message to provide in the body of the redirect page.

at line 516
static string baseURL()

Get the base URL of the system.

Return Value

string

at line 529
static bool authenticateAbort(string $message, bool $abort)

Authenticate or abort.

Parameters

string $message
bool $abort

Return Value

bool

at line 547
static bool authenticateKey(bool $abort = TRUE)

Authenticate key.

Parameters

bool $abort (optional) Whether to exit; defaults to true.

Return Value

bool

at line 598
static bool authenticateScript(bool $abort = TRUE, string $name = NULL, string $pass = NULL, bool $storeInSession = TRUE, bool $loadCMSBootstrap = TRUE, bool $requireKey = TRUE)

Authenticate script.

Parameters

bool $abort
string $name
string $pass
bool $storeInSession
bool $loadCMSBootstrap
bool $requireKey

Return Value

bool

at line 659
static false|array authenticate(string $name, string $password, bool $loadCMSBootstrap = FALSE, string $realPath = NULL)

Authenticate the user against the uf db.

In case of successful authentication, returns an array consisting of (contactID, ufID, unique string). Returns FALSE if authentication is unsuccessful.

Parameters

string $name The username.
string $password The password.
bool $loadCMSBootstrap
string $realPath

Return Value

false|array

at line 686
static setUFMessage(string $message)

Set a message in the UF to display to a user.

Parameters

string $message The message to set.

at line 699
static bool isNull(mixed $value)

Determine whether a value is null-ish.

Parameters

mixed $value The value to check for null.

Return Value

bool

at line 727
static string mungeCreditCard(string $number, int $keep = 4)

Obscure all but the last few digits of a credit card number.

Parameters

string $number The credit card number to obscure.
int $keep (optional) The number of digits to preserve unmodified.

Return Value

string The obscured credit card number.

at line 782
static mixed getModuleSetting(string $pModuleName, string $pSetting)

Get a setting from a loaded PHP module.

Parameters

string $pModuleName
string $pSetting

Return Value

mixed

at line 795
static mixed|string memory(string $title = NULL)

Do something no-one bothered to document.

Parameters

string $title (optional)

Return Value

mixed|string

at line 819
static download(string $name, string $mimeType, string $buffer, string $ext = NULL, bool $output = TRUE, string $disposition = 'attachment')

Download something or other.

Parameters

string $name
string $mimeType
string $buffer
string $ext
bool $output
string $disposition

at line 861
static xMemory(string $title = NULL, bool $log = FALSE)

Gather and print (and possibly log) amount of used memory.

Parameters

string $title
bool $log (optional) Whether to log the memory usage information.

at line 887
static string fixURL(string $url)

Take a URL (or partial URL) and make it better.

Currently, URLs pass straight through unchanged unless they are "seriously malformed" (see http://us2.php.net/parse_url).

Parameters

string $url The URL to operate on.

Return Value

string The fixed URL.

at line 907
static bool validCallback(string $callback)

Make sure a callback is valid in the current context.

Parameters

string $callback Name of the function to check.

Return Value

bool

at line 952
static string[] explode(string $separator, string $string, int $limit)

Like PHP's built-in explode(), but always return an array of $limit items.

This serves as a wrapper to the PHP explode() function. In the event that PHP's explode() returns an array with fewer than $limit elements, pad the end of the array with NULLs.

Parameters

string $separator
string $string
int $limit

Return Value

string[]

at line 970
static mixed checkURL(string $url, bool $addCookie = FALSE)

Check url.

Parameters

string $url The URL to check.
bool $addCookie (optional)

Return Value

mixed

at line 1000
static bool checkPHPVersion(int $ver = 5, bool $abort = TRUE)

Assert that we are running on a particular PHP version.

Parameters

int $ver The major version of PHP that is required.
bool $abort (optional) Whether to fatally abort if the version requirement is not met. Defaults to TRUE.

Return Value

bool Returns TRUE if the requirement is met, FALSE if the requirement is not met and we're not aborting due to the failed requirement. If $abort is TRUE and the requirement fails, this function does not return.

at line 1022
static string formatWikiURL(string $string, bool $encode = FALSE)

Format wiki url.

Parameters

string $string
bool $encode

Return Value

string

at line 1043
static null|string urlEncode(string $url)

Encode url.

Parameters

string $url

Return Value

null|string

at line 1079
static string version()

Return the running civicrm version.

Return Value

string civicrm version

at line 1106
static string majorVersion()

Gives the first two parts of the version string E.g. 6.1.

Return Value

string

at line 1119
static bool isVersionFormatValid(string $version)

Determines whether a string is a valid CiviCRM version string.

Parameters

string $version Version string to be checked.

Return Value

bool

at line 1126
static getAllHeaders()

Wraps or emulates PHP's getallheaders() function.

at line 1154
static array|false getRequestHeaders()

Get request headers.

Return Value

array|false

at line 1169
static isSSL()

Determine whether this is an SSL request.

Note that we inline this function in install/civicrm.php, so if you change this function, please go and change the code in the install script as well.

at line 1182
static redirectToSSL(bool|FALSE $abort = FALSE)

Redirect to SSL.

Parameters

bool|FALSE $abort

Exceptions

Exception

at line 1222
static string ipAddress(bool $strictIPV4 = TRUE)

Get logged in user's IP address.

Get IP address from HTTP REMOTE_ADDR header. If the CMS is Drupal then use the Drupal function as this also handles reverse proxies (based on proper configuration in settings.php)

Parameters

bool $strictIPV4 (optional) Whether to return only IPv4 addresses.

Return Value

string IP address of logged in user.

at line 1255
static string refererPath()

Get the referring / previous page URL.

Return Value

string The previous page URL

at line 1265
static string getDocBaseURL()

Get the documentation base URL.

Return Value

string Base URL of the CRM documentation.

at line 1276
static string getWikiBaseURL()

Returns wiki (alternate) documentation URL base.

Return Value

string documentation url

at line 1304
static string docURL2(string $page, bool $URLonly = FALSE, string $text = NULL, string $title = NULL, string $style = NULL, null $resource = NULL)

Returns URL or link to documentation page, based on provided parameters.

For use in PHP code. WARNING: Always returns URL, if ts function is not defined ($URLonly has no effect).

Parameters

string $page Title of documentation wiki page.
bool $URLonly (optional) Whether to return URL only or full HTML link (default).
string $text (optional) Text of HTML link (no effect if $URLonly = false).
string $title (optional) Tooltip text for HTML link (no effect if $URLonly = false)
string $style (optional) Style attribute value for HTML link (no effect if $URLonly = false)
null $resource

Return Value

string URL or link to documentation page, based on provided parameters.

at line 1341
static null|string docURL(array $params)

Returns URL or link to documentation page, based on provided parameters.

For use in templates code.

Parameters

array $params An array of parameters (see CRM_Utils_System::docURL2 method for names)

Return Value

null|string URL or link to documentation page, based on provided parameters.

at line 1388
static mixed formatDocUrl($url)

Add language and version parameters to the doc url.

Note that this function may run before CiviCRM is initialized and so should not call ts() or perform any db lookups.

Parameters

$url

Return Value

mixed

at line 1400
static civiExit(int $status = 0, array $testParameters = [])

Exit with provided exit code.

Parameters

int $status (optional) Code with which to exit.
array $testParameters

at line 1425
static flushCache()

Reset the various system caches and some important static variables.

at line 1480
static loadBootStrap(array $params = [], bool $loadUser = TRUE, bool $throwError = TRUE, string $realPath = NULL)

Load CMS bootstrap.

Parameters

array $params Array with uid name and pass
bool $loadUser Boolean load user or not.
bool $throwError
string $realPath

at line 1497
static mixed|string baseCMSURL()

Get Base CMS url.

Return Value

mixed|string

at line 1545
static string relativeURL(string $url)

Given a URL, return a relative URL if possible.

Parameters

string $url

Return Value

string

at line 1572
static string absoluteURL(string $url, bool $removeLanguagePart = FALSE)

Produce an absolute URL from a possibly-relative URL.

Parameters

string $url
bool $removeLanguagePart

Return Value

string

at line 1598
static string cleanUrl(string $url)

Clean url, replaces first '&' with '?'.

Parameters

string $url

Return Value

string , clean url

at line 1621
static string languageNegotiationURL(string $url, bool $addLanguagePart = TRUE, bool $removeLanguagePart = FALSE)

Format the url as per language Negotiation.

Parameters

string $url
bool $addLanguagePart
bool $removeLanguagePart

Return Value

string , formatted url.

at line 1643
static appendTPLFile(string $fileName, string $content, string $overideFileName = NULL)

Append the contents of an 'extra' smarty template file.

It must be present in the custom template directory. This does not work if there are multiple custom template directories

Parameters

string $fileName The name of the tpl file that we are processing.
string $content The current content string. May be modified by this function.
string $overideFileName (optional) Sent by contribution/event reg/profile pages which uses a id specific extra file name if present.

at line 1678
static array listIncludeFiles(string $relpath)

Get a list of all files that are found within the directories.

Files must be the result of appending the provided relative path to each component of the PHP include path.

Parameters

string $relpath A relative path, typically pointing to a directory with multiple class files.

Return Value

array An array of files that exist in one or more of the directories that are referenced by the relative path when appended to each element of the PHP include path.

at line 1717
static array getPluginList(string $relpath, string $fext = '.php', array $skipList = [])

Get a list of all "plugins".

(PHP classes that implement a piece of functionality using a well-defined interface) that are found in a particular CiviCRM directory (both custom and core are searched).

Parameters

string $relpath A relative path referencing a directory that contains one or more plugins.
string $fext (optional) Only files with this extension will be considered to be plugins.
array $skipList (optional) List of files to skip.

Return Value

array List of plugins, where the plugin name is both the key and the value of each element.

at line 1735
static executeScheduledJobs()

Execute scheduled jobs.

at line 1755
static string|FALSE evalUrl(string|FALSE $url)

Evaluate any tokens in a URL.

Parameters

string|FALSE $url

Return Value

string|FALSE

at line 1781
static string getSiteID()

Returns the unique identifier for this site, as used by community messages.

SiteID will be generated if it is not already stored in the settings table.

Return Value

string

at line 1796
static bool isDevelopment()

Determine whether this is a developmental system.

Return Value

bool

at line 1810
static bool isInUpgradeMode()

Is in upgrade mode.

Return Value

bool

Determine the standard URL for viewing or editing the specified link.

This function delegates the decision-making to (a) the hook system and (b) the BAO system.

Parameters

array $crudLinkSpec With keys:. - action: int, CRM_Core_Action::UPDATE or CRM_Core_Action::VIEW [default: VIEW] - entity_table: string, eg "civicrm_contact" - entity_id: int

Return Value

array|NULL NULL if unavailable, or an array. array has keys: - path: string - query: array - title: string - url: string

at line 1878
static sendResponse(ResponseInterface $response)

Return an HTTP Response with appropriate content and status code set.

Parameters

ResponseInterface $response

at line 57
static appendBreadCrumb(array $breadCrumbs)

Append an additional breadcrumb tag to the existing breadcrumbs.

Parameters

array $breadCrumbs

Return Value

static

at line 57
static resetBreadCrumb()

Reset an additional breadcrumb tag to the existing breadcrumb.

Return Value

static

at line 57
static addHTMLHead(string $bc)

Append a string to the head of the HTML file.

Parameters

string $bc

Return Value

static

at line 57
static setHttpHeader(string $name, string $value)

Set http header.

Parameters

string $name
string $value

Return Value

static

at line 57
static appendCoreResources(GenericHookEvent $e)

Callback for hook_civicrm_coreResourceList.

Parameters

GenericHookEvent $e

Return Value

static

at line 57
static alterAssetUrl(GenericHookEvent $e)

Callback for hook_civicrm_getAssetUrl.

Parameters

GenericHookEvent $e

Return Value

static