Latte Functions
***************

.[perex]
In addition to the common PHP functions, you can also use these in templates.

.[table-latte-filters]
| `clamp`      | [clamps value to the range |#clamp]
| `divisibleBy`| [checks if a variable is divisible by a number |#divisibleBy]
| `even`       | [checks if the given number is even |#even]
| `first`      | [returns first element of array or character of string |#first]
| `group`      | [groups data according to various criteria |#group]
| `hasBlock`   | [detects the existence of a block |#hasBlock]
| `last`       | [returns last element of array or character of string |#last]
| `odd`        | [checks if the given number is odd |#odd]
| `slice`      | [extracts a slice of an array or a string |#slice]


Usage
=====

Functions are used in the same way as common PHP functions and can be used in all expressions:

```latte
<p>{clamp($num, 1, 100)}</p>

{if odd($num)} ... {/if}
```

[Custom functions|extending-latte#functions] can be registered this way:

```php
$latte = new Latte\Engine;
$latte->addFunction('shortify', fn(string $s, int $len = 10) => mb_substr($s, 0, $len));
```

We use it in a template like this:

```latte
<p>{shortify($text)}</p>
<p>{shortify($text, 100)}</p>
```


Functions
=========


clamp(int|float $value, int|float $min, int|float $max): int|float .[method]
----------------------------------------------------------------------------
Returns value clamped to the inclusive range of min and max.

```latte
{=clamp($level, 0, 255)}
```

See also [filter clamp|filters#clamp]:


divisibleBy(int $value, int $by): bool .[method]
------------------------------------------------
Checks if a variable is divisible by a number.

```latte
{if divisibleBy($num, 5)} ... {/if}
```


even(int $value): bool .[method]
--------------------------------
Checks if the given number is even.

```latte
{if even($num)} ... {/if}
```


first(string|iterable $value): mixed .[method]
----------------------------------------------
Returns the first element of array or character of string:

```latte
{=first([1, 2, 3, 4])}    {* outputs 1 *}
{=first('abcd')}          {* outputs 'a' *}
```

See also [#last], [filter first|filters#first].


group(iterable $data, string|int|\Closure $by): array .[method]{data-version:3.0.16}
------------------------------------------------------------------------------------
This function groups data according to different criteria.

In this example, the rows in the table are grouped by the column `categoryId`. The output is an array of fields where the key is the value in the column `categoryId`. Read the [detailed instructions |cookbook/grouping].

```latte
{foreach group($items, categoryId) as $categoryId => $categoryItems}
    <ul>
        {foreach $categoryItems as $item}
            <li>{$item->name}</li>
        {/foreach}
    </ul>
{/foreach}
```

See also filter [group |filters#group].


hasBlock(string $name): bool .[method]{data-version:3.0.10}
-----------------------------------------------------------
Checks if the block of the specified name exists:

```latte
{if hasBlock(header)} ... {/if}
```

See also [block existence check |template-inheritance#Checking Block Existence].


last(string|array $value): mixed .[method]
------------------------------------------
Returns the last element of array or character of string:

```latte
{=last([1, 2, 3, 4])}    {* outputs 4 *}
{=last('abcd')}          {* outputs 'd' *}
```

See also [#first], [filter last|filters#last].


odd(int $value): bool .[method]
-------------------------------
Checks if the given number is odd.

```latte
{if odd($num)} ... {/if}
```


slice(string|array $value, int $start, ?int $length=null, bool $preserveKeys=false): string|array .[method]
-----------------------------------------------------------------------------------------------------------
Extracts a slice of an array or a string.

```latte
{=slice('hello', 1, 2)}           {* outputs 'el' *}
{=slice(['a', 'b', 'c'], 1, 2)}   {* outputs ['b', 'c'] *}
```

The slice filter works as the `array_slice` PHP function for arrays and `mb_substr` for strings with a fallback to `iconv_substr` in UTF‑8 mode.

If the start is non-negative, the sequence will start at that start in the variable. If start is negative, the sequence will start that far from the end of the variable.

If length is given and is positive, then the sequence will have up to that many elements in it. If the variable is shorter than the length, then only the available variable elements will be present. If length is given and is negative then the sequence will stop that many elements from the end of the variable. If it is omitted, then the sequence will have everything from offset up until the end of the variable.

Filter will reorder and reset the integer array keys by default. This behaviour can be changed by setting preserveKeys to true. String keys are always preserved, regardless of this parameter.