Функції Latte
*************

.[perex]
На додаток до звичайних функцій PHP, ви можете використовувати їх у шаблонах.

.[table-latte-filters]
| `clamp` | [затискає значення в діапазон |#clamp]
| `divisibleBy`| [перевіряє, чи ділиться змінна на число |#divisibleBy]
| `even` | [перевіряє, чи є дане число парним |#even]
| `first` | [повертає перший елемент масиву або символ рядка |#first]
| `group` | [групує дані за різними критеріями |#group]
| `hasBlock` | [виявляє наявність блоку |#hasBlock]
| `last` | [pповертає останній елемент масиву або символ рядка |#last]
| `odd` | [перевіряє, чи є дане число непарним |#odd]
| `slice` | [витягує фрагмент масиву або рядка |#slice]


Використання .[#toc-usage]
==========================

Функції використовуються так само, як і звичайні функції PHP, і можуть бути використані у всіх виразах:

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

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

[Користувацькі функції |extending-latte#Functions] можуть бути зареєстровані таким чином:

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

Ми використовуємо його в шаблоні таким чином:

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


Функції .[#toc-functions]
=========================


clamp(int|float $value, int|float $min, int|float $max): int|float .[method]
----------------------------------------------------------------------------
Повертає значення, затиснуте у включно діапазоні min і max.

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

Див. також [затиск фільтра |filters#clamp]:


divisibleBy(int $value, int $by): bool .[method]
------------------------------------------------
Перевіряє, чи ділиться змінна на число.

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


even(int $value): bool .[method]
--------------------------------
Перевіряє, чи є задане число парним.

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


first(string|iterable $value): mixed .[method]
----------------------------------------------
Повертає перший елемент масиву або символ рядка:

```latte
{=first([1, 2, 3, 4])}    {* виводить 1 *}
{=first('abcd')}          {* виводиться 'a' *}
```

Див. також [last |#last], [filter first |filters#first].


group(iterable $data, string|int|\Closure $by): array .[method]{data-version:3.0.16}
------------------------------------------------------------------------------------
Ця функція групує дані за різними критеріями.

У цьому прикладі рядки таблиці групуються за стовпцем `categoryId`. Результатом є масив полів, де ключем є значення у стовпчику `categoryId`. Прочитайте [детальну інструкцію |cookbook/grouping].

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

Дивіться також [групу |filters#group] фільтрів.


hasBlock(string $name): bool .[method]{data-version:3.0.10}
-----------------------------------------------------------
Перевіряє, чи існує блок з вказаною назвою:

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

Див. також [перевірка існування блоку |template-inheritance#Checking Block Existence].


last(string|array $value): mixed .[method]
------------------------------------------
Повертає останній елемент масиву або символ рядка:

```latte
{=last([1, 2, 3, 4])}    {* виводиться 4 *}
{=last('abcd')}          {* виводиться 'd' *}
```

Див. також [first |#first], [filter last |filters#last].


odd(int $value): bool .[method]
-------------------------------
Перевіряє, чи є задане число непарним.

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


slice(string|array $value, int $start, ?int $length=null, bool $preserveKeys=false): string|array .[method]
-----------------------------------------------------------------------------------------------------------
Витягує фрагмент масиву або рядка.

```latte
{=slice('hello', 1, 2)} {* виводиться 'el' *}
{=slice(['a', 'b', 'c'], 1, 2)} {* виводить ['b', 'c'] *}
```

Фільтр зрізів працює як функція `array_slice` PHP для масивів і `mb_substr` для рядків із поверненням до `iconv_substr` у режимі UTF-8.

Якщо start невід'ємний, то послідовність почнеться з цього початку в змінній. Якщо start від'ємний, то послідовність почнеться на такій-то відстані від кінця змінної.

Якщо задано довжину і вона позитивна, то послідовність міститиме до цієї кількості елементів. Якщо змінна коротша за довжину, то будуть присутні тільки доступні елементи змінної. Якщо довжина задана і від'ємна, то послідовність зупиниться на стільки елементів від кінця змінної. Якщо довжина не вказана, то послідовність міститиме всі елементи від зміщення до кінця змінної.

Filter за замовчуванням упорядковує і скидає ключі цілочисельного масиву. Цю поведінку можна змінити, встановивши preserveKeys в true. Рядкові ключі завжди зберігаються, незалежно від цього параметра.