Özel fonksiyonlar oluşturma
***************************

.[perex]
Latte şablonlarına kendi yardımcı fonksiyonlarınızı kolayca ekleyin. Hesaplamalar, servislere erişim veya dinamik içerik üretimi için PHP mantığını doğrudan ifadelerin içinde çağırın; şablonlarınız hem temiz hem güçlü kalsın.


Fonksiyonlar nedir?
===================

Latte fonksiyonları, şablon ifadelerinin (`{...}`) içinde çağrılabilen fonksiyon kümesini genişletmenizi sağlar. Onları **yalnızca Latte şablonlarınızın içinde erişilebilen özel PHP fonksiyonları** gibi düşünün. Bu birkaç avantaj sağlar:

**Rahatlık:** Yardımcı mantığı (hesaplamalar, biçimlendirme veya uygulama verisine erişim gibi) tanımlayabilir ve onu doğrudan şablonda, tıpkı PHP'de `strlen()` veya `date()` çağırır gibi basit ve tanıdık bir fonksiyon sözdizimiyle çağırabilirsiniz.

```latte
{var $userInitials = initials($userName)} {* örneğin 'J. D.' *}

{if hasPermission('article', 'edit')}
    <a href="...">Düzenle</a>
{/if}
```

**Genel kapsamı kirletmez:** PHP'de gerçek bir genel fonksiyon tanımlamanın aksine, Latte fonksiyonları yalnızca şablon render bağlamında vardır. Genel PHP isim alanını şablona özgü yardımcılarla doldurmanız gerekmez.

**Uygulama mantığıyla entegrasyon:** Bir Latte fonksiyonunun arkasındaki PHP callable herhangi bir şey olabilir: bir closure, bir statik metot veya bir örnek metodu. Bu, şablon fonksiyonlarınızın değişkenleri yakalayarak (closure'larda) veya bağımlılık enjeksiyonuyla (nesnelerde) uygulama servislerine, veritabanlarına, yapılandırmaya ya da gereken başka mantığa kolayca erişebileceği anlamına gelir. Yukarıdaki `hasPermission` örneği bunu açıkça gösterir; büyük olasılıkla arka planda bir yetkilendirme servisini çağırır.

**Yerel fonksiyonları ezme (isteğe bağlı):** Bir Latte fonksiyonunu, yerel bir PHP fonksiyonuyla aynı adla bile tanımlayabilirsiniz. Şablonun içinde onun yerine sizin sürümünüz çağrılır. Bu, şablona özgü davranış sağlamak veya tutarlı bir işleyiş garantilemek için yararlı olabilir (örneğin `strlen`'i her zaman çok baytlı güvenli kılmak). Kafa karışıklığından kaçınmak için bu özelliği dikkatli kullanın.

Latte, varsayılan olarak *tüm* yerel PHP fonksiyonlarının çağrılmasına izin verir ([Sandbox|sandbox] tarafından kısıtlanmadıkça). Özel fonksiyonlar bu yerleşik kütüphaneyi projenizin özel ihtiyaçlarıyla tamamlar.

Tek bir değeri dönüştürüyorsanız, bir [özel filtre|custom filters] daha uygun olabilir.


Fonksiyonların oluşturulması ve kaydı
=====================================

Filtrelere benzer şekilde, özel fonksiyonları tanımlamanın ve kaydetmenin birkaç yolu vardır.


`addFunction()` ile doğrudan kayıt
----------------------------------

En basit yöntem, `Latte\Engine` nesnesi üzerinde `addFunction()` kullanmaktır. Fonksiyon adını (şablonda görüneceği biçimde) ve karşılık gelen PHP callable'ı verirsiniz.

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

// Basit yardımcı fonksiyon
$latte->addFunction('initials', function (string $name): string {
	preg_match_all('#\b\w#u', $name, $m);
	return implode('. ', $m[0]) . '.';
});
```

**Şablonda kullanımı:**

```latte
{var $userInitials = initials($userName)}
```

Şablondaki fonksiyon argümanları, aynı sırayla doğrudan PHP callable'a aktarılır. Tür bildirimleri, varsayılan değerler ve değişken sayıda parametre (`...`) gibi PHP özellikleri beklendiği gibi çalışır.


Uzantı ile kayıt
----------------

Daha iyi bir düzen ve yeniden kullanılabilirlik için fonksiyonları bir [Latte uzantısında |extending-latte#Latte Extension] kaydedin. Bu, önemsiz olmayan uygulamalar veya paylaşılan kütüphaneler için önerilen yaklaşımdır.

```php
namespace App\Templating;

use Latte\Extension;
use Nette\Security\Authorizator;

class MyLatteExtension extends Extension
{
	public function __construct(
		// Authorizator servisinin var olduğunu varsayalım
		private Authorizator $authorizator,
	) {
	}

	public function getFunctions(): array
	{
		// Metotları Latte fonksiyonu olarak kaydet
		return [
			'hasPermission' => $this->hasPermission(...),
		];
	}

	public function hasPermission(string $resource, string $action): bool
	{
		return $this->authorizator->isAllowed($resource, $action);
	}
}

// Kayıt ($container'ın DIC'yi tuttuğunu varsayalım)
$extension = $container->getByType(MyLatteExtension::class);
$latte = new Latte\Engine;
$latte->addExtension($extension);
```

Bu yaklaşım, Latte'de tanımlanan fonksiyonların, kendi bağımlılıkları uygulamanızın bağımlılık enjeksiyonu konteyneri veya factory'si tarafından yönetilen nesne metotlarıyla nasıl desteklenebileceğini açıkça gösterir. Böylece şablon mantığınız düzenli kalırken uygulamanızın çekirdeğine bağlı kalır.


Nitelikli bir sınıf kullanan fonksiyonlar .{toc: Functions Using the Class}
---------------------------------------------------------------------------

Tıpkı filtreler gibi, fonksiyonlar da `#[Latte\Attributes\TemplateFunction]` niteliği kullanılarak [şablon parametreleri sınıfınızda |develop#Parametreler bir sınıf olarak] metot olarak tanımlanabilir.

```php
use Latte\Attributes\TemplateFunction;

class TemplateParameters
{
	public function __construct(
		public string $userName,
		// diğer parametreler...
	) {}

	// Bu metot şablonda {initials(...)} olarak erişilebilir olur
	#[TemplateFunction]
	public function initials(string $name): string
	{
		preg_match_all('#\b\w#u', $name, $m);
		return implode('. ', $m[0]) . '.';
	}
}

// Nesneyi şablona aktar
$params = new TemplateParameters(userName: 'John Doe', /* ... */);
$latte->render('template.latte', $params);
```

Latte, parametre nesnesi şablona aktarıldığında bu nitelikle işaretlenmiş metotları otomatik bulur ve kaydeder. Şablondaki fonksiyon adı metot adıyla aynıdır.

```latte
{* Parametreler sınıfında tanımlanan fonksiyonu kullan *}
{var $inits = initials($userName)}
```

**Bağlamsal fonksiyonlar?**

Filtrelerin aksine fonksiyonlar bir `FilterInfo` nesnesi almaz. Ancak bir fonksiyon şablon bağlamına erişebilir: ilk parametresinin tür bildirimi `Latte\Runtime\Template` ise, Latte ona geçerli şablon nesnesini otomatik aktarır. Yerleşik `hasBlock()` ve `hasTemplate()` fonksiyonları tam olarak böyle uygulanmıştır.