6. Standard library

Functions which are documented in this chapter are considered core functions hence are available in all contexts. Functions in the standard library may be recognized by the fact that they are all in lowercase.

6.1. Array

array_keys(array)

Returns the keys in the array.

Parameters:array (array) – the array
Returns:array’s keys
Return type:array
array_filter(callback, array)

Returns the filtered items from the array using a callback.

Parameters:
  • callback (function) – the callback
  • array (array) – the array
Returns:

array of filtered values, keys are preserved

Return type:

array

The function should take one argument (value) and return a boolean value.

array_filter(function ($x) { return $x % 2 == 0; }, [0, 1, 2, 3]); // even values
array_filter(is_number, [0, "Hello World", 2]);
array_map(callback, array)

Returns values from the array with the callback applied.

Parameters:
  • callback (function) – the callback
  • array (array) – the array
Returns:

array of values, keys are preserved

Return type:

array

The function should take one argument (value) and return a value.

array_map(function ($x) { return $x * 2; }, [0, 1, 2, 3]); // double values
array_reduce(callback, array[, initial])

Reduces the values in the array using the callback from left-to-right, optionally starting with a initial value.

Parameters:
  • callback (function) – the callback
  • array (array) – the array
  • initial (any) – the initial value
Returns:

a single value

Return type:

any

The function should take two arguments (carry and value) and return a value.

If no initial value is provided and;

  • the array is empty, an error will be raised.
  • the array contains one value, that value will be returned.
array_reduce(function ($carry, $x) { return $carry + $x; }, [0, 1, 2, 3]); // sum values
array_reverse(array)

Return array in reverse order

Parameters:array (array) – the array
Returns:array in reverse order
Return type:array
array_sort(callback, array[, options])

Returns the array sorted (with index association maintained) using the callback function to determine the order. The sort is not guaranteed to be stable.

Parameters:
  • callback (function) – the callback
  • array (array) – the array
  • options (array) – options array
Returns:

a sorted array

Return type:

array

The following options are available in the options array.

  • keys (boolean) Sort the array based on their keys. The default is false.

The callback function should take two arguments (a and b) and return true if a is less-than b.

array_sort(function ($a, $b) { return $a < $b; }, [2, 3, 1]); // sort
array_sort(function ($a, $b) { return $a > $b; }, [2, 3, 1]); // reverse-sort

Note

Some other languages (eg. javascript and PHP) use a trivalue function (-1, 0, 1) in a similar way in order to determine the order. HSL does not since if needed, a trivalue function may be simulated internally using the provided less-than function. Further some sorting implementation may only need the less-than result hence the greater-than and equality result may be superfluous to establish.

function trivalue($a, $b, $lessthan)
{
        if ($lessthan($a, $b)) return -1;
        if ($lessthan($b, $a)) return 1;
        return 0;
}
count(array)

Counts items in an array.

Parameters:array (array) – the array
Returns:the number of items in array
Return type:number
explode(delimiter, string[, limit = 0])

Splits the string into an array on the delimiter.

Parameters:
  • delimiter (string) – the delimiter
  • string (string) – the string
  • limit (number) – the maximum number of parts returned
Returns:

an array of strings

Return type:

array

explode(" ", "how are you",  2) // ["how","are you"]
explode(" ", "how are you", -2) // ["how are","you"]
implode(glue, array)

Joins the array with the glue.

Parameters:
  • glue (string) – the glue
  • array (array) – the array
Returns:

a string from an array

Return type:

string

in_array(needle, array)

Returns true if nedle is found in the array.

Parameters:
  • needle (any) – the value to match or a callback function
  • array (array) – the array
Returns:

true if needle is found

Return type:

boolean

The needle function should take one argument (the current item) and return a boolean value.

range(start, stop[, step = 1])

Returns an array from a numeric range (inclusive) with the given steps.

Parameters:
  • start (number) – the first number
  • stop (number) – the last number (that will occur)
  • step (number) – the step between numbers
Returns:

an array with numbers

Return type:

array

foreach (range(0, 9) as $i) // 0,1,2,..,9
      echo $i;

6.2. Cryptographic

hmac_md5(key, s)

Return the HMAC MD5 hash of s with the key.

Parameters:
  • key (string) – the HMAC key
  • s (string) – the value to hash
Returns:

the hash value hex encoded

Return type:

string

hmac_sha1(key, s)

Return the HMAC SHA1 hash of s with the key.

Parameters:
  • key (string) – the HMAC key
  • s (string) – the value to hash
Returns:

the hash value hex encoded

Return type:

string

md5(s)

Return the MD5 hash of s.

Parameters:s (string) – the value to hash
Returns:the hash value hex encoded
Return type:string
sha1(s)

Return the SHA1 hash of s.

Parameters:s (string) – the value to hash
Returns:the hash value hex encoded
Return type:string
hash(string)

Return the numeric hash value of the input string. The hash value is same for equal strings.

Parameters:string (string) – string to be hashed
Returns:a hash value
Return type:number

6.3. Data types

array([...])

This function creates an array.

Parameters:any (any) – the input
Returns:an array
Return type:array

Note

array is not a function, it’s a language construct to create an array type. It’s an alias for the short array syntax [].

number(x)

This function converts the input of x to the number type.

Parameters:x (any) – the input
Returns:a number
Return type:number
string(x)

This function converts the input of s to the string type, hence converting it to its string representation.

Parameters:x (any) – the input
Returns:a string
Return type:string
is_array(a)

Returns true if the type of a is an array.

Parameters:a (any) – the input
Returns:the result
Return type:boolean
is_function(f)

Returns true if the type of f is a function.

Parameters:f (any) – the input
Returns:the result
Return type:boolean
is_number(n)

Returns true if the type of n is a number.

Parameters:n (any) – the input
Returns:the result
Return type:boolean
is_string(s)

Returns true if the type of s is a string.

Parameters:s (any) – the input
Returns:the result
Return type:boolean
isset(x)

Returns true if the variable is defined.

Note

This is not a regular function. It’s a language construct and will only accept variables as input.

Parameters:x (variable) – a variable
Returns:the result
Return type:boolean
unset(x)

Unsets the variable or array index of x, it return true if the variable or array index was defined.

Note

This is not a regular function. It’s a language construct and will only accept variables as input.

Parameters:x (variable) – a variable
Returns:if x was unset
Return type:boolean

6.4. Date and time

executiontime()

Return the elapsed time since the beginning of the code execution.

Returns:the time in seconds (with decimals)
Return type:number
rand(x, y)

Return a random integer between x and y (inclusive).

Parameters:
  • x (number) – first possible number
  • y (number) – last possible number
Returns:

the random number

Return type:

number

sleep(x)

Pause the code execution for x seconds.

Parameters:x (number) – the number of seconds to sleep
Returns:the time slept in seconds (with decimals)
Return type:number
strftime(format)

Format according to the strftime manual with the time without timezone.

echo strftime("%H:%M:%S"); // prints current time eg "13:58:38"
Parameters:format (string) – the format string
Returns:the time formatted (max length 100)
Return type:string
time()

Return elapsed seconds (unix time) since 1970-01-01T00:00:00Z without timezone.

Returns:the time in seconds (with decimals)
Return type:number
timelocal()

Return elapsed seconds (unix time) since 1970-01-01T00:00:00Z with timezone.

Returns:the time in seconds (with decimals)
Return type:number
uptime()

Return the monotonic time since system boot. Monotonic time is by definition suitable for relative time keeping, in contrast to time(). If you want to obtain the script execution time use executiontime().

Returns:the time in seconds (with decimals)
Return type:number

6.5. DNS

dns(name[, options])

Query for the A and AAAA record of a hostname.

Parameters:
  • query (string) – the query
  • options (array) – options array
Returns:

list of items or an extended result

Return type:

array

The following options are available in the options array.

  • timeout (number) Query timeout in seconds. The default is 5.
  • extended_result (boolean) Get a more extended result. The default is false.
  • servers (array) List of resolvers. The default is the system wide.

In the extended_result mode, either result or error in set in an associative array. dnssec is always included. result is the list of results and error is the string representation of rcode or h_errno.

echo dns("nxdomain.halon.se");
// []
echo dns("nxdomain.halon.se", ["extended_result" => true]);
// ["error"=>"NXDOMAIN","dnssec"=>0]

echo dns("halon.se");
// [0=>"54.152.237.238"]
echo dns("halon.se", ["extended_result" => true]);
// ["result"=>[0=>"54.152.237.238"],"dnssec"=>0]
dns4(name[, options])

Query the resolvers for the A record of the hostname.

Parameters:
  • query (string) – the query
  • options (array) – options array
Returns:

list of items or an extended result

Return type:

array

The following options are available in the options array.

  • timeout (number) Query timeout in seconds. The default is 5.
  • extended_result (boolean) Get a more extended result. The default is false.
  • servers (array) List of resolvers. The default is the system wide.

In the extended_result mode, either result or error in set in an associative array. dnssec is always included. result is the list of results and error is the string representation of rcode or h_errno.

dns6(name[, options])

Query the resolvers for the AAAA record of the hostname.

Parameters:
  • query (string) – the query
  • options (array) – options array
Returns:

list of items or an extended result

Return type:

array

The following options are available in the options array.

  • timeout (number) Query timeout in seconds. The default is 5.
  • extended_result (boolean) Get a more extended result. The default is false.
  • servers (array) List of resolvers. The default is the system wide.

In the extended_result mode, either result or error in set in an associative array. dnssec is always included. result is the list of results and error is the string representation of rcode or h_errno.

dnscname(name[, options])

Query the resolvers for the CNAME record of the hostname.

Parameters:
  • query (string) – the query
  • options (array) – options array
Returns:

list of items or an extended result

Return type:

array

The following options are available in the options array.

  • timeout (number) Query timeout in seconds. The default is 5.
  • extended_result (boolean) Get a more extended result. The default is false.
  • servers (array) List of resolvers. The default is the system wide.

In the extended_result mode, either result or error in set in an associative array. dnssec is always included. result is the list of results and error is the string representation of rcode or h_errno.

dnsmx(name[, options])

Query the resolvers for the MX record of the hostname.

Parameters:
  • query (string) – the query
  • options (array) – options array
Returns:

list of items or an extended result

Return type:

array

The following options are available in the options array.

  • timeout (number) Query timeout in seconds. The default is 5.
  • extended_result (boolean) Get a more extended result. The default is false.
  • servers (array) List of resolvers. The default is the system wide.

In the extended_result mode, either result or error in set in an associative array. dnssec is always included. result is the list of results and error is the string representation of rcode or h_errno.

dnsptr(name[, options])

Query the resolvers for the PTR record of the address.

Parameters:
  • query (string) – the query
  • options (array) – options array
Returns:

list of items or an extended result

Return type:

array

The following options are available in the options array.

  • timeout (number) Query timeout in seconds. The default is 5.
  • extended_result (boolean) Get a more extended result. The default is false.
  • servers (array) List of resolvers. The default is the system wide.

In the extended_result mode, either result or error in set in an associative array. dnssec is always included. result is the list of results and error is the string representation of rcode or h_errno.

dnstxt(name[, options])

Query the resolvers for the TXT record of the hostname.

Parameters:
  • query (string) – the query
  • options (array) – options array
Returns:

list of items or an extended result

Return type:

array

The following options are available in the options array.

  • timeout (number) Query timeout in seconds. The default is 5.
  • extended_result (boolean) Get a more extended result. The default is false.
  • servers (array) List of resolvers. The default is the system wide.

In the extended_result mode, either result or error in set in an associative array. dnssec is always included. result is the list of results and error is the string representation of rcode or h_errno.

is_subdomain(d, domain)

Test if d is subdomain of domain. If the domain starts with a dot . it must be a subdomain of domain, hence it will not even if d == domain.

is_subdomain("www.halon.io", "halon.io"); // true
is_subdomain("halon.io", "halon.io"); // true
is_subdomain("www.halon.io", ".halon.io"); // true
is_subdomain("halon.io", ".halon.io"); // false
Parameters:
  • d (string) – the subdomain
  • domain (string) – the domain
Returns:

if d is a subdomain of domain

Return type:

boolean

6.6. Encodings and JSON

base64_encode(string)

Base64 encode the string.

Parameters:string (string) – the input string
Returns:the base64 representation
Return type:string
base64_decode(string)

Base64 decode the string.

Parameters:string (string) – the input string
Returns:the string representation
Return type:string
csv_explode(string)

CSV explode the string.

Parameters:string (string) – CSV formated string
Returns:an array of strings
Return type:array
json_encode(value[, options])

JSON encode a HSL data type.

Parameters:
  • value (any) – HSL data type
  • options (array) – options array
Returns:

a JSON representation of value

Return type:

string

The following options are available in the options array.

  • ensure_ascii (boolean) Convert all non-ASCII characters (UTF-8) to unicode (\uXXXX). The default is true.
  • pretty_print (boolean) Pretty print the JSON output. The default is false.

Encode an array, number or string into a JSON representation (string). The encoding distinguishes arrays from objects if they are sequentially numbered from zero. On encoding errors an object with the data type of undefined is returned. All non-ASCII characters will be escaped as Unicode code points (\uXXXX).

Note

Since object keys are converted to strings (even numeric once) a json_encode() followed by a json_decode() does not always yield the same result.

json_decode(string)

Decodes a JSON string into a HSL data type.

Parameters:string (string) – JSON serialized data
Returns:the decoded string as the correct type, and on errors None is returned
Return type:any

The following translations are done (JSON to HSL).

  • object to associative array (is_array)
  • array to array (is_array)
  • string to string (is_string)
  • number to number (is_number)
  • true to 1 (is_number)
  • false to 0 (is_number)
  • null to none (check for expected type instead)

6.7. File and HTTP

The filename may point to a file in the configuration file:X or a file relative on the accessible filesystem file://filename.txt.

file(filename)

Return the content of the filename as an array line by line (without CR/LF).

Parameters:filename (string) – the file name
Returns:the file content as an array
Return type:array
file_get_contents(filename)

Return the content of the filename as a string.

Parameters:filename (string) – the file name
Returns:the file content as a string
Return type:string
in_file(needle, filename[, options])

Searches for a needle at the beginning (or at index) of each line in filename. If found, the line is returned as an array separated by the delimiter.

Parameters:
  • needle (any) – the string to match or a callback function
  • filename (string) – the file name
  • options (array) – options array
Returns:

if word is found in string, return all words on that line as an array

Return type:

array

The following options are available in the options array.

  • type (string) may be text/plain or text/csv. In text/csv mode the delimiter is changed to , and the first line may be used as index. The default type is text/plain.
  • delimiter (string) separates words. The default is a white space for text/plain and , for text/csv.
  • assoc (boolean) in text/csv mode the first line may be used as associative index for the returned array. The default is true.
  • index (number) the word index to search for (indexed at zero). The default is 0 (the first word).

The needle function should take one argument (the line, as an array of words) and return a boolean value.

Note

Example using a CSV file; below is the content of file:1:

ip,comment
192.168.1.25,webserver
192.168.1.26,mailserver
$infile = in_file($senderip, "file:1", ["type" => "text/csv"]);
if ($infile) {
        // e.g. ["ip" => "192.168.1.26", "comment" => "mailserver"]
}
$infile = in_file(function ($v) {
                                global $senderip;
                                return $v["ip"] == $senderip;
                        }, "file:1", ["type" => "text/csv"]);
http(url, [options, [get, [post]]]])

Make HTTP/HTTPS request to a URL and return the content

Parameters:
  • url (string) – URL to request
  • options (array) – options array
  • get (array) – GET variables, replaced and encoded in URL as $1, $2...
  • post (array or string) – POST data as an array or a string for raw POST data
Returns:

if the request was successful (2XX) the content is returned, otherwise the type None is returned

Return type:

string or array

The following options are available in the options array.

  • extended_result (boolean) Get a more extended result. The default is false.
  • connect_timeout (number) Connection timeout (in seconds). The default is 10 seconds.
  • timeout (number) Timeout (in seconds) waiting for data once the connection is established. The default is to wait indefinitely.
  • method (string) Request method. The default is GET unless POST data is sent.
  • headers (array) An array of additional HTTP headers.
  • response_headers (boolean) Return the full request, including response headers (regardless of HTTP status). The default is false.
  • ssl_verify_peer (boolean) Verify SSL peer. The default is true.
  • ssl_verify_host (boolean) Verify certificate hostname (CN). The default is false.
  • ssl_default_ca (boolean) Load additional TLS certificates (ca_root_nss). The default is false.
  • background (boolean) Perform request in the background. In which case this function returns None. The default is false.
  • background_hash (number) Assign this request to a specific queue. If this value is higher than the number of queues, it’s chosen by modulus. The default is queue 0.
  • background_retry_count (number) Number of retry attempts made after the initial failure. The default is 0.
  • background_retry_delay (number) The delay, in seconds, before each retry attempt. The default is 0 seconds.

If the option extended_result result is true. This function will return an array containing the status code and content. If no valid HTTP response is receivied None is return.

$response = http("http://halon.io/", ["extended_result" => true]);
if ($response) {
        echo $response;
}

6.8. Mail

dnsbl(ip, hostname[, resolvers[, timeout = 5]])

Query the resolvers for the DNSBL status of an address. If no resolvers are given, the system default is used.

Parameters:
  • ip (string) – IP or IPv6 address to check
  • hostname (string) – in DNSBL list
  • resolvers (array) – list of resolvers
  • timeout (number) – timeout in seconds
Returns:

list of IP addresses

Return type:

array

This function works by reversing the IP addresses octets and appending to the hostname parameter.

spf(ip, helo, domain)

Check the SPF status of the senderdomain.

Parameters:
  • ip (string) – IP or IPv6 address to check
  • helo (string) – HELO/EHLO host name
  • domain (string) – domain too lookup
Returns:

0 if the addresses passed, 20 for softfail, 50 if the status is unknown and 100 if the spf failed.

Return type:

number

globalview(ip)

Check the Cyren Glovalview reputation for an IP.

Parameters:ip (string) – IP or IPv6 address to check
Returns:the recommended action to take for the ip accept, tempfail or permfail.
Return type:string

6.9. Mathematical

abs(x)

Return the absolute value of a number.

Parameters:x (number) – the numeric value to process
Returns:the absolute value of x
Return type:number
ceil(x)

Return the integer value of a number by rounding up if necessary.

Parameters:x (number) – the numeric value to process
Returns:the integer value of x
Return type:number
floor(x)

Return the integer value of a number by rounding down if necessary.

Parameters:x (number) – the numeric value to process
Returns:the integer value of x
Return type:number
log(x[, y = e])

Return the logarithm of base x and exponent y.

Parameters:
  • x (number) – the numeric value to process
  • y (number) – the base
Returns:

the logarithm value of x to base y

Return type:

number

pow(x, y)

Return base x raised to the power of the exponent y.

Parameters:
  • x (number) – the numeric value to process
  • y (number) – the exponent
Returns:

the x to power of y

Return type:

number

See also

It’s significantly faster to use the ** operator since it’s an operator and not a function.

round(x[, y = 0])

Return x rounded to precision of y decimals.

Parameters:
  • x (number) – the numeric value to process
  • y (number) – the number of decimals
Returns:

the value x rounded to y

Return type:

number

sqrt(x)

Return the square root of x.

Parameters:x (number) – the numeric value to process
Returns:the square root of x
Return type:number

6.10. MIME

class MIME

The MIME object “constructor” takes no function arguments, and returns a new MIME object.

The standard library’s MIME object is a “string builder” to construct MIME parts. In the DATA context there is an similar MIME object as well, which is useful to work with a message’s MIME parts. To create a “string building” MIME object, call the MIME function without any arguments.

$part = MIME();
$part->setType("multipart/alternative");
$part->appendPart(MIME()->setType("text/plain")->setBody("*Hello World*"));
$part->appendPart(MIME()->setType("text/html")->setBody("<strong>Hello World</strong>"));
echo $part->toString();

Note

Many of the MIME object’s member functions return this, allowing them to be called with method chaining.

echo MIME()->addHeader("Subject", "Hello")->setBody("Hello World")->toString();
addHeader(name, value)

Add a header. The value may be encoded (if needed) and reformatted.

Parameters:
  • name (string) – name of the header
  • value (string) – value of the header
Returns:

this

Return type:

MIME

Note

If a Content-Type header is added, the value of MIME.setType() is ignored. If a Content-Transfer-Encoding header is added no encoding will be done on data added by MIME.setBody().

appendPart(part)

Add a MIME part (child) object, this is useful when building a multipart MIME.

Parameters:part (MIME) – a MIME part object
Returns:this
Return type:MIME

Note

The Content-Type is not automatically set to multipart/*, this has to be done using MIME.setType(). The MIME boundary is however automatically created.

setBody(data)

Set the MIME part body content. In case the MIME part has children (multipart) this will be the MIME parts preamble. The data will be Base64 encoded if no Content-Transfer-Encoding header is added.

Parameters:data (string) – the data
Returns:this
Return type:MIME
setType(type)

Set the type field of the Content-Type header. The default type is text/plain, and the charset is always utf-8.

Parameters:type (string) – the content type
Returns:this
Return type:MIME
setBoundary(boundary)

Set the MIME boundary for multipart/* messages. The default is to use an UUID.

Parameters:boundary (string) – the boundary
Returns:this
Return type:MIME
toString()

Return the created MIME as a string. This function useful for debugging.

Returns:the MIME as string
Return type:string
send(sender, recipient, transportid[, options])

Send the MIME as an email to the recipient.

Parameters:
  • sender (string) – the sender
  • recipient (string) – the recipient
  • transportid (string) – the transportid
  • options (array) – options array
Returns:

the message id

Return type:

string

The following options are available in the options array.

  • metadata (array) Add additional metadata to the message (KVP).
MIME()
        ->addHeader("Subject", "Hello")
        ->setBody("Hi, how are you?")
        ->send("", "info@example.com", "mailtransport:1");

6.11. Misc

serial()

The serial number of the installation, this can be used to identify a software instance.

Returns:the serial number
Return type:string
gethostname()

The hostname of the installation, this can be used to identify a software instance.

Returns:the hostname
Return type:string
uuid()

Return a unique ID.

Returns:a unique ID
Return type:string
echo()

Print a message to the log.

echo "Log message";

Note

echo is not a function, therefore do not call it with parentheses, all messages are logged as syslog() level debug, with $messageid prefixed.

syslog(priority, message)

The syslog function complements the echo statement by allowing messages with custom priorities to be logged.

Parameters:
  • priority (string or number) – message priority
  • message (string) – message
Return type:

none

Priority may be any of

Name  
emerg 0
alert 1
crit 2
err 3
warning 4
notice 5
info 6
debug 7

Note

If you want your log message to appear when the message log is viewed (as it does with echo(), you should prefix the message parameter with "[$messageid] ".

stat(name, legends)

Collect statistics based on one or more legend (value). The name is the name of the graph (the collection of legends). A legend is a value for which the system should collect statistics.

Parameters:
  • name (string) – name of the graph
  • legends (array) – key value pair of legends
Return type:

none

Values stat’ed are available

  • as a line graph (on the graphs and report page)
  • as a pie chart (on the graphs and report page)
  • using the statList and graphFile SOAP API call.
  • using SNMP

In order for the line graph to work properly, all values should be defined to the stat function on every stat call (even if they are not increased).

$fam4 = 0; $fam6 = 0;
if (in_network($senderip, "0.0.0.0/0")) { $fam4 = 1; } else { $fam6 = 1; }
stat("ip-family", ["ipv4" => $fam4, "ipv6" => $fam6]);

Note

You can only use “a-z0-9.-” in the name and “a-z0-9-” in the legends (legends longer than 19 characters will be truncated on the graph page) when using the stat function. For example, uppercase letters are not allowed.

in_network(ip, network)

Returns true if ip is in the subnet of network.

Parameters:
  • ip (string) – IP or IPv6 address
  • network (string) – address, subnet or range.
Returns:

true if ip is in network

Return type:

boolean

in_network("127.0.0.1", "127.0.0.1/8");
in_network("127.0.0.1", "127.0.0.0-127.255.255.255");
in_network("127.0.0.1", "127.0.0.1");
rate(namespace, entry, count, interval)

Check or account for the rate of entry in namespace during the last interval.

Parameters:
  • namespace (string) – the namespace
  • entry (string) – an entry
  • count (number) – the count
  • interval (number) – the interval in seconds
Returns:

if count is greater than zero, it will increase the rate and return true, or return false if the limit is exceeded. If count is zero 0, it will return the number of items during the last interval.

Return type:

number

if (rate("outbound", $saslusername, 3, 60) == false) {
                Reject("User is only allowed to send 3 messages per minute");
}

Note

Rates are shared between all contexts, and may also be synchronized in clusters.

mail(sender, recipient, subject, body[, options])

Send an email to recipient.

Parameters:
  • sender (string) – the sender
  • recipient (string) – the recipient
  • subject (string) – the subject
  • body (string) – the body
  • options (array) – options array
Returns:

the message id

Return type:

string

The following options are available in the options array.

  • sender_name (string) Friendly name of the sender.
  • recipient_name (string) Friendly name of the recipient.
  • serverid (string) Helps the decision making of where we should send this email.
  • transportid (string) Set the transportid to be used with this message.
  • plaintext (boolean) Send message as plain/text (default is text/html). The default is false.
  • rawbody (boolean) Instead of using a template, send body as raw text. The default is false.
  • headers (array) Add additional message headers (KVP).
  • metadata (array) Add additional metadata to the message (KVP).
mail("postmaster@example.com", "support@halon.se", "Lunch", "How about lunch on Friday?");

6.12. Protocols

smtp_lookup_rcpt(server, sender, recipient[, options])

Check if sender is allowed to send mail to recipient.

Parameters:
  • server (string or array) – array with server settings or mailtransport profile
  • sender (string) – the sender (MAIL FROM)
  • recipient (string) – the recipient (RCPT TO)
  • options (array) – options array
Returns:

1 if the command succeeded, 0 if the command failed and -1 if an error occurred. The error_code option may change this behavior.

Return type:

number or array

The following server settings are available in the server array.

  • host (string) IP-address or hostname. required
  • port (number) TCP port. The default is 25.
  • helo (string) The default is to use the system hostname.
  • sourceip (string) Explicitly bind a netaddr:X or an IP address. The default is auto.
  • saslusername (string) If specified issue a AUTH LOGIN before RCPT TO.
  • saslpassword (string) If specified issue a AUTH LOGIN before RCPT TO.
  • tls (string) Use any of the following TLS modes; disabled, optional, optional_verify, dane, dane_require, require or require_verify. The default is disabled.
  • tls_protocols (string) Use one or many of the following TLS protocols; SSLv1, SSLv2, TLSv1, TLSv1.1 or TLSv1.2. Protocols may be separated by , and excluded by !. The default is !SSLv2,!SSLv3.
  • tls_ciphers (string) List of ciphers to support. The default is decided by OpenSSL for each tls_protocol.

The following options are available in the options array.

  • error_code (boolean) If error_code is true and associative array with “error_code” and “error_message” is returned. The default is false.
smtp_lookup_auth(server, username, password)

Try to authenticate the username against a SMTP server.

Parameters:
  • server (string or array) – array with server settings or mailtransport profile
  • username (string) – username
  • password (string) – password
  • options (array) – options array
Returns:

1 if the authentication succeeded, 0 if the authentication failed and -1 if an error occurred.

Return type:

number

The following server settings are available in the server array.

  • host (string) IP-address or hostname. required
  • port (number) TCP port. The default is 25.
  • helo (string) The default is to use the system hostname.
  • sourceip (string) Explicitly bind a netaddr:X or an IP address. The default is auto.
  • tls (string) Use any of the following TLS modes; disabled, optional, optional_verify, dane, dane_require, require or require_verify. The default is disabled.
  • tls_protocols (string) Use one or many of the following TLS protocols; SSLv1, SSLv2, TLSv1, TLSv1.1 or TLSv1.2. Protocols may be separated by , and excluded by !. The default is !SSLv2,!SSLv3.
  • tls_ciphers (string) List of ciphers to support. The default is decided by OpenSSL for each tls_protocol.
dovecot_lookup_auth(options, username, password)

Try to authenticate the username against a dovecot server.

Parameters:
  • options (array) – options array
  • username (string) – username
  • password (string) – password
Returns:

1 if the authentication succeeded, 0 if the authentication failed and -1 if an error occurred.

Return type:

number

The following options are available in the options array.

  • host (string) IP-address or hostname of the dovecot server. required
  • port (number) TCP port. required
  • timeout (number) Timeout in seconds. The default is 5 seconds.

There are also some protocol specific flags that may be configured.

  • service (string) Service name to identify this request. The default is smtp.
  • rip (string) The IP-address of the client (remote IP).
  • lip (string) The IP-address of the Halon (local IP).
  • secured (boolean) Set to true if the client has tlsstarted. The default is false.

Query an LDAP server for lookup and return all LDAP entries found.

Parameters:
  • profile (string) – ldap profile
  • lookup (string) – query that will be inserted into the ldap query (ldapescaped)
  • override (array) – options array
Returns:

an array with LDAP entries or -1 if an error occurred.

Return type:

array or number

The following overrides are available in the override array.

  • host (string) IP-address or hostname.
  • username (string) LDAP username.
  • password (string) LDAP password.
  • base (string) LDAP base.
  • query (string) LDAP query (unescaped).
ldap_bind(profile, username, password[, override])

Try to bind (authenticate) against an LDAP server.

Parameters:
  • profile (string) – ldap profile
  • username (string) – LDAP username
  • password (string) – LDAP password
  • override (array) – options array
Returns:

1 if the authentication succeeded, 0 if the authentication failed and -1 if an error occurred.

Return type:

number

The following overrides are available in the override array.

  • host (string) IP-address or hostname.
radius_authen(options, username, password[, vendorstrings])

Authenticate against a RADIUS server.

Parameters:
  • options (array) – options array
  • username (string) – username
  • password (string) – password
  • vendorstrings (array) – array of vendor strings
Returns:

1 if the authentication succeeded, 0 if the authentication failed and -1 if an error occurred.

Return type:

number

The following options are available in the options array.

  • host (string) IP-address or hostname of the RADISU server. required
  • secret (string) The secret. required
  • port (number) TCP port. The default is 1812.
  • timeout (number) Timeout in seconds. The default is 5 seconds.
  • clientip (string) The IP-address of the client (remote IP).
  • retry (number) The retry count is 3.

Vendor strings must be strings and must be registered as ID 33234 (Halon Security’s Enterprise Number)

tacplus_authen(options, username, password)

Authenticate against a TACACS+ server (e.g. Cisco Secure ACS).

Parameters:
  • options (array) – options array
  • username (string) – username
  • password (string) – password
Returns:

1 if the authentication succeeded, 0 if the authentication failed and -1 if an error occurred.

Return type:

number

The following options are available in the options array.

  • host (string) IP-address or hostname of the TACACS+ server. required
  • secret (string) The secret. required
  • port (number) TCP port. The default is 49.
  • timeout (number) Timeout in seconds. The default is 5 seconds.
  • clientip (string) The IP-address of the client (remote IP).
tacplus_author(options, username, avpair)

Send an authorization request to a TACACS+ server.

Parameters:
  • options (array) – options array
  • username (string) – username
  • avpair (array) – an array of avpairs
Returns:

an array with avpairs entries if the authorization succeeded, 0 if the authorization failed and -1 if an error occurred.

Return type:

array or number

The following options are available in the options array.

  • host (string) IP-address or hostname of the TACACS+ server. required
  • secret (string) The secret. required
  • port (number) TCP port. The default is 49.
  • timeout (number) Timeout in seconds. The default is 5 seconds.
  • clientip (string) The IP-address of the client (remote IP).

6.13. String

chr(c)

Returns ASCII character of number c.

Parameters:c (number) – the ASCII number
Returns:string from ASCII value c
Return type:string
str_repeat(s, n)

Returns the string s repeated n times.

Parameters:
  • s (string) – the input string
  • n (number) – the string multiplier
Returns:

s repeated n times

Return type:

string

str_replace(search, replace, subject)

Returns the string subject with the string search replace with replace.

Parameters:
  • search (string) – the search string
  • replace (string) – the replace string
  • subject (string) – the string acted upon
Returns:

subject with searched replaced with replace

Return type:

string

strlen(s)

Returns the length of the string s.

Parameters:s (string) – the input string
Returns:the length of s
Return type:number
strpos(s, find[, offset = 0])

Return the position (starting from zero) of the first occurrence of find in s (starting from the offset). If the find is not found -1 is returned.

Parameters:
  • s (string) – the input string
  • find (string) – the string to look for
  • offset (number) – the offset from the start
Returns:

the position where find is found

Return type:

number

strrpos(s, find[, offset = 0])

Return the position (starting from zero) of the last occurrence of find in s searching backward (starting from the offset relative to the end). If the find is not found -1 is returned.

Parameters:
  • s (string) – the input string
  • find (string) – the string to look for
  • offset (number) – the offset from the end
Returns:

the position where find is found

Return type:

number

strtolower(s)

Returns s with all US-ASCII character to lowercased.

Parameters:s (string) – the input string
Returns:the string lowercased
Return type:string
strtoupper(s)

Returns s with all US-ASCII character uppercased.

Parameters:s (string) – the input string
Returns:the string uppercased
Return type:string
substr(s[[, start = 0], len])

Return the substring of s.

Parameters:
  • s (string) – the input string
  • start (string) – the start position
  • len (number) – the length limit if given
Returns:

the substring

Return type:

string

trim(s)

Returns s with whitespace characters removed from the start and end of the string.

Parameters:s (string) – the input string
Returns:the trimmed string
Return type:string
pcre_match(pattern, subject)

PCRE matching in subject.

Parameters:
  • pattern (string) – the regular expression
  • subject (string) – the string to match against
Returns:

returns matches if no result is found, an empty array is returned.

Return type:

array

Perl compatible regular expression data matching and extraction, requires capture groups. All modifiers supported by =~ operator are available.

Note

Use raw strings so you don’t have to escape the pattern.

See also

For matching only the regular expression operator can be used.

pcre_match_all(pattern, subject)

The implementation is identical to pcre_match() except the return type.

Parameters:
  • pattern (string) – the regular expression
  • subject (string) – the string to match against
Returns:

returns multiple results group by capture groups, and matched result.

Return type:

array

pcre_quote(string)

Quote all metacharacters which has special meaning in a regular expression.

Parameters:string (string) – the string
Returns:a quoted string
Return type:string
pcre_replace(pattern, replace, subject[, limit = 0])

Perl compatible regular expression data matching and replacing

Parameters:
  • pattern (string) – the regular expression to match
  • replace (any) – the pattern to replace as string or a callback function
  • subject (string) – the string acted upon
  • limit (number) – max occurrences to replace (0 equals unlimited)
Returns:

return subject with the replacements done

Return type:

string

In replace matches are available using $0 to $n. $0 will be the entire match, and $1 (and forward) each match group.

The replace function should take one argument (array of values [$0, $n...]) and return a string value.

echo pcre_replace("\\[link](.*?)\\[/link]",
        "<a href=\"$1\">$1</a>",
                        "[link]http://halon.se[/link]");
// <a href="http://halon.se">http://halon.se</a>

echo pcre_replace("\\d", "($0)", "foo1bar2baz");
// foo(1)bar(2)baz

// "ucfirst()"
echo pcre_replace(''\b[a-z]'', function ($i) { return strtoupper($i[0]); }, "hello world");
// Hello World