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, thenget_value(aggregate, item.value)
to compute aggregated value. In case two or more items share the same key,get_value
will be called withinitial
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
andkey
as arguments ; returnsvalue
if not specifiedget_value (function) – value transform callback receiving current aggregate for this item’s computed key and
value
as arguments ; returnsvalue
if not specifiedinitial (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
andvalues
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 }}