Builtin functions

Functional constraint

Deval’s ability to evaluate code at compilation or delay it to runtime relies on template code not having any side-effect. Side-effects would make evaluation not predictable by depending on inputs that Deval have no control on, and therefore could break your templates by producing different results depending on when or in which order functions are evaluated. This is why the template language and all Deval flavor functions are pure.

Deval has no way to make sure functions you inject are pure, so this responsibility is left to the developer. Remember it’s technically possible to inject non-pure functions into a Deval template but you’ll most probably break something if you do so, unless you really know what you’re doing.

List of builtin functions

Deval offers two predefined “flavors” of builtin functions you can inject:

Preferred “deval” flavor: a minimal set of pure functions you can safely use in your templates without any risk of unexpected behavior ;
Alternative “php” flavor: all standard PHP functions made directly available in your templates. Make sure you only use the pure ones, otherwise you may experience unreliable results as explained above.

To inject builtin functions into your template, use the same Deval\Renderer::inject method we saw in previous sections:

// Inject "deval" flavor builtin functions into your template
$renderer->inject(Deval\Builtin::deval());

// or

// Inject "php" flavor builtin functions into your template
$renderer->inject(Deval\Builtin::php());

Deval flavor functions

Following functions are available in Deval\Builtin::deval flavor:

array(value1[, value2[, ...]])

Convert parameters into arrays and merge them together. This function can be used to cast any value to an array (equivalent to PHP’s (array) cast) and/or concatenate several values as a single array.

Parameters:: valueN (mixed) – any value
Returns:: concatenated parameters $valueN after converting them to arrays

bool(value)

Convert input value into boolean, just like a PHP boolean cast would do.

Parameters:: value (mixed) – any value
Returns:: input value converted to boolean

cat(value1[, value2[, ...]])

Concatenate arrays or strings (all arguments will be treated as arrays or strings depending on the type of first argument).

Parameters:: valueN (mixed) – string or array
Returns:: concatenated values

compare(value1, value2)

Compare two values and return -1 if first one is lower than second one, 1 if first one is greater than second one, or 0 otherwise. When used on numeric values comparison uses numerical order. When used on strings comparison uses alphabetical order. Two values of different types are always different but the order between them is undefined.

Parameters:: valueN (mixed) – any value
Returns:: comparison order

default(value, fallback)

Shorthand function to test whether a value is defined and not null.

Parameters:: value (mixed) – input value
Returns:: value if defined and not null, fallback otherwise

filter(items[, predicate])

Filter items from an array based on a predicate. If predicate is not specified then (item) => bool(item) is used, meaning function will return an array with all items which are equivalent to true using PHP boolean casting rules.

Parameters:

items (any_array) – input items
predicate (function) – predicate callback

Returns:

array of all items for which predicate(item) is true

find(items[, predicate])

Find first item from an array matching given predicate. If predicate is not specified then (item) => true is used, meaning function will return first item from the array.

Parameters:

items (any_array) – input items
predicate (function) – predicate callback

Returns:

first item from array for which predicate(item) is true

flip(items)

Return an array where keys and values have been swapped (similar to PHP function array_flip).

Parameters:: items (any_array) – input items
Returns:: array with swapped keys and values

float(value)

Convert input value into floading point number, just like a PHP float cast would do.

Parameters:: value (mixed) – any value
Returns:: input value converted to floating point number

group(items[, get_key[, get_value[, initial]]])

Group array items by key and merge together values sharing the same key. This function will process every key and value from input array items and apply get_key(item.value, item.key) to compute grouping key, then get_value(aggregate, item.value) to compute aggregated value. In case two or more items share the same key, get_value will be called with initial as first argument then each subsequent call receives aggregated value resulting from previous call.

This very versatile function can be used in multiple situations depending on the callbacks you specify. Here are a few examples:

Parameters:

items (any_array) – input items
get_key (function) – key transform callback receiving item’s value and key as arguments ; returns value if not specified
get_value (function) – value transform callback receiving current aggregate for this item’s computed key and value as arguments ; returns value if not specified
initial (any) – initial aggregate passed as first argument of get_value for the first item of each group ; null if not specified

Returns:

grouped array

{{ $ group(values) /* keep distinct values */ }}
{{ $ group(users, (user) => user.id) /* index users by ID */ }}
{{ $ group(books, (book) => book.author, (books, book) => cat(books, [book]), []) /* group books by author */ }}

int(value)

Convert input value into integer number, just like a PHP int cast would do.

Parameters:: value (mixed) – any value
Returns:: input value converted to integer number

join(items[, separator])

Join array items together in a string using an optional separator (similar to PHP function implode).

Parameters:

items (any_array) – input items
separator (string) – separator, empty string is used if undefined

Returns:

joined array items as a single string

keys(items)

Extract keys from array and make another array out of them (similar to PHP function array_keys).

Parameters:: items (any_array) – input items
Returns:: input item keys

length(value)

Return length of an array (number of items) or a string (number of characters).

Parameters:: value (mixed) – input array or string
Returns:: length of input value

map(items, apply)

Returns an array after applying given callback to all its values, leaving keys unchanged (similar to PHP function array_map).

Parameters:: items (any_array) – input items
Returns:: array of (key, apply(value)) pairs

max(value1[, value2[, ...]])

Returns highest value in given array when given a single argument, or highest argument when given more than one (similar to PHP function max).

Parameters:: valueN (mixed) – array (if one argument) or scalar value (if more)
Returns:: greatest value or argument

min(value1[, value2[, ...]])

Returns lowest value in given array when given a single argument, or lowest argument when given more than one (similar to PHP function min).

Parameters:: valueN (mixed) – array (if one argument) or scalar value (if more)
Returns:: lowest value or argument

php(symbol)

Access PHP global variable, constant or function by name. Prepend “#” to name to access a constant or “$” to access a variable. Class members can be accessed by prepending their namespace followed by “::” to the symbol name. This function allows you to escape from a safe pure context, so all precautions listed in Functional constraint section apply to it.

Parameters:: symbol (string) – name of the symbol to access
Returns:: symbol value

{{ $ php("implode")(",", [1, 2]) /* access PHP function */ }}
{{ $ php("#PHP_VERSION") /* access PHP constant */ }}
{{ $ php("$_SERVER")["PHP_SELF"] /* access PHP variable */ }}
{{ $ php("My\\SomeClass::$field") /* access class variable */ }}
{{ $ php("OtherClass::#VALUE") /* access class constant */ }}

range(start, stop[, step])

Build a sequence of numbers between given boundaries (inclusive), using a step increment between each value (similar to PHP function range).

Parameters:

start (integer) – first value of the sequence
stop (integer) – last value of the sequence
step (integer) – increment between numbers, 1 will be used in not specified

Returns:

sequence array

reduce(items, callback[, initial])

Reduce array items to a scalar value using a callback function (similar to PHP function array_reduce).

Parameters:

items (any_array) – input items
callback (function) – callback function producing result from aggregated value and current item value
initial (mixed) – value used as initial aggregate, null if not specified

Returns:

final aggregated value

replace(value, replacements)

Replace all occurrences of replacements keys by corresponding values (similar to PHP function str_replace but takes a single key-value array for replacements instead of two separate arrays).

Parameters:

value (string) – original string
replacements (any_array) – replacements key-value pairs

Returns:

string with all keys from replacements replaced

reverse(value)

Reverse elements in an array (similar to PHP function array_reverse) or characters in a string (similar to PHP function strrev).

Parameters:: value (mixed) – input array or string
Returns:: reversed array or string

slice(value, offset[, count])

Extract delimited slice from given array or string starting at given offset.

Parameters:

value (mixed) – input array or string
offset (integer) – beginning offset of extracted slice
count (integer) – length of extracted slice, or extract to the end if not specified

Returns:

extracted array or string slice

sort(items[, compare])

Sort input array using optional comparison callback.

Parameters:

items (any_array) – input items
callback (function) – items comparison function, see usort for specification

Returns:

sorted array

split(string, separator[, limit])

Split string into array using a separator string (similar to PHP function explode).

Parameters:

string (string) – input string
separator (string) – separator string
limit (integer) – maximum number of items in output array

Returns:

array of split strings

str(value)

Convert input value into string, just like a PHP string cast would do.

Parameters:: value (mixed) – any value
Returns:: input value converted to string

values(items)

Extract values from array and make another array out of them (similar to PHP function array_values).

Parameters:: items (any_array) – input items
Returns:: input item values

void()

Empty function which always returns null, for use as a default placeholder in Deval statements.

Returns:: null

zip(keys, values)

Create a key-value array from given list of keys and values (similar to PHP function array_combine). Input arrays keys and values must have the same length for this function to work properly.

Parameters:

keys (any_array) – items to be used as array keys
values (any_array) – items to be used as array values

Returns:

key-value array

PHP flavor functions

If you chose to use Deval\Builtin::php flavor, all standard PHP functions are available in your templates. Proceed with caution! Using any non-pure function e.g. rand could make your template unreliable as you don’t control when exactly it’s going to be called nor how many times.

{{ if strlen(input) == 0 }}
    Please enter a non-empty value!
{{ end }}