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 must be 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 unpure 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.

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
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[, merge]]])

Group array items together, optionally transforming keys and values and handling key collisions using callback functions. This function will process every key and value from input array and apply specified get_key and get_value callbacks on them, passing them value and key as arguments. Resulting key and value are inserted into output array, using merge callback to resolve conflict when two values share the same key and passing it both previous and current value as arguments.

This very versatile function can be used in multiple situations depending on the callback you specify. For example when used with default callbacks it will act as a “unique” function and remove duplicates, by using values as keys and solving conflicts by keeping first encountered value.

Parameters:
  • items (any_array) – input items
  • get_key (function) – key transform callback, returns value if not specified
  • get_value (function) – value transform callback, returns value if not specified
  • merge (function) – merge conflict handling callback, returns previous value if not specified
Returns:

grouped array

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 */ }}
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

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 functions 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.

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