/functions/strings.php

Description
Description | Includes | Functions

strings.php

This code provides various string manipulation functions that are used by the rest of the SquirrelMail code.

Includes
Description | Includes | Functions
include_once (SM_PATH.'plugins/compatibility/functions.php') (line 36)
require_once (SM_PATH.'functions/global.php') (line 33)

There can be a circular issue with includes, where the $version string is referenced by the include of global.php, etc. before it's defined.

For that reason, bring in global.php AFTER we define the version strings.

Functions
Description | Includes | Functions
GenerateRandomString (line 614)

Generates a random string from the caracter set you pass in

  • return: the random string
string GenerateRandomString (int $size, string $chars, [int $flags = 0])
  • int $size: size the size of the string to generate
  • string $chars: chars a string containing the characters to use
  • int $flags: flags a flag to add a specific set to the characters to use: Flags:
    1. = add lowercase a-z to $chars
    2. = add uppercase A-Z to $chars
    4 = add numbers 0-9 to $chars
get_location (line 340)

get_location

Determines the location to forward to, relative to your server. This is used in HTTP Location: redirects. If set, it uses $config_location_base as the first part of the URL, specifically, the protocol, hostname and port parts. The path is always autodetected.

  • return: the base url for this SquirrelMail installation
string get_location ()
makeComposeLink (line 704)

Create compose link

Returns a link to the compose-page, taking in consideration the compose_in_new and javascript settings.

  • return: a link to the compose page
string makeComposeLink (string $url, [string $text = null], [ $target = ''])
  • string $url: url the URL to the compose page
  • string $text: text the link text, default "Compose"
  • $target
OneTimePadCreate (line 565)

Creates encryption key

Creates an encryption key for encrypting the password stored in the cookie. The encryption key itself is stored in the session.

  • return: the encryption key
string OneTimePadCreate ([int $length = 100])
  • int $length: length optional, length of the string to generate
OneTimePadDecrypt (line 460)

Decrypts a password from the cookie

Decrypts a password from the cookie, encrypted by OneTimePadEncrypt. This uses the encryption key that is stored in the session.

  • return: the decrypted password
string OneTimePadDecrypt (string $string, string $epad)
  • string $string: string the string to decrypt
  • string $epad: epad the encryption key from the session
OneTimePadEncrypt (line 430)

Encrypts password

These functions are used to encrypt the password before it is stored in a cookie. The encryption key is generated by OneTimePadCreate();

  • return: the base64-encoded encrypted password
string OneTimePadEncrypt (string $string, string $epad)
  • string $string: string the (password)string to encrypt
  • string $epad: epad the encryption key
php_self (line 266)

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.

  • return: The path, filename and any arguments for the current script
  • since: 1.2.3
string php_self ()
quoteimap (line 646)

Escapes special characters for use in IMAP commands.

  • return: the escaped string
string quoteimap (string $str)
  • string $str: the string to escape
readShortMailboxName (line 240)

If $haystack is a full mailbox name and $needle is the mailbox separator character, returns the last part of the mailbox name.

  • return: the last part of the mailbox name
string readShortMailboxName (string $haystack, string $needle)
  • string $haystack: haystack full mailbox name to search
  • string $needle: needle the mailbox separator character
RemoveSlashes (line 678)

Removes slashes from every element in the array

void RemoveSlashes ( &$array)
  • &$array
show_readable_size (line 582)

Returns a string showing the size of the message/attachment.

  • return: the filesize in human readable format
string show_readable_size (int $bytes)
  • int $bytes: bytes the filesize in bytes
sm_encode_html_special_chars (line 1549)

Wrapper for PHP's htmlspecialchars() that attempts to add the correct character encoding

  • return: The converted text
string sm_encode_html_special_chars (string $string, [int $flags = ENT_COMPAT], [string $encoding = NULL], [boolean $double_encode = TRUE])
  • string $string: The string to be converted
  • int $flags: A bitmask that controls the behavior of htmlspecialchars() (See http://php.net/manual/function.htmlspecialchars.php ) (OPTIONAL; default ENT_COMPAT, ENT_COMPAT | ENT_SUBSTITUTE for PHP >=5.4)
  • string $encoding: The character encoding to use in the conversion (OPTIONAL; default automatic detection)
  • boolean $double_encode: Whether or not to convert entities that are already in the string (only supported in PHP 5.2.3+) (OPTIONAL; default TRUE)
sm_generate_security_token (line 1364)

Generates a security token that is then stored in the user's preferences with a timestamp for later verification/use (although session-based tokens are not stored in user preferences).

NOTE: By default SquirrelMail will use a single session-based token, but if desired, user tokens can have expiration dates associated with them and become invalid even during the same login session. When in that mode, the note immediately below applies, otherwise it is irrelevant. To enable that mode, the administrator must add the following to config/config_local.php: $use_expiring_security_tokens = TRUE;

NOTE: The administrator can force SquirrelMail to generate a new token every time one is requested (which may increase obscurity through token randomness at the cost of some performance) by adding the following to config/config_local.php: $do_not_use_single_token = TRUE; Otherwise, only one token will be generated per user which will change only after it expires or is used outside of the validity period specified when calling sm_validate_security_token()

WARNING: If the administrator has turned the token system off by setting $disable_security_tokens to TRUE in config/config.php or the configuration tool, this function will not store tokens in the user preferences (but it will still generate and return a random string).

  • return: A security token
  • since: 1.4.19 and 1.5.2
string sm_generate_security_token ([boolean $force_generate_new = FALSE])
  • boolean $force_generate_new: When TRUE, a new token will always be created even if current configuration dictates otherwise (OPTIONAL; default FALSE)
sm_get_user_security_tokens (line 1296)

Gathers the list of secuirty tokens currently stored in the user's preferences and optionally purges old ones from the list.

  • return: The list of tokens
  • since: 1.4.19 and 1.5.2
array sm_get_user_security_tokens ([boolean $purge_old = TRUE])
  • boolean $purge_old: Indicates if old tokens should be purged from the list ("old" is 2 days or older unless the administrator overrides that value using $max_token_age_days in config/config_local.php) (OPTIONAL; default is to always purge old tokens)
sm_print_r (line 747)

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 <[email protected]> to be displayed. The output is wrapped in <pre> and </pre> tags.

void sm_print_r ()
sm_truncate_string (line 167)

Truncates the given string so that it has at

most $max_chars characters. NOTE that a "character" may be a multibyte character, or (optionally), an HTML entity, so this function is different than using substr() or mb_substr().

NOTE that if $elipses is given and used, the returned number of characters will be $max_chars PLUS the length of $elipses

  • return: The truncated string
  • since: 1.4.20 and 1.5.2 (replaced truncateWithEntities())
string sm_truncate_string (string $string, int $max_chars, [string $elipses = ''], [boolean $html_entities_as_chars = FALSE])
  • string $string: The string to truncate
  • int $max_chars: The maximum allowable characters
  • string $elipses: A string that will be added to the end of the truncated string (ONLY if it is truncated) (OPTIONAL; default not used)
  • boolean $html_entities_as_chars: Whether or not to keep HTML entities together (OPTIONAL; default ignore HTML entities)
sm_validate_security_token (line 1456)

Validates a given security token and optionally remove it from the user's preferences if it was valid. If the token is too old but otherwise valid, it will still be rejected.

"Too old" is 2 days or older unless the administrator overrides that value using $max_token_age_days in config/config_local.php

Session-based tokens of course are always reused and are valid for the lifetime of the login session.

WARNING: If the administrator has turned the token system off by setting $disable_security_tokens to TRUE in config/config.php or the configuration tool, this function will always return TRUE.

  • return: TRUE if the token validated; FALSE otherwise
  • since: 1.4.19 and 1.5.2
boolean sm_validate_security_token (string $token, [int $validity_period = 0], [boolean $show_error = FALSE])
  • string $token: The token to validate
  • int $validity_period: The number of seconds tokens are valid for (set to zero to remove valid tokens after only one use; set to -1 to allow indefinite re-use (but still subject to $max_token_age_days - see elsewhere); use 3600 to allow tokens to be reused for an hour) (OPTIONAL; default is to only allow tokens to be used once) NOTE this is unrelated to $max_token_age_days or rather is an additional time constraint on tokens that allows them to be re-used (or not) within a more narrow timeframe
  • boolean $show_error: Indicates that if the token is not valid, this function should display a generic error, log the user out and exit - this function will never return in that case. (OPTIONAL; default FALSE)
sqm_baseuri (line 315)

Find out where squirrelmail lives and try to be smart about it.

The only problem would be when squirrelmail lives in directories called "src", "functions", or "plugins", but people who do that need to be beaten with a steel pipe anyway.

  • return: the base uri of squirrelmail installation.
string sqm_baseuri ()
sqUnWordWrap (line 105)

Does the opposite of sqWordWrap()

void sqUnWordWrap (string &$body)
  • string &$body: body the text to un-wordwrap
sqWordWrap (line 48)

Wraps text at $wrap characters

Has a problem with special HTML characters, so call this before you do character translation.

Specifically, &#039 comes up as 5 characters instead of 1. This should not add newlines to the end of lines.

void sqWordWrap ( &$line,  $wrap, [ $charset = null])
  • &$line
  • $wrap
  • $charset
sq_fwrite (line 763)

version of fwrite which checks for failure

void sq_fwrite ( $fp,  $string)
  • $fp
  • $string
sq_is8bit (line 784)

Tests if string contains 8bit symbols.

If charset is not set, function defaults to default_charset. $default_charset global must be set correctly if $charset is not used.

  • return: true if 8bit symbols are detected
  • since: 1.5.1 and 1.4.4
bool sq_is8bit (string $string, [string $charset = ''])
  • string $string: tested string
  • string $charset: charset used in a string
sq_lowercase_array_vals (line 1263)

Callback function used to lowercase array values.

  • since: 1.5.1 and 1.4.6
void sq_lowercase_array_vals ( &$val, mixed $key, string $val)
  • string $val: array value
  • mixed $key: array key
  • &$val
sq_mb_list_encodings (line 1186)

Replacement of mb_list_encodings function

This function provides replacement for function that is available only in php 5.x. Function does not test all mbstring encodings. Only the ones that might be used in SM translations.

Supported strings are stored in session in order to reduce number of mb_internal_encoding function calls.

If mb_list_encodings() function is present, code uses it. Main difference from original function behaviour - array values are lowercased in order to simplify use of returned array in in_array() checks.

If you want to test all mbstring encodings - fill $list_of_encodings array.

  • return: list of encodings supported by php mbstring extension
  • since: 1.5.1 and 1.4.6
array sq_mb_list_encodings ()
sq_mt_randomize (line 522)

Init random number generator

This function initializes the random number generator fairly well. It also only initializes it once, so you don't accidentally get the same 'random' numbers twice in one session.

void sq_mt_randomize ()
sq_mt_seed (line 492)

Randomizes the mt_rand() function.

Toss this in strings or integers and it will seed the generator appropriately. With strings, it is better to get them long. Use md5() to lengthen smaller strings.

void sq_mt_seed (mixed $Val)
  • mixed $Val: val a value to seed the random number generator
sq_strlen (line 816)

Function returns number of characters in string.

Returned number might be different from number of bytes in string, if $charset is multibyte charset. Detection depends on mbstring functions. If mbstring does not support tested multibyte charset, vanilla string length function is used.

  • return: number of characters in string
  • since: 1.5.1 and 1.4.6
integer sq_strlen ( $string, [string $charset = NULL], string $str)
  • string $str: string
  • string $charset: charset
  • $string
sq_strpos (line 895)

This is a replacement for PHP's strpos() that is multibyte-aware.

  • return: The integer offset of the next $needle in $haystack, if found, or FALSE if not found
mixed sq_strpos (string $haystack, string $needle, [int $offset = 0], [string $charset = 'auto'])
  • string $haystack: The string to search within
  • string $needle: The substring to search for
  • int $offset: The offset from the beginning of $haystack from which to start searching (OPTIONAL; default none)
  • string $charset: The charset of the given string. A value of NULL here will force the use of PHP's standard strpos(). (OPTIONAL; default is "auto", which indicates that the user's current charset should be used).
sq_substr (line 980)

This is a replacement for PHP's substr() that is multibyte-aware.

  • return:

    The desired substring

    Of course, you can use more advanced (e.g., negative) values for $start and $length as needed - see the PHP manual for more information: http://www.php.net/manual/function.substr.php

string sq_substr (string $string, int $start, [int $length = NULL], [string $charset = 'auto'])
  • string $string: The string to operate upon
  • int $start: The offset at which to begin substring extraction
  • int $length: The number of characters after $start to return NOTE that if you need to specify a charset but want to achieve normal substr() behavior where $length is not specified, use NULL (OPTIONAL; default from $start to end of string)
  • string $charset: The charset of the given string. A value of NULL here will force the use of PHP's standard substr(). (OPTIONAL; default is "auto", which indicates that the user's current charset should be used).
sq_substr_replace (line 1074)

This is a replacement for PHP's substr_replace() that is multibyte-aware.

  • return:

    The manipulated string

    Of course, you can use more advanced (e.g., negative) values for $start and $length as needed - see the PHP manual for more information: http://www.php.net/manual/function.substr-replace.php

string sq_substr_replace (string $string, string $replacement, int $start, [int $length = NULL], [string $charset = 'auto'])
  • string $string: The string to operate upon
  • string $replacement: The string to be inserted
  • int $start: The offset at which to begin substring replacement
  • int $length: The number of characters after $start to remove NOTE that if you need to specify a charset but want to achieve normal substr_replace() behavior where $length is not specified, use NULL (OPTIONAL; default from $start to end of string)
  • string $charset: The charset of the given string. A value of NULL here will force the use of PHP's standard substr(). (OPTIONAL; default is "auto", which indicates that the user's current charset should be used).
sq_trim_value (line 1272)

Callback function to trim whitespace from a value, to be used in array_walk

  • since: 1.5.2 and 1.4.7
void sq_trim_value ( &$value, string $value)
  • string $value: value to trim
  • &$value
TrimArray (line 659)

Trims array

Trims every element in the array, ie. remove the first char of each element Obsolete: will probably removed soon

void TrimArray (array &$array)
  • array &$array: array the array to trim

Documentation generated on Mon, 13 Jan 2020 04:25:22 +0100 by phpDocumentor 1.4.3