Uzayan Latte
************

.[perex]
Latte çok esnektir ve birçok şekilde genişletilebilir: özel filtreler, işlevler, etiketler, yükleyiciler vb. ekleyebilirsiniz. Size nasıl yapılacağını göstereceğiz.

Bu bölümde Latte'yi genişletmenin farklı yolları açıklanmaktadır. Yaptığınız değişiklikleri farklı projelerde yeniden kullanmak veya başkalarıyla paylaşmak istiyorsanız, [sözde uzantı oluşturmalısınız |creating-extension].


Roma'ya Kaç Yol Çıkar? .[#toc-how-many-roads-lead-to-rome]
==========================================================

Latte'yi genişletmenin bazı yolları harmanlanabildiğinden, önce aralarındaki farkları açıklamaya çalışalım. Örnek olarak, üretilecek kelime sayısı verilen bir *Lorem ipsum* üretecini uygulamaya çalışalım.

Latte dilinin ana yapısı etikettir. Latte'yi yeni bir etiketle genişleterek bir üreteç uygulayabiliriz:

```latte
{lipsum 40}
```

Etiket harika çalışacaktır. Ancak, etiket biçimindeki oluşturucu bir ifadede kullanılamayacağı için yeterince esnek olmayabilir. Bu arada, pratikte etiket oluşturmaya nadiren ihtiyaç duyarsınız; ve bu iyi bir haber, çünkü etiketler genişletmek için daha karmaşık bir yoldur.

Tamam, etiket yerine bir filtre oluşturmayı deneyelim:

```latte
{=40|lipsum}
```

Yine geçerli bir seçenek. Ancak filtre geçirilen değeri başka bir şeye dönüştürmelidir. Burada, dönüştürmek istediğimiz değer olarak değil, filtre argümanı olarak üretilen kelime sayısını gösteren `40` değerini kullanıyoruz.

Öyleyse fonksiyon kullanmayı deneyelim:

```latte
{lipsum(40)}
```

İşte bu kadar! Bu özel örnek için, bir fonksiyon oluşturmak kullanılacak ideal uzantı noktasıdır. Örneğin, bir ifadenin kabul edildiği her yerde onu çağırabilirsiniz:

```latte
{var $text = lipsum(40)}
```


Filtreler .[#toc-filters]
=========================

Adını ve işlev gibi herhangi bir PHP çağrılabilirini kaydederek bir süzgeç oluşturun:

```php
$latte = new Latte\Engine;
$latte->addFilter('shortify', fn(string $s) => mb_substr($s, 0, 10)); // metni 10 karaktere kısaltır
```

Bu durumda filtrenin ek bir parametre alması daha iyi olacaktır:

```php
$latte->addFilter('shortify', fn(string $s, int $len = 10) => mb_substr($s, 0, $len));
```

Bunun gibi bir şablonda kullanırız:

```latte
<p>{$text|shortify}</p>
<p>{$text|shortify:100}</p>
```

Gördüğünüz gibi, fonksiyon `|` as the first argument and the arguments passed to the filter after `:` borusundan önce filtrenin sol tarafını sonraki argümanlar olarak alır.

Elbette, filtreyi temsil eden fonksiyon herhangi bir sayıda parametre kabul edebilir ve değişken parametreler de desteklenir.

Filtre HTML'de bir dize döndürürse, Latte'nin otomatik olarak (ve bu nedenle çift) kaçış yapmaması için işaretleyebilirsiniz. Bu, şablonda `|noescape` belirtme ihtiyacını ortadan kaldırır.
En kolay yol dizeyi bir `Latte\Runtime\Html` nesnesine sarmaktır, diğer yol ise [Bağlamsal Filtrelerdir |#Contextual Filters].

```php
$latte->addFilter('money', fn(float $amount) => new Latte\Runtime\Html("<i>$amount EUR</i>"));
```

.[note]
Bu durumda, filtre verilerin doğru şekilde kaçmasını sağlamalıdır.


Sınıfı Kullanan Filtreler .[#toc-filters-using-the-class]
---------------------------------------------------------

Bir filtre tanımlamanın ikinci yolu [sınıf kullanmaktır |develop#Parameters as a class]. `TemplateFilter` niteliği ile bir yöntem oluşturuyoruz:

```php
class TemplateParameters
{
	public function __construct(
		// parametreler
	) {}

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

$params = new TemplateParameters(/* ... */);
$latte->render('template.latte', $params);
```


Filtre Yükleyici .[#toc-filter-loader]
--------------------------------------

Süzgeçleri tek tek kaydetmek yerine, süzgeç adını argüman olarak kullanarak çağrılan ve PHP çağrılabilirini veya null döndüren bir işlev olan yükleyici adı verilen bir işlev oluşturabilirsiniz.

```php
$latte->addFilterLoader([new Filters, 'load']);


class Filters
{
	public function load(string $filter): ?callable
	{
		if (in_array($filter, get_class_methods($this))) {
			return [$this, $filter];
		}
		return null;
	}

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

	// ...
}
```


Bağlamsal Filtreler .[#toc-contextual-filters]
----------------------------------------------

Bağlamsal bir filtre, ilk parametrede [api:Latte\Runtime\FilterInfo] nesnesini kabul eden ve ardından klasik filtrelerde olduğu gibi diğer parametreleri kabul eden bir filtredir. Aynı şekilde kaydedilir, Latte filtrenin bağlamsal olduğunu kendisi tanır:

```php
use Latte\Runtime\FilterInfo;

$latte->addFilter('foo', function (FilterInfo $info, string $str): string {
	// ...
});
```

Bağlam filtreleri, `$info->contentType` değişkeninde aldıkları içerik türünü algılayabilir ve değiştirebilir. Filtre klasik olarak bir değişken üzerinden çağrılırsa (örneğin `{$var|foo}`), `$info->contentType` null içerecektir.

Filtre öncelikle girdi dizesinin içerik türünün desteklenip desteklenmediğini kontrol etmelidir. Ayrıca bunu değiştirebilir. Metin (veya null) kabul eden ve HTML döndüren bir filtre örneği:

```php
use Latte\Runtime\FilterInfo;

$latte->addFilter('money', function (FilterInfo $info, float $amount): string {
	// önce girdinin içerik türünün metin olup olmadığını kontrol ederiz
	if (!in_array($info->contentType, [null, ContentType::Text])) {
		throw new Exception("Filter |money used in incompatible content type $info->contentType.");
	}

	// içerik türünü HTML olarak değiştir
	$info->contentType = ContentType::Html;
	return "<i>$amount EUR</i>";
});
```

.[note]
Bu durumda, filtre verilerin doğru şekilde kaçmasını sağlamalıdır.

[Bloklar |tags#block] üzerinde kullanılan tüm filtreler (örn. `{block|foo}...{/block}`) bağlamsal olmalıdır.


Fonksiyonlar .[#toc-functions]
==============================

Öntanımlı olarak, sandbox devre dışı bırakmadığı sürece tüm yerel PHP işlevleri Latte'de kullanılabilir. Ancak kendi işlevlerinizi de tanımlayabilirsiniz. Bunlar yerel işlevleri geçersiz kılabilir.

Adını ve herhangi bir PHP çağrılabilirini kaydederek bir işlev oluşturun:

```php
$latte = new Latte\Engine;
$latte->addFunction('random', function (...$args) {
	return $args[array_rand($args)];
});
```

Bu durumda kullanım PHP fonksiyonunun çağrılmasıyla aynıdır:

```latte
{random(apple, orange, lemon)} // prints for example: apple
```


Sınıfı Kullanan İşlevler .[#toc-functions-using-the-class]
----------------------------------------------------------

Bir fonksiyon tanımlamanın ikinci yolu [sınıf kullanmaktır |develop#Parameters as a class]. `TemplateFunction` niteliği ile bir metot oluşturuyoruz:

```php
class TemplateParameters
{
	public function __construct(
		// parametreler
	) {}

	#[Latte\Attributes\TemplateFunction]
	public function random(...$args)
	{
		return $args[array_rand($args)];
	}
}

$params = new TemplateParameters(/* ... */);
$latte->render('template.latte', $params);
```


Yükleyiciler .[#toc-loaders]
============================

Yükleyiciler, şablonları dosya sistemi gibi bir kaynaktan yüklemekten sorumludur. `setLoader()` yöntemi kullanılarak ayarlanırlar:

```php
$latte->setLoader(new MyLoader);
```

Yerleşik yükleyiciler şunlardır:


FileLoader .[#toc-fileloader]
-----------------------------

Varsayılan yükleyici. Şablonları dosya sisteminden yükler.

Temel dizin ayarlanarak dosyalara erişim kısıtlanabilir:

```php
$latte->setLoader(new Latte\Loaders\FileLoader($templateDir));
$latte->render('test.latte');
```


StringLoader .[#toc-stringloader]
---------------------------------

Şablonları dizelerden yükler. Bu yükleyici birim testi için çok kullanışlıdır. Ayrıca tüm şablonları tek bir PHP dosyasında saklamanın mantıklı olabileceği küçük projeler için de kullanılabilir.

```php
$latte->setLoader(new Latte\Loaders\StringLoader([
	'main.file' => '{include other.file}',
	'other.file' => '{if true} {$var} {/if}',
]));

$latte->render('main.file');
```

Basitleştirilmiş kullanım:

```php
$template = '{if true} {$var} {/if}';
$latte->setLoader(new Latte\Loaders\StringLoader);
$latte->render($template);
```


Özel Yükleyici Oluşturma .[#toc-creating-a-custom-loader]
---------------------------------------------------------

Yükleyici, [api:Latte\Loader] arayüzünü uygulayan bir sınıftır.


Etiketler .[#toc-tags]
======================

Şablonlama motorunun en ilginç özelliklerinden biri, etiketleri kullanarak yeni dil yapıları tanımlama yeteneğidir. Bu aynı zamanda daha karmaşık bir işlevdir ve Latte'nin dahili olarak nasıl çalıştığını anlamanız gerekir.

Ancak çoğu durumda etikete gerek yoktur:
- eğer bir çıktı üretmesi gerekiyorsa, bunun yerine [fonksiyon |#functions] kullanın
- bazı girdileri değiştirip döndürmek içinse, bunun yerine [filtre |#filters] kullanın
- bir metin alanını düzenlemek olsaydı, onu bir [`{block}` |tags#block] etiketi ve bir [filtre kullanın|#Contextual Filters]
- eğer herhangi bir çıktı vermeyip sadece bir fonksiyon çağırması gerekiyorsa [`{do}` |tags#do]

Eğer hala bir etiket oluşturmak istiyorsanız, harika! Tüm temel bilgileri [Uzantı Oluşturma |creating-extension] bölümünde bulabilirsiniz.


Derleyici Geçişleri .[#toc-compiler-passes]
===========================================

Derleyici geçişleri AST'leri değiştiren veya içlerindeki bilgileri toplayan işlevlerdir. Örneğin Latte'de bir sandbox şu şekilde uygulanır: AST'nin tüm düğümlerini dolaşır, işlev ve yöntem çağrılarını bulur ve bunları kontrollü çağrılarla değiştirir.

Etiketlerde olduğu gibi, bu daha karmaşık bir işlevdir ve Latte'nin kaputun altında nasıl çalıştığını anlamanız gerekir. Tüm temel bilgileri [Uzantı Oluşturma |creating-extension] bölümünde bulabilirsiniz.