/functions/global.php

Description

global.php

This includes code to update < 4.1.0 globals to the newer format It also has some session register functions that work across various php versions.

Constants
SQ_COOKIE = 4 (line 26)
SQ_FORM = 6 (line 28)
SQ_GET = 1 (line 23)
SQ_INORDER = 0 (line 22)

These constants are used in the function sqgetGlobalVar(). See sqgetGlobalVar() for a description of what they mean.

  • since: 1.4.0
SQ_POST = 2 (line 24)
SQ_SERVER = 5 (line 27)
SQ_SESSION = 3 (line 25)
Functions
check_php_version (line 40)

returns true if current php version is at mimimum a.b.c

Called: check_php_version(4,1)

bool check_php_version ([int $a = '0'], [int $b = '0'], [int $c = '0'])
  • int $a: a major version number
  • int $b: b minor version number
  • int $c: c release number
check_sm_version (line 56)

returns true if the current internal SM version is at minimum a.b.c These are plain integer comparisons, as our internal version is constructed by us, as an array of 3 ints.

Called: check_sm_version(1,3,3)

bool check_sm_version ([int $a = 0], [int $b = 0], [int $c = 0])
  • int $a: a major version number
  • int $b: b minor version number
  • int $c: c release number
get_process_owner_info (line 893)

Endeavor to detect what user and group PHP is currently running as. Probably only works in non-Windows environments.

  • return: Boolean FALSE is returned if something went wrong, otherwise an array is returned with the following elements: uid The current process' UID (integer) euid The current process' effective UID (integer) gid The current process' GID (integer) egid The current process' effective GID (integer) name The current process' name/handle (string) ename The current process' effective name/handle (string) group The current process' group name (string) egroup The current process' effective group name (string) Note that some of these elements may have empty values, especially if they could not be determined.
  • since: 1.5.2
mixed get_process_owner_info ()
get_secured_config_value (line 428)

Get an immutable copy of a configuration variable if SquirrelMail

is in "secured configuration" mode. This guarantees the caller gets a copy of the requested value as it is set in the main application configuration (including config_local overrides), and not what it might be after possibly having been modified by some other code (usually a plugin overriding configuration values for one reason or another).

WARNING: Please use this function as little as possible, because every time it is called, it forcibly reloads the main configuration file(s).

Caller beware that this function will do nothing if SquirrelMail is not in "secured configuration" mode per the $secured_config setting.

  • return: The desired value
  • since: 1.5.2
mixed get_secured_config_value (string $var_name)
  • string $var_name: The name of the desired variable
is_ssl_secured_connection (line 852)

Detect whether or not we have a SSL secured (HTTPS) connection connection to the browser

It is thought to be so if you have 'SSLOptions +StdEnvVars' in your Apache configuration, OR if you have HTTPS set to a non-empty value (except "off") in your HTTP_SERVER_VARS, OR if you have HTTP_X_FORWARDED_PROTO=https in your HTTP_SERVER_VARS, OR if you are on port 443.

Note: HTTP_X_FORWARDED_PROTO could be sent from the client and therefore possibly spoofed/hackable. Thus, SquirrelMail ignores such headers by default. The administrator can tell SM to use such header values by setting $sq_ignore_http_x_forwarded_headers to boolean FALSE in config/config.php or by using config/conf.pl.

Note: It is possible to run SSL on a port other than 443, and if that is the case, the administrator should set $sq_https_port in config/config.php or by using config/conf.pl.

  • return: TRUE if the current connection is SSL-encrypted; FALSE otherwise.
  • since: 1.4.17 and 1.5.2
boolean is_ssl_secured_connection ()
php_combined_lcg (line 635)

session_regenerate_id replacement for PHP < 4.3.2

This code is borrowed from Gallery, session.php version 1.53.2.1

void php_combined_lcg ()
php_self (line 685)

php_self

Attempts to determine the path and filename and any arguments for the currently executing script. This is usually found in $_SERVER['REQUEST_URI'], but some environments may differ, so this function tries to standardize this value.

Note that before SquirrelMail version 1.5.1, this function was stored in function/strings.php.

  • return: The path, filename and any arguments for the current script
  • since: 1.2.3
string php_self ()
session_regenerate_id (line 656)
void session_regenerate_id ()
sm_print_r (line 739)

Print variable

sm_print_r($some_variable, [$some_other_variable [, ...]]);

Debugging function - does the same as print_r, but makes sure special characters are converted to htmlentities first. This will allow values like <some@email.address> to be displayed. The output is wrapped in <pre> and </pre> tags. Since 1.4.2 accepts unlimited number of arguments.

  • since: 1.4.1
void sm_print_r ()
sqgetGlobalVar (line 299)

Search for the variable $name in one or more of the global variables $_SESSION, $_POST, $_GET, $_COOKIE, and $_SERVER, and set the value of it in the variable $vaule.

$search must be one of the defined constants below. The default is SQ_INORDER. Both SQ_INORDER and SQ_FORM stops on the first match.

SQ_INORDER searches $_SESSION, then $_POST, and then $_GET. SQ_FORM searches $_POST and then $_GET. SQ_COOKIE searches $_COOKIE only. SQ_GET searches $_GET only. SQ_POST searches $_POST only. SQ_SERVER searches $_SERVER only. SQ_SESSION searches $_SESSION only.

Example: sqgetGlobalVar('username', $username, SQ_SESSION); // No quotes around the last parameter, it's a constant - not a string!

  • return: whether variable is found.
bool sqgetGlobalVar (string $name, mixed &$value, [int $search = SQ_INORDER], [mixed $default = NULL], [int $typecast = FALSE])
  • string $name: name the name of the var to search
  • mixed &$value: value the variable to return
  • int $search: search constant defining where to look
  • mixed $default: default the value to assign to $value when nothing is found
  • int $typecast: typecast force variable to be cast to given type (please use SQ_TYPE_XXX constants or set to FALSE (default) to leave variable type unmolested)
sqGetGlobalVarMultiple (line 233)

Retrieves a form variable, from a set of possible similarly named

form variables, based on finding a different, single field. This is intended to allow more than one same-named inputs in a single <form>, where the submit button that is clicked tells us which input we should retrieve. An example is if we have: <select name="startMessage_1"> <select name="startMessage_2"> <input type="submit" name="form_submit_1" /> <input type="submit" name="form_submit_2" /> and we want to know which one of the select inputs should be returned as $startMessage (without the suffix!), this function decides by looking for either "form_submit_1" or "form_submit_2" (both should not appear). In this example, $name should be "startMessage" and $indicator_field should be "form_submit".

NOTE that form widgets must be named with the suffix "_1", "_2", "_3" and so on, or this function will not work.

If more than one of the indicator fields is found, the first one (numerically) will win.

If an indicator field is found without a matching input ($name) field, FALSE is returned.

If no indicator fields are found, a field of $name *without* any suffix is searched for (but only if $fallback_no_suffix is TRUE), and if not found, FALSE is ultimately returned.

It should also be possible to use the same string for both $name and $indicator_field to look for the first possible widget with a suffix that can be found (and possibly fallback to a widget without a suffix).

  • return: whether variable is found.
bool sqGetGlobalVarMultiple (string $name, mixed &$value, string $indicator_field, [int $search = SQ_INORDER], [bool $fallback_no_suffix = TRUE], [mixed $default = NULL], [int $typecast = FALSE])
  • string $name: name the name of the var to search
  • mixed &$value: value the variable to return
  • string $indicator_field: indicator_field the name of the field upon which to base our decision upon (see above)
  • int $search: search constant defining where to look
  • bool $fallback_no_suffix: fallback_no_suffix whether or not to look for $name with no suffix when nothing else is found
  • mixed $default: default the value to assign to $value when nothing is found
  • int $typecast: typecast force variable to be cast to given type (please use SQ_TYPE_XXX constants or set to FALSE (default) to leave variable type unmolested)
sqsession_destroy (line 478)

Deletes an existing session, more advanced than the standard PHP session_destroy(), it explicitly deletes the cookies and global vars.

WARNING: Older PHP versions have some issues with session management. See http://bugs.php.net/11643 (warning, spammed bug tracker) and http://bugs.php.net/13834. SID constant is not destroyed in PHP 4.1.2, 4.2.3 and maybe other versions. If you restart session after session is destroyed, affected PHP versions produce PHP notice. Bug should be fixed only in 4.3.0

void sqsession_destroy ()
sqsession_is_active (line 533)

Function to verify a session has been started. If it hasn't

start a session up. php.net doesn't tell you that $_SESSION (even though autoglobal), is not created unless a session is started, unlike $_POST, $_GET and such Update: (see #1685031) the session ID is left over after the session is closed in some PHP setups; this function just becomes a passthru to sqsession_start(), but leaving old code in for edification.

void sqsession_is_active ()
sqsession_is_registered (line 173)

Checks to see if a variable has already been registered in the session.

  • return: whether the var has been registered
bool sqsession_is_registered (string $name)
  • string $name: the name of the var to check
sqsession_register (line 144)

Add a variable to the session.

void sqsession_register (mixed $var, string $name)
  • mixed $var: the variable to register
  • string $name: the name to refer to this variable
sqsession_start (line 548)

Function to start the session and store the cookie with the session_id as

HttpOnly cookie which means that the cookie isn't accessible by javascript (IE6 only) Note that as sqsession_is_active() no longer discriminates as to when it calls this function, session_start() has to have E_NOTICE suppression (thus the @ sign).

void sqsession_start ()
sqsession_unregister (line 156)

Delete a variable from the session.

void sqsession_unregister (string $name)
  • string $name: the name of the var to delete
sqsetcookie (line 589)

Set a cookie

  • since: 1.4.16 and 1.5.1
void sqsetcookie (string $sName, [string $sValue = 'deleted'], [int $iExpire = 0], [string $sPath = &quot;&quot;], [string $sDomain = &quot;&quot;], [boolean $bSecure = false], [boolean $bHttpOnly = true], [boolean $bReplace = false])
  • string $sName: The name of the cookie.
  • string $sValue: The value of the cookie.
  • int $iExpire: The time the cookie expires. This is a Unix timestamp so is in number of seconds since the epoch.
  • string $sPath: The path on the server in which the cookie will be available on.
  • string $sDomain: The domain that the cookie is available.
  • boolean $bSecure: Indicates that the cookie should only be transmitted over a secure HTTPS connection.
  • boolean $bHttpOnly: Disallow JS to access the cookie (IE6 only)
  • boolean $bReplace: Replace previous cookies with same name?
sqstripslashes (line 77)

Recursively strip slashes from the values of an array.

void sqstripslashes (array &$array)
  • array &$array: array the array to strip, passed by reference
sq_call_function_suppress_errors (line 118)

Squelch error output to screen (only) for the given function.

If the SquirrelMail debug mode SM_DEBUG_MODE_ADVANCED is not enabled, error output will not go to the log, either.

This provides an alternative to the @ error-suppression operator where errors will not be shown in the interface but will show up in the server log file (assuming the administrator has configured PHP logging).

  • return: The return value, if any, of the function being executed will be returned.
  • since: 1.4.12 and 1.5.2
mixed sq_call_function_suppress_errors (string $function, [array $args = array()])
  • string $function: The function to be executed
  • array $args: The arguments to be passed to the function (OPTIONAL; default no arguments) NOTE: The caller must take extra action if the function being called is supposed to use any of the parameters by reference. In the following example, $x is passed by reference and $y is passed by value to the "my_func" function. sq_call_function_suppress_errors('my_func', array(&$x, $y));
sq_htmlspecialchars (line 794)

Sanitize a value using sm_encode_html_special_chars() or similar, but also recursively run sm_encode_html_special_chars() (or similar) on array keys and values.

If $value is not a string or an array with strings in it, the value is returned as is.

  • return: The sanitized value.
  • since: 1.5.2
mixed sq_htmlspecialchars (mixed $value, [mixed $quote_style = ENT_QUOTES])
  • mixed $value: The value to be sanitized.
  • mixed $quote_style: Either boolean or an integer. If it is an integer, it must be the PHP constant indicating if/how to escape quotes: ENT_QUOTES, ENT_COMPAT, or ENT_NOQUOTES. If it is a boolean value, it must be TRUE and thus indicates that the only sanitizing to be done herein is to replace single and double quotes with &#039; and &quot;, no other changes are made to $value. If it is boolean and FALSE, behavior reverts to same as if the value was ENT_QUOTES (OPTIONAL; default is ENT_QUOTES).

Documentation generated on Fri, 01 Aug 2014 04:18:11 +0200 by phpDocumentor 1.4.3