Vytváření vlastních filtrů
**************************

.[perex]
Filtry jsou výkonné nástroje pro formátování a úpravu dat přímo v šablonách Latte. Nabízejí čistou syntaxi pomocí symbolu roury (`|`) pro transformaci proměnných nebo výsledků výrazů do požadovaného výstupního formátu.


Co jsou filtry?
===============

Filtry v Latte jsou v podstatě **PHP funkce navržené speciálně pro transformaci vstupní hodnoty na výstupní hodnotu**. Aplikují se pomocí zápisu s rourou (`|`) uvnitř výrazů šablony (`{...}`).

**Pohodlnost:** Filtry vám umožňují zapouzdřit běžné úlohy formátování (jako formátování datumů, změna velikosti písmen, zkracování) nebo manipulace s daty do znovupoužitelných jednotek. Místo opakování složitého PHP kódu ve vašich šablonách můžete jednoduše aplikovat filtr:
```latte
{* Místo složitého PHP pro zkrácení: *}
{$article->text|truncate:100}

{* Místo kódu pro formátování datumu: *}
{$event->startTime|date:'Y-m-d H:i'}

{* Aplikace více transformací: *}
{$product->name|lower|capitalize}
```

**Čitelnost:** Používání filtrů činí šablony přehlednějšími a více zaměřenými na prezentaci, protože transformační logika je přesunuta do definice filtru.

**Kontextová citlivost:** Klíčovou předností filtrů v Latte je jejich schopnost být [kontextově citlivé |#Kontextové filtry]. To znamená, že filtr může rozpoznat typ obsahu, se kterým pracuje (HTML, JavaScript, prostý text atd.), a aplikovat odpovídající logiku nebo escapování, což je zásadní pro bezpečnost a správnost, zejména při generování HTML.

**Integrace s aplikační logikou:** Stejně jako vlastní funkce může být PHP callable za filtrem uzávěr (closure), statická metoda nebo metoda instance. To umožňuje filtrům přistupovat k aplikačním službám nebo datům, pokud je to potřeba, i když jejich hlavním účelem zůstává *transformace vstupní hodnoty*.

Latte ve výchozím nastavení poskytuje bohatou sadu [standardních filtrů |filters]. Vlastní filtry vám umožňují rozšířit tuto sadu o formátování a transformace specifické pro váš projekt.

Pokud potřebujete provádět logiku založenou na *více* vstupech nebo nemáte primární hodnotu k transformaci, je pravděpodobně vhodnější použít [vlastní funkci |custom-functions]. Pokud potřebujete generovat složitý markup nebo řídit tok šablony, zvažte [vlastní tag |custom-tags].


Vytváření a registrace filtrů
=============================

Existuje několik způsobů, jak definovat a registrovat vlastní filtry v Latte.


Přímá registrace pomocí `addFilter()`
-------------------------------------

Nejjednodušší způsob, jak přidat filtr, je použití metody `addFilter()` přímo na objektu `Latte\Engine`. Zadáte název filtru (jak bude použit v šabloně) a odpovídající PHP callable.

```php
$latte = new Latte\Engine;

// Jednoduchý filtr bez argumentů
$latte->addFilter('initial', fn(string $s): string => mb_substr($s, 0, 1) . '.');

// Filtr s volitelným argumentem
$latte->addFilter('shortify', function (string $s, int $len = 10): string {
	return mb_substr($s, 0, $len);
});

// Filtr zpracovávající pole
$latte->addFilter('sum', fn(array $numbers): int|float => array_sum($numbers));
```

**Použití v šabloně:**

```latte
{$name|initial}                 {* Vypíše 'J.' pokud je $name 'John' *}
{$description|shortify}         {* Použije výchozí délku 10 *}
{$description|shortify:50}      {* Použije délku 50 *}
{$prices|sum}                   {* Vypíše součet položek v poli $prices *}
```

**Předávání argumentů:**

Hodnota nalevo od roury (`|`) je vždy předána jako *první* argument funkci filtru. Jakékoliv parametry uvedené za dvojtečkou (`:`) v šabloně jsou předány jako následující argumenty.

```latte
{$text|shortify:30}
// Volá PHP funkci shortify($text, 30)
```


Registrace pomocí rozšíření
---------------------------

Pro lepší organizaci, zejména při vytváření znovupoužitelných sad filtrů nebo jejich sdílení jako balíčky, je doporučeným způsobem registrovat je v rámci [rozšíření Latte |extending-latte#Latte Extension]:

```php
namespace App\Latte;

use Latte\Extension;

class MyLatteExtension extends Extension
{
	public function getFilters(): array
	{
		return [
			'initial' => $this->initial(...),
			'shortify' => $this->shortify(...),
		];
	}

	public function initial(string $s): string
	{
		return mb_substr($s, 0, 1) . '.';
	}

	public function shortify(string $s, int $len = 10): string
	{
		return mb_substr($s, 0, $len);
	}
}

// Registrace
$latte = new Latte\Engine;
$latte->addExtension(new App\Latte\MyLatteExtension);
```

Tento přístup udrží logiku vašeho filtru zapouzdřenou a registraci jednoduchou.


Použití načítače filtrů
-----------------------

Latte umožňuje registrovat načítač filtrů pomocí `addFilterLoader()`. Jde o jediné volatelné callable, které Latte požádá o jakýkoliv neznámý název filtru během kompilace. Načítač vrací PHP callable filtru nebo `null`.

```php
$latte = new Latte\Engine;

// Načítač může dynamicky vytvářet/získávat callable filtry
$latte->addFilterLoader(function (string $name): ?callable {
	if ($name === 'myLazyFilter') {
		// Představte si zde náročnou inicializaci...
		$service = get_some_expensive_service();
		return fn($value) => $service->process($value);
	}
	return null;
});
```

Tato metoda byla primárně určena pro líné načítání filtrů s velmi **náročnou inicializací**. Avšak moderní praktiky vkládání závislostí (dependency injection) obvykle zvládají líné služby efektivněji.

Načítače filtrů přidávají složitost a obecně se nedoporučují ve prospěch přímé registrace pomocí `addFilter()` nebo v rámci rozšíření pomocí `getFilters()`. Používejte načítače pouze pokud máte závažný, specifický důvod související s výkonnostními problémy při inicializaci filtrů, které nelze řešit jinak.


Filtry používající třídu s atributy
-----------------------------------

Další elegantní způsob, jak definovat filtry, je použití metod ve vaší [třídě parametrů šablony |develop#Parametry jako třída]. Stačí přidat atribut `#[Latte\Attributes\TemplateFilter]` k metodě.

```php
use Latte\Attributes\TemplateFilter;

class TemplateParameters
{
	public function __construct(
		public string $description,
		// další parametry...
	) {}

	#[TemplateFilter]
	public function shortify(string $s, int $len = 10): string
	{
		return mb_substr($s, 0, $len);
	}
}

// Předání objektu do šablony
$params = new TemplateParameters(description: '...');
$latte->render('template.latte', $params);
```

Latte automaticky rozpozná a zaregistruje metody označené tímto atributem, když je objekt `TemplateParameters` předán do šablony. Název filtru v šabloně bude stejný jako název metody (`shortify` v tomto případě).

```latte
{* Použití filtru definovaného ve třídě parametrů *}
{$description|shortify:50}
```


Kontextové filtry
=================

Někdy filtr potřebuje více informací než jen vstupní hodnotu. Může potřebovat znát **typ obsahu** řetězce, se kterým pracuje (např. HTML, JavaScript, prostý text) nebo ho dokonce upravit. To je situace pro kontextové filtry.

Kontextový filtr je definován stejně jako běžný filtr, ale jeho **první parametr musí být** typově označen jako `Latte\Runtime\FilterInfo`. Latte automaticky rozpozná tento podpis a při volání filtru předá objekt `FilterInfo`. Následující parametry obdrží argumenty filtru jako obvykle.

```php
use Latte\Runtime\FilterInfo;
use Latte\ContentType;

$latte->addFilter('money', function (FilterInfo $info, float $amount): string {
	// 1. Zkontrolujte vstupní typ obsahu (volitelné, ale doporučené)
	//    Povolte null (proměnný vstup) nebo prostý text. Odmítněte pokud je aplikován na HTML atd.
	if (!in_array($info->contentType, [null, ContentType::Text], true)) {
		$actualType = $info->contentType ?? 'mixed';
		throw new \RuntimeException(
			"Filter |money used in incompatible content type $actualType. Expected text or null."
		);
	}

	// 2. Proveďte transformaci
	$formatted = number_format($amount, 2, '.', ',') . ' EUR';
	$htmlOutput = '<i>' . htmlspecialchars($formatted) . '</i>'; // Zajistěte správné escapování!

	// 3. Deklarujte výstupní typ obsahu
	$info->contentType = ContentType::Html;

	// 4. Vraťte výsledek
	return $htmlOutput;
});
```

`$info->contentType` je řetězcová konstanta z `Latte\ContentType` (např. `ContentType::Html`, `ContentType::Text`, `ContentType::JavaScript`, atd.) nebo `null`, pokud je filtr aplikován na proměnnou (`{$var|filter}`). Můžete tuto hodnotu **číst**, abyste zkontrolovali vstupní kontext, a **zapisovat** do ní, abyste deklarovali typ výstupního kontextu.

Nastavením typu obsahu na HTML sdělujete Latte, že řetězec vrácený vaším filtrem je bezpečné HTML. Latte pak na tento výsledek **nebude** aplikovat své výchozí automatické escapování. To je zásadní, pokud váš filtr generuje HTML markup.

.[warning]
Pokud váš filtr generuje HTML, **jste zodpovědní za správné escapování jakýchkoliv vstupních dat** použitých v tomto HTML (jako v případě volání `htmlspecialchars($formatted)` výše). Opomenutí může vytvořit XSS zranitelnosti. Pokud váš filtr vrací pouze prostý text, nemusíte nastavovat `$info->contentType`.


Filtry na blocích
-----------------

Všechny filtry aplikované na [bloky |tags#block] *musí* být kontextové. Je to proto, že obsah bloku má definovaný typ obsahu (obvykle HTML), kterého si filtr musí být vědom.

```latte
{block heading|money}1000{/block}
{* Filtr 'money' obdrží '1000' jako druhý argument
   a $info->contentType bude ContentType::Html *}
```

Kontextové filtry poskytují silnou kontrolu nad tím, jak jsou data zpracovávána na základě jejich kontextu, umožňují pokročilé funkce a zajišťují správné chování escapování, zejména při generování HTML obsahu.