Latte'yi Genişletme

Latte, genişletilebilirlik göz önünde bulundurularak tasarlanmıştır. Standart etiket, filtre ve fonksiyon seti birçok kullanım durumunu kapsasa da, genellikle kendi özel mantığınızı veya yardımcı araçlarınızı eklemeniz gerekir. Bu sayfa, Latte'yi projenizin gereksinimlerine mükemmel şekilde uyacak şekilde genişletmenin yollarına genel bir bakış sunar – basit yardımcılardan karmaşık yeni sözdizimine kadar.

Latte'yi Genişletme Yolları

Latte'yi özelleştirebileceğiniz ve genişletebileceğiniz ana yolların hızlı bir özeti aşağıdadır:

  • Özel Filtreler: Şablon çıktısındaki verileri doğrudan biçimlendirmek veya dönüştürmek için (ör. {$var|myFilter}). Tarihleri biçimlendirme, metin düzenleme veya belirli kaçış işlemleri uygulama gibi görevler için idealdir. İçeriği anonim bir {block} içine alıp üzerine özel bir filtre uygulayarak daha büyük HTML içerik bloklarını değiştirmek için de kullanabilirsiniz.
  • Özel Fonksiyonlar: Şablon içindeki ifadelerde çağrılabilecek yeniden kullanılabilir mantık eklemek için (ör. {myFunction($arg1, $arg2)}). Hesaplamalar, uygulama yardımcı fonksiyonlarına erişim veya küçük içerik parçaları oluşturmak için kullanışlıdır.
  • Özel Etiketler: Tamamen yeni dil yapıları oluşturmak için ({mytag}...{/mytag} veya n:mytag). Etiketler en fazla esnekliği sunar, özel yapılar tanımlamanıza, şablon ayrıştırmasını kontrol etmenize ve karmaşık oluşturma mantığı uygulamanıza olanak tanır.
  • Derleyici Geçişleri: Ayrıştırmadan sonra ancak PHP kodu oluşturulmadan önce şablonun soyut sözdizimi ağacını (AST) değiştiren fonksiyonlar. Gelişmiş optimizasyonlar, güvenlik kontrolleri (Sandbox gibi) veya otomatik kod düzenlemeleri için kullanılır.
  • Özel Yükleyiciler: Latte'nin şablon dosyalarını bulma ve yükleme şeklini değiştirmek için (ör. veritabanından, şifreli depolamadan vb. yükleme).

Doğru genişletme yöntemini seçmek çok önemlidir. Karmaşık bir etiket oluşturmadan önce, daha basit bir filtre veya fonksiyonun yeterli olup olmayacağını düşünün. Bunu bir örnekle gösterelim: oluşturulacak kelime sayısını argüman olarak alan bir Lorem ipsum üreteci uygulama.

  • Etiket olarak mı? {lipsum 40} – Mümkün, ancak etiketler kontrol yapıları veya karmaşık işaretleme oluşturmak için daha uygundur. Etiketler doğrudan ifadelerde kullanılamaz.
  • Filtre olarak mı? {=40|lipsum} – Teknik olarak çalışır, ancak filtreler girdi değerini dönüştürmek için tasarlanmıştır. Burada 40 dönüştürülen bir değer değil, bir argümandır. Bu anlamsal olarak yanlış hissettirir.
  • Fonksiyon olarak mı? {lipsum(40)} – Bu en doğal çözümdür! Fonksiyonlar argüman alır ve değer döndürür, bu da herhangi bir ifadede kullanım için idealdir: {var $text = lipsum(40)}.

Genel öneri: Hesaplamalar/üretim için fonksiyonları, dönüştürme için filtreleri ve yeni dil yapıları veya karmaşık işaretleme için etiketleri kullanın. AST manipülasyonu için geçişleri ve şablonları almak için yükleyicileri kullanın.

Doğrudan Kayıt

Projeye özgü yardımcı araçlar veya hızlı genişletmeler için Latte, filtrelerin ve fonksiyonların doğrudan Latte\Engine nesnesine kaydedilmesine olanak tanır.

Bir filtre kaydetmek için addFilter() metodunu kullanın. Filtre fonksiyonunuzun ilk argümanı | karakterinden önceki değer olacak ve sonraki argümanlar iki nokta üst üste : işaretinden sonra iletilenler olacaktır.

$latte = new Latte\Engine;

// Filtre tanımı (çağrılabilir nesne: fonksiyon, statik metot vb.)
$myTruncate = fn(string $s, int $length = 50) => mb_substr($s, 0, $length);

// Kayıt
$latte->addFilter('truncate', $myTruncate);

// Şablonda kullanım: {$text|truncate} veya {$text|truncate:100}

Ayrıca, istenen ada göre dinamik olarak çağrılabilir filtre nesneleri sağlayan bir Filtre Yükleyici de kaydedebilirsiniz:

$latte->addFilterLoader(fn(string $name) => /* çağrılabilir nesne veya null döndürür */);

Şablon ifadelerinde kullanılabilir bir fonksiyon kaydetmek için addFunction() metodunu kullanın.

$latte = new Latte\Engine;

// Fonksiyon tanımı
$isWeekend = fn(DateTimeInterface $date) => $date->format('N') >= 6;

// Kayıt
$latte->addFunction('isWeekend', $isWeekend);

// Şablonda kullanım: {if isWeekend($myDate)}Hafta sonu!{/if}

Daha fazla bilgi için Özel Filtreler Oluşturma ve Fonksiyonlar bölümlerine bakın.

Sağlam Yöntem: Latte Uzantısı

Doğrudan kayıt basit olsa da, Latte uzantılarını paketlemek ve dağıtmak için standart ve önerilen yol Extension sınıfları aracılığıyladır. Extension, birden çok etiket, filtre, fonksiyon, derleyici geçişi ve diğer öğeleri kaydetmek için merkezi bir yapılandırma noktası olarak hizmet eder.

Neden Uzantıları Kullanmalısınız?

  • Organizasyon: İlgili uzantıları (belirli bir işlev için etiketler, filtreler vb.) tek bir sınıfta bir arada tutar.
  • Yeniden Kullanılabilirlik ve Paylaşım: Uzantılarınızı diğer projelerde kullanmak veya toplulukla paylaşmak (ör. Composer aracılığıyla) için kolayca paketleyin.
  • Tam Güç: Özel etiketler ve derleyici geçişleri yalnızca Uzantılar aracılığıyla kaydedilebilir.

Uzantı Kaydı

Uzantı, Latte'ye addExtension() metoduyla (veya yapılandırma dosyası aracılığıyla) kaydedilir:

$latte = new Latte\Engine;
$latte->addExtension(new MyProjectExtension);

Birden fazla uzantı kaydederseniz ve bunlar aynı ada sahip etiketler, filtreler veya fonksiyonlar tanımlarsa, en son eklenen uzantı öncelikli olur. Bu aynı zamanda uzantılarınızın yerel etiketleri/filtreleri/fonksiyonları geçersiz kılabileceği anlamına gelir.

Sınıfta bir değişiklik yaptığınızda ve otomatik yenileme kapalı değilse, Latte şablonlarınızı otomatik olarak yeniden derleyecektir.

Uzantı Oluşturma

Özel bir uzantı oluşturmak için Latte\Extension sınıfından miras alan bir sınıf oluşturmanız gerekir. Böyle bir uzantının nasıl göründüğüne dair bir fikir edinmek için yerleşik “CoreExtension”'e göz atın.

Uygulayabileceğiniz metotlara bakalım:

beforeCompile (Latte\Engine $engine): void

Şablon derlenmeden önce çağrılır. Metot, örneğin derlemeyle ilgili başlatmalar için kullanılabilir.

getTags(): array

Şablon derlenirken çağrılır. Etiket ayrıştırma fonksiyonları olan etiket adı ⇒ çağrılabilir nesne şeklinde ilişkisel bir dizi döndürür. Daha fazla bilgi.

public function getTags(): array
{
	return [
		'foo' => FooNode::create(...),
		'bar' => BarNode::create(...),
		'n:baz' => NBazNode::create(...),
		// ...
	];
}

n:baz etiketi, saf bir n:nitelik'i temsil eder, yani yalnızca nitelik olarak yazılabilen bir etikettir.

foo ve bar etiketleri için Latte, bunların çift etiket olup olmadığını otomatik olarak tanır ve eğer öyleyse, n:inner-foo ve n:tag-foo önekli varyantlar da dahil olmak üzere n:nitelikler kullanılarak otomatik olarak yazılabilirler.

Bu tür n:niteliklerin yürütme sırası, getTags() metodu tarafından döndürülen dizideki sıralarına göre belirlenir. Bu nedenle, n:foo her zaman n:bar'dan önce yürütülür, HTML etiketindeki nitelikler ters sırada listelenmiş olsa bile (<div n:bar="..." n:foo="...">).

Birden fazla uzantı arasında n:niteliklerin sırasını belirlemeniz gerekiyorsa, order() yardımcı metodunu kullanın; burada before xor after parametresi, hangi etiketlerin etiketten önce veya sonra sıralandığını belirtir.

public function getTags(): array
{
	return [
		'foo' => self::order(FooNode::create(...), before: 'bar'),
		'bar' => self::order(BarNode::create(...), after: ['block', 'snippet']),
	];
}

getPasses(): array

Şablon derlenirken çağrılır. AST'yi dolaşan ve değiştiren sözde derleyici geçişleri'ni temsil eden fonksiyonlar olan geçiş adı ⇒ çağrılabilir nesne şeklinde ilişkisel bir dizi döndürür.

Burada da order() yardımcı metodu kullanılabilir. before veya after parametrelerinin değeri, hepsinden önce/sonra anlamına gelen * olabilir.

public function getPasses(): array
{
	return [
		'optimize' => Passes::optimizePass(...),
		'sandbox' => self::order($this->sandboxPass(...), before: '*'),
		// ...
	];
}

beforeRender (Latte\Engine $engine): void

Her şablon oluşturulmadan önce çağrılır. Metot, örneğin oluşturma sırasında kullanılan değişkenleri başlatmak için kullanılabilir.

getFilters(): array

Şablon oluşturulmadan önce çağrılır. Filtreleri filtre adı ⇒ çağrılabilir nesne şeklinde ilişkisel bir dizi olarak döndürür. Daha fazla bilgi.

public function getFilters(): array
{
	return [
		'batch' => $this->batchFilter(...),
		'trim' => $this->trimFilter(...),
		// ...
	];
}

getFunctions(): array

Şablon oluşturulmadan önce çağrılır. Fonksiyonları fonksiyon adı ⇒ çağrılabilir nesne şeklinde ilişkisel bir dizi olarak döndürür. Daha fazla bilgi.

public function getFunctions(): array
{
	return [
		'clamp' => $this->clampFunction(...),
		'divisibleBy' => $this->divisibleByFunction(...),
		// ...
	];
}

getProviders(): array

Şablon oluşturulmadan önce çağrılır. Genellikle çalışma zamanında etiketler tarafından kullanılan sağlayıcılar dizisini döndürür. Bunlara $this->global->... aracılığıyla erişilir. Daha fazla bilgi.

public function getProviders(): array
{
	return [
		'myFoo' => $this->foo,
		'myBar' => $this->bar,
		// ...
	];
}

getCacheKey (Latte\Engine $engine): mixed

Şablon oluşturulmadan önce çağrılır. Dönüş değeri, hash'i derlenmiş şablon dosyasının adında bulunan anahtarın bir parçası haline gelir. Bu nedenle, farklı dönüş değerleri için Latte farklı önbellek dosyaları oluşturur.

versiyon: 3.0