HumHub Documentation (unofficial)

The boundary string.

The input string.

If limit is set and positive, the returned array will contain a maximum of limit elements with the last element containing the rest of string. If the limit parameter is negative, all components except the last -limit are returned. If the limit parameter is zero, then this is treated as 1.

The input string.

The optional second quote_style parameter lets you define what will be done with 'single' and "double" quotes. It takes on one of three constants with the default being ENT_COMPAT . Available quote_style constants:

• ENT_COMPAT: Will convert double-quotes and leave single-quotes alone.
• ENT_QUOTES: Will convert both double and single quotes.
• ENT_NOQUOTES: Will leave both double and single quotes unconverted.

The ISO-8859-1 character set is used as default for the optional third charset. This defines the character set used in conversion.

The input string.

The input string.

Whenever to use XHTML compatible line breaks or not.

The pattern to search for. It can be either a string or an array with strings. Several PCRE modifiers are also available, including the deprecated e (PREG_REPLACE_EVAL), which is specific to this function.

The string or an array with strings to replace.

• If this parameter is a string and the pattern parameter is an array, all patterns will be replaced by that string.
• If both pattern and replacement parameters are arrays, each pattern will be replaced by the replacement counterpart.
• If there are fewer elements in the replacement array than in the pattern array, any extra patterns will be replaced by an empty string.
• replacement may contain references of the form \\n or (since PHP 4.0.4) $n, with the latter form being the preferred one. Every such reference will be replaced by the text captured by the n'th parenthesized pattern. n can be from 0 to 99, and \\0 or $0 refers to the text matched by the whole pattern. Opening parentheses are counted from left to right (starting from 1) to obtain the number of the capturing subpattern. To use backslash in replacement, it must be doubled ("\\\\" PHP string).
• When working with a replacement pattern where a backreference is immediately followed by another number (i.e.: placing a literal number immediately after a matched pattern), you cannot use the familiar \\1 notation for your backreference. \\11, for example, would confuse preg_replace since it does not know whether you want the \\1 backreference followed by a literal 1, or the \\11 backreference followed by nothing. In this case the solution is to use \${1}1. This creates an isolated $1 backreference, leaving the 1 as a literal.
• When using the deprecated e modifier, this function escapes some characters (namely ', ", \ and NULL) in the strings that replace the backreferences. This is done to ensure that no syntax errors arise from backreference usage with either single or double quotes (e.g. strlen(\'$1\') + strlen("$2")). Make sure you are aware of PHP's string syntax to know exactly how the interpreted string will look.

The string or an array with strings to search and replace. If subject is an array, then the search and replace is performed on every entry of subject , and the return value is an array as well.

The maximum possible replacements for each pattern in each subject string. Defaults to -1 (no limit).

If specified, this variable will be filled with the number of replacements done.

The pattern to search for, as a string.

The input string.

If matches is provided, then it is filled with the results of search. $matches[0] will contain the text that matched the full pattern, $matches[1] will have the text that matched the first captured parenthesized subpattern, and so on.

flags can be the following flags:

• PREG_OFFSET_CAPTURE: If this flag is passed, for every occurring match the appendant string offset will also be returned. Note that this changes the value of matches into an array where every element is an array consisting of the matched string at offset 0 and its string offset into subject at offset 1.

Lib::preg_match('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
print_r($matches);

The above example will output:

Array
(
  [0] => Array
    (
      [0] => foobarbaz
      [1] => 0
    )

  [1] => Array
    (
        [0] => foo
        [1] => 0
    )

  [2] => Array
    (
        [0] => bar
        [1] => 3
    )

  [3] => Array
    (
        [0] => baz
        [1] => 6
    )
)

• PREG_UNMATCHED_AS_NULL : If this flag is passed, unmatched subpatterns are reported as NULL; otherwise they are reported as an empty string.

Lib::preg_match('/(a)(b)*(c)/', 'ac', $matches);
var_dump($matches);
Lib::preg_match('/(a)(b)*(c)/', 'ac', $matches, PREG_UNMATCHED_AS_NULL);
var_dump($matches);

The above example will output:

array(4) {
  [0]=> string(2) "ac"
  [1]=> string(1) "a"
  [2]=> string(0) ""
  [3]=> string(1) "c"
}
array(4) {
  [0]=> string(2) "ac"
  [1]=> string(1) "a"
  [2]=> NULL
  [3]=> string(1) "c"
}

Normally, the search starts from the beginning of the subject string. The optional parameter offset can be used to specify the alternate place from which to start the search (in bytes). Using offset is not equivalent to passing substr($subject, $offset) to preg_match in place of the subject string, because pattern can contain assertions such as ^, $ or (?<=x).

Compare:

$subject = "abcdef";
$pattern = '/^def/';
Lib::preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);
print_r($matches);

The above example will output:

Array
(
)

while this example

$subject = "abcdef";
$pattern = '/^def/';
Lib::preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE);
print_r($matches);

will produce:

Array
(
[0] => Array
    (
        [0] => def
        [1] => 0
    )
)

Alternatively, to avoid using substr(), use the \G assertion rather than the ^ anchor, or the A modifier instead, both of which work with the offset parameter.

The pattern to search for, as a string.

The input string.

Array of all matches in multi-dimensional array ordered according to flags.

Can be a combination of the following flags (note that it doesn't make sense to use PREG_PATTERN_ORDER together with PREG_SET_ORDER):

• PREG_PATTERN_ORDER: Orders results so that $matches[0] is an array of full pattern matches, $matches[1] is an array of strings matched by the first parenthesized subpattern, and so on. For example:

preg_match_all(
    "|<[^>]+>(.*)</[^>]+>|U",
    "<b>example: </b><div align=left>this is a test</div>",
    $out, PREG_PATTERN_ORDER
);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";

The above example will output:

<b>example: </b>, <div align=left>this is a test</div>
example: , this is a test

So, $out[0] contains array of strings that matched full pattern, and $out[1] contains array of strings enclosed by tags.

If the pattern contains named subpatterns, $matches additionally contains entries for keys with the subpattern name.

If the pattern contains duplicate named subpatterns, only the rightmost subpattern is stored in $matches[NAME].

preg_match_all(
    '/(?J)(?<match>foo)|(?<match>bar)/',
    'foo bar',
    $matches,
    PREG_PATTERN_ORDER
);
print_r($matches['match'])

The above example will output:

Array
(
    [0] =>
    [1] => bar
)

• PREG_SET_ORDER: Orders results so that $matches[0] is an array of first set of matches, $matches[1] is an array of second set of matches, and so on. For example:

preg_match_all(
    "|<[^>]+>(.*)</[^>]+>|U",
    "<b>example: </b><div align=left>this is a test</div>",
    $out, PREG_SET_ORDER
);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";

The above example will output

<b>example: </b>, example:
<div align="left">this is a test</div>, this is a test

• PREG_OFFSET_CAPTURE: If this flag is passed, for every occurring match the appendant string offset (in bytes) will also be returned. Note that this changes the value of matches into an array of arrays where every element is an array consisting of the matched string at offset 0 and its string offset into subject at offset 1.

preg_match_all('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
print_r($matches);

The above example will output

Array
(
    [0] => Array
        (
            [0] => Array
                (
                    [0] => foobarbaz
                    [1] => 0
                )

        )

    [1] => Array
        (
            [0] => Array
                (
                    [0] => foo
                    [1] => 0
                )

        )

    [2] => Array
        (
            [0] => Array
                (
                    [0] => bar
                    [1] => 3
                )

        )

    [3] => Array
        (
            [0] => Array
                (
                    [0] => baz
                    [1] => 6
                )

        )

)

• PREG_UNMATCHED_AS_NULL: If this flag is passed, unmatched subpatterns are reported as NULL; otherwise they are reported as an empty string.

If no order flag is given, PREG_PATTERN_ORDER is assumed.

Normally, the search starts from the beginning of the subject string. The optional parameter offset can be used to specify the alternate place from which to start the search (in bytes). Using offset is not equivalent to passing substr($subject, $offset) to preg_match_all in place of the subject string, because pattern can contain assertions such as ^, $ or (?<=x). See [[preg_match()]] for examples.

Lib::preg_match_all("|]+>(.*)]+>|U", "example: this is a test", $out, PREG_PATTERN_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";

The above example will output:

example: , this is a test
example: , this is a test

So, $out[0] contains array of strings that matched full pattern, and $out[1] contains array of strings enclosed by tags.

The pattern to search for. It can be either a string or an array with strings. Several PCRE modifiers are also available, including the deprecated 'e' (PREG_REPLACE_EVAL), which is specific to this function.

The string or an array with strings to replace.

• If this parameter is a string and the pattern parameter is an array, all patterns will be replaced by that string.
• If both pattern and replacement parameters are arrays, each pattern will be replaced by the replacement counterpart.
• If there are fewer elements in the replacement array than in the pattern array, any extra patterns will be replaced by an empty string.
• replacement may contain references of the form \\n or (since PHP 4.0.4) $n, with the latter form being the preferred one. Every such reference will be replaced by the text captured by the n'th parenthesized pattern. n can be from 0 to 99, and \\0 or $0 refers to the text matched by the whole pattern. Opening parentheses are counted from left to right (starting from 1) to obtain the number of the capturing subpattern. To use backslash in replacement, it must be doubled ("\\\\" PHP string).
• When working with a replacement pattern where a backreference is immediately followed by another number (i.e.: placing a literal number immediately after a matched pattern), you cannot use the familiar \\1 notation for your backreference. \\11, for example, would confuse preg_replace since it does not know whether you want the \\1 backreference followed by a literal 1, or the \\11 backreference followed by nothing. In this case the solution is to use \${1}1. This creates an isolated $1 backreference, leaving the 1 as a literal.
• When using the deprecated e modifier, this function escapes some characters (namely ', ", \ and NULL) in the strings that replace the backreferences. This is done to ensure that no syntax errors arise from backreference usage with either single or double quotes (e.g. strlen(\'$1\') + strlen("$2")). Make sure you are aware of PHP's string syntax to know exactly how the interpreted string will look.

The string or an array with strings to search and replace. If subject is an array, then the search and replace is performed on every entry of subject , and the return value is an array as well.

The maximum possible replacements for each pattern in each subject string. Defaults to -1 (no limit).

If specified, this variable will be filled with the number of replacements done.

The pattern to search for. It can be either a string or an array with strings. *

A callback that will be called and passed an array of matched elements in the subject string. The callback should return the replacement string. This is the callback signature:

handler(array $matches): string

You'll often need the callback function for a preg_replace_callback in just one place. In this case you can use an anonymous function to declare the callback within the call to preg_replace_callback. By doing it this way you have all information for the call in one place and do not clutter the function namespace with a callback function's name not used anywhere else.

Example of usage of preg_replace_callback and anonymous function:

// a unix-style command line filter to convert uppercase
// letters at the beginning of paragraphs to lowercase
$fp = fopen("php://stdin", "r") or die("can't read stdin");
while (!feof($fp)) {
    $line = fgets($fp);
    $line = Lib::preg_replace_callback( '|\s*\w|', function ($matches) {
         return Lib::strtolower($matches[0]);
    }, $line);
    echo $line;
}
fclose($fp);

The string or an array with strings to search and replace.

The maximum possible replacements for each pattern in each subject string. Defaults to -1 (no limit).

If specified, this variable will be filled with the number of replacements done.

can be a combination of the PREG_OFFSET_CAPTURE and PREG_UNMATCHED_AS_NULL flags, which influence the format of the matches array. See the description in [[preg_match]] for more details.

An associative array mapping patterns (keys) to callbacks (values)

The string or an array with strings to search and replace.

The maximum possible replacements for each pattern in each subject string. Defaults to -1 (no limit).

If specified, this variable will be filled with the number of replacements done.

can be a combination of the PREG_OFFSET_CAPTURE and PREG_UNMATCHED_AS_NULL flags, which influence the format of the matches array. See the description in [[preg_match]] for more details.

The pattern to search for, as a string.

The input string.

If specified, then only substrings up to limit are returned with the rest of the string being placed in the last substring. A limit of -1, 0 or NULL means "no limit" and, as is standard across PHP, you can use NULL to skip to the flags parameter.

flags can be any combination of the following flags (combined with the | bitwise operator): PREG_SPLIT_NO_EMPTY If this flag is set, only non-empty pieces will be returned by preg_split.

The URL to be encoded.

The string to be encoded.

The value being searched for, otherwise known as the needle. An array may be used to designate multiple needles.

The replacement value that replaces found search values. An array may be used to designate multiple replacements.

The string or array being searched and replaced on, otherwise known as the haystack. If subject is an array, then the search and replace is performed with every entry of subject, and the return value is an array as well.

If passed, this will hold the number of matched and replaced needles.

The string to be repeated.

Number of time the input string should be repeated. The multiplier has to be greater than or equal to 0. If the multiplier is set to 0, the function will return an empty string.

The value being searched for, otherwise known as the needle. An array may be used to designate multiple needles.

The replacement value that replaces found search values. An array may be used to designate multiple replacements.

The string or array being searched and replaced on, otherwise known as the haystack. If subject is an array, then the search and replace is performed with every entry of subject, and the return value is an array as well.

If passed, this will hold the number of matched and replaced needles.

The input string.

You can use the optional second parameter to specify tags which should not be stripped. HTML comments and PHP tags are also stripped. This is hardcoded and can not be changed with allowable_tags.

The string to search in

If needle is not a string, it is converted to an integer and applied as the ordinal value of a character.

If specified, search will start this number of characters counted from the beginning of the string. If the value is negative, search will instead start from that many characters from the end of the string, searching backwards.

The string being measured for length.

The first string.

The second string.

Number of characters to use in the comparison.

The string to search in

If needle is not a string, it is converted to an integer and applied as the ordinal value of a character.

If specified, search will start this number of characters counted from the beginning of the string. Unlike [[strrpos()]] and [[stripos()]], the offset cannot be negative.

The string to search in

If needle is not a string, it is converted to an integer and applied as the ordinal value of a character.

If specified, search will start this number of characters counted from the beginning of the string. If the value is negative, search will instead start from that many characters from the end of the string, searching backwards.

The input string.

The input string.

The string being translated.

The replace_pairs parameter may be used as a substitute for to and from in which case it's an array in the form ['from' => 'to', ...].

The input string.

The starting offset position.

• If the start is non-negative, the returned string will start at the start'th position in string, counting from zero. For instance, in the string 'abcdef', the character at position 0 is 'a', the character at position 2 is 'c', and so forth.
• If start is negative, the returned string will start at the start'th character from the end of string.
• If string is less than or equal to start characters long, false will be returned.

Example(s) of using a negative start:

$rest = Lib::substr("abcdef", -1);    // returns "f"
$rest = Lib::substr("abcdef", -2);    // returns "ef"
$rest = Lib::substr("abcdef", -3, 1); // returns "d"

The length of characters to return.

• If length is given and is positive, the string returned will contain at most length characters beginning from start (depending on the length of string).
• If length is given and is negative, then that many characters will be omitted from the end of string (after the start position has been calculated when a start is negative). If start denotes a position beyond this truncation, an empty string will be returned.
• If length is given and is 0, then false or null or an empty string will be returned.

Example(s) of using a negative length:

$rest = Lib::substr("abcdef", 0, -1);  // returns "abcde"
$rest = Lib::substr("abcdef", 2, -1);  // returns "cde"
$rest = Lib::substr("abcdef", 4, -4);  // returns false
$rest = Lib::substr("abcdef", -3, -1); // returns "de"

The string that will be trimmed.

Optionally, the stripped characters can also be specified using the charlist parameter. Simply list all characters that you want to be stripped. With .. you can specify a range of characters.

The input string.

The input string.

The optional separators contains the word separator characters.

The string to be decoded.

The string to be encoded.