/functions/strings.php

Description

strings.php

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

Functions
GenerateRandomString (line 702)

Generates a random string from the character set you pass in

  • return: the random string
  • since: 1.0
string GenerateRandomString (int $size, string $chars, [int $flags = 0])
  • int $size: the length of the string to generate
  • string $chars: a string containing the characters to use
  • int $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 471)

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
  • since: 1.0
string get_location ()
get_message_list_uri (line 560)

Get Message List URI

  • return: The message list URI
  • since: 1.5.2
string get_message_list_uri (string $mailbox, string $startMessage, [string $what = ''])
  • string $mailbox: Current mailbox name (unencoded/raw)
  • string $startMessage: The mailbox page offset
  • string $what: Any current search parameters (OPTIONAL; default empty string)
makeComposeLink (line 752)

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
  • since: 1.4.2
string makeComposeLink (string $url, [string $text = null], [string $target = ''], [string $accesskey = 'NONE'])
  • string $url: The URL to the compose page
  • string $text: The link text, default "Compose"
  • string $target: URL target, if any (since 1.4.3)
  • string $accesskey: The access key to be used, if any
OneTimePadCreate (line 648)

Creates encryption key

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

Pad must be longer or equal to encoded string length in 1.4.4/1.5.0 and older.

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

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
  • since: 1.0
string OneTimePadDecrypt (string $string, string $epad)
  • string $string: the string to decrypt
  • string $epad: the encryption key from the session
OneTimePadEncrypt (line 585)

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
  • since: 1.0
string OneTimePadEncrypt (string $string, string $epad)
  • string $string: the (password)string to encrypt
  • string $epad: the encryption key
quoteimap (line 733)

Escapes special characters for use in IMAP commands.

  • return: the escaped string
  • since: 1.0.3
string quoteimap (string $str)
  • string $str: the string to escape
readShortMailboxName (line 443)

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
  • since: 1.0
string readShortMailboxName (string $haystack, string $needle)
  • string $haystack: haystack full mailbox name to search
  • string $needle: needle the mailbox separator character
show_readable_size (line 668)

Returns a string showing a byte size figure in a more easily digested (readable) format

  • return: The size in human readable format
  • since: 1.0
string show_readable_size (int $bytes)
  • int $bytes: the size in bytes
sm_ctype_space (line 76)

Checks for spaces in strings - only used if PHP doesn't have native ctype support

You might be able to rewrite the function by adding short evaluation form.

possible problems:

  • iso-2022-xx charsets - hex 20 might be part of other symbol. I might
be wrong. 0x20 is not used in iso-2022-jp. I haven't checked iso-2022-kr and iso-2022-cn mappings.

  • no-break space ( ) - it is 8bit symbol, that depends on charset.
there are at least three different charset groups that have nbsp in different places.

I don't see any charset/nbsp options in php ctype either.

  • return: true when only whitespace symbols are present in test string
  • since: 1.5.1
bool sm_ctype_space (string $string)
  • string $string: tested string
sm_encode_html_special_chars (line 1698)

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)
  • 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 1552)

Generates a security token that is then stored in the user's preferences with a timestamp for later verification/use.

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 1494)

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_truncate_string (line 1409)

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 1626)

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

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)
sqBodyWrap (line 96)

Wraps text at $wrap characters. While sqWordWrap takes a single line of text and wraps it, this function works on the entire corpus at once, this allows it to be a little bit smarter and when and how to wrap.

  • return: the wrapped text
  • author: Justus Pendleton
  • since: 1.5.1
string &sqBodyWrap ( &$body, int $wrap, string $body)
  • string $body: the entire body of text
  • int $wrap: the maximum line length
  • &$body
sqMakeCite (line 25)

Appends citation markers to the string.

Also appends a trailing space.

  • author: Justus Pendleton
  • since: 1.5.1
null sqMakeCite ( &$str, int $citeLevel, string $str)
  • string $str: The string to append to
  • int $citeLevel: the number of markers to append
  • &$str
sqMakeNewLine (line 45)

Create a newline in the string, adding citation markers to the newline as necessary.

  • author: Justus Pendleton
  • since: 1.5.1
null sqMakeNewLine ( &$str, int $citeLevel,  &$column, string $str, int $column)
  • string $str: the string to make a newline in
  • int $citeLevel: the citation level the newline is at
  • int $column: starting column of the newline
  • &$str
  • &$column
sqUnWordWrap (line 399)

Does the opposite of sqWordWrap()

  • since: 1.0
void sqUnWordWrap ( &$body, string $body)
  • string $body: the text to un-wordwrap
  • &$body
sqWordWrap (line 340)

Wraps text at $wrap characters

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

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

  • since: 1.0
void sqWordWrap ( &$line, int $wrap, [string $charset = ''], string $line)
  • string $line: the line of text to wrap, by ref
  • int $wrap: the maximum line lenth
  • string $charset: name of charset used in $line string. Available since v.1.5.1.
  • &$line
sq_count8bit (line 1365)

Counts 8bit bytes in string

  • return: number of 8bit bytes
integer sq_count8bit (string $string)
  • string $string: tested string
sq_fwrite (line 793)

version of fwrite which checks for failure

  • return: of written bytes. false on failure
  • since: 1.4.3
number sq_fwrite (resource $fp, string $string)
  • resource $fp
  • string $string
sq_get_html_translation_table (line 824)

sq_get_html_translation_table

Returns the translation table used by sq_htmlentities()

  • return: html translation array
  • since: 1.5.1
array sq_get_html_translation_table (integer $table, [integer $quote_style = ENT_COMPAT], [string $charset = 'us-ascii'])
  • integer $table: html translation table. Possible values (without quotes):
    • HTML_ENTITIES - full html entities table defined by charset
    • HTML_SPECIALCHARS - html special characters table
  • integer $quote_style: quote encoding style. Possible values (without quotes):
    • ENT_COMPAT - (default) encode double quotes
    • ENT_NOQUOTES - don't encode double or single quotes
    • ENT_QUOTES - encode double and single quotes
  • string $charset: charset used for encoding. default to us-ascii, 'auto' uses $default_charset global value.
sq_htmlentities (line 888)

sq_htmlentities

Convert all applicable characters to HTML entities. Minimal php requirement - v.4.0.5.

Function is designed for people that want to use full power of htmlentities() in i18n environment.

  • return: sanitized string
  • since: 1.5.1
string sq_htmlentities (string $string, [integer $quote_style = ENT_COMPAT], [string $charset = 'us-ascii'])
  • string $string: string that has to be sanitized
  • integer $quote_style: quote encoding style. Possible values (without quotes):
    • ENT_COMPAT - (default) encode double quotes
    • ENT_NOQUOTES - don't encode double or single quotes
    • ENT_QUOTES - encode double and single quotes
  • string $charset: charset used for encoding. defaults to 'us-ascii', 'auto' uses $default_charset global value.
sq_is8bit (line 906)

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 1011)

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 941)

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 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_strlen (line 1028)

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 $str, [string $charset = null])
  • string $str: string
  • string $charset: charset
sq_strpos (line 1278)

Wrapper that is used to switch between vanilla and multibyte strpos functions.

string sq_strpos (string $haystack, mixed $needle, integer $offset, [string $charset = 'auto'])
  • string $haystack
  • mixed $needle
  • integer $offset
  • string $charset
sq_strtoupper (line 1323)

Wrapper that is used to switch between vanilla and multibyte strtoupper functions.

string sq_strtoupper (string $string, [string $charset = 'auto'])
  • string $string
  • string $charset
sq_str_pad (line 1069)

string padding with multibyte support

string sq_str_pad (string $string, integer $width, string $pad, integer $padtype, [string $charset = ''])
  • string $string: original string
  • integer $width: padded string width
  • string $pad: padding symbols
  • integer $padtype: padding type (internal php defines, see str_pad() description)
  • string $charset: charset used in original string
sq_substr (line 1102)

Wrapper that is used to switch between vanilla and multibyte substr functions.

string sq_substr (string $string, integer $start, [integer $length = NULL], [string $charset = 'auto'])
  • string $string
  • integer $start
  • integer $length
  • string $charset
sq_substr_replace (line 1171)

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 1378)

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

Documentation generated on Thu, 23 Oct 2014 04:20:10 +0200 by phpDocumentor 1.4.3