Geliştirici Uygulamaları

Kurulum

Latte'yi kurmanın en iyi yolu Composer kullanmaktır:

composer require latte/latte

Desteklenen PHP sürümleri (son küçük Latte sürümleri için geçerlidir):

sürüm PHP ile uyumlu
Latte 3.0 PHP 8.0 – 8.2

Bir Şablon Nasıl Oluşturulur

Bir şablon nasıl oluşturulur? Sadece şu basit kod yeterlidir:

$latte = new Latte\Engine;
// önbellek dizini
$latte->setTempDirectory('/path/to/tempdir');

$params = [ /* şablon değişkenleri */ ];
// veya $params = new TemplateParameters(/* ... */);

// çıktıya oluştur
$latte->render('template.latte', $params);
// değişkene oluştur
$output = $latte->renderToString('template.latte', $params);

Parametreler bir dizi veya daha iyisi, tip kontrolü ve editörlerde ipucu sağlayan bir sınıf olabilir.

Kullanım örneklerini ayrıca Latte örnekleri deposunda bulabilirsiniz.

Performans ve Önbellek

Latte'deki şablonlar son derece hızlıdır, çünkü Latte onları doğrudan PHP koduna derler ve diskte önbelleğe alır. Bu nedenle, saf PHP ile yazılmış şablonlara göre ek bir yükleri yoktur.

Önbellek, kaynak dosyasını her değiştirdiğinizde otomatik olarak yeniden oluşturulur. Böylece geliştirme sırasında Latte şablonlarınızı rahatça düzenleyebilir ve değişiklikleri tarayıcıda anında görebilirsiniz. Bu özelliği üretim ortamında kapatabilir ve böylece biraz performans tasarrufu sağlayabilirsiniz:

$latte->setAutoRefresh(false);

Üretim sunucusuna dağıtım yaparken, özellikle daha büyük uygulamalarda önbelleğin ilk oluşturulması elbette biraz zaman alabilir. Latte, cache stampede karşı yerleşik bir önleme sahiptir. Bu, Latte'yi başlatan daha fazla sayıda eşzamanlı isteğin bir araya geldiği ve önbellek henüz mevcut olmadığı için hepsinin aynı anda oluşturmaya başlayacağı bir durumdur. Bu da sunucuyu aşırı yükler. Latte akıllıdır ve birden fazla eşzamanlı istek olduğunda önbelleği yalnızca ilk iş parçacığı oluşturur, diğerleri bekler ve ardından onu kullanır.

Parametreler Olarak Sınıf

Şablona değişkenleri dizi olarak iletmek yerine bir sınıf oluşturmak daha iyidir. Bu size tip güvenli yazım, IDE'de hoş ipucu ve filtrelerin kaydı ve fonksiyonlar için bir yol sağlar.

class MailTemplateParameters
{
	public function __construct(
		public string $lang,
		public Address $address,
		public string $subject,
		public array $items,
		public ?float $price = null,
	) {}
}

$latte->render('mail.latte', new MailTemplateParameters(
	lang: $this->lang,
	subject: $title,
	price: $this->getPrice(),
	items: [],
	address: $userAddress,
));

Değişken Otomatik Kaçışını Devre Dışı Bırakma

Bir değişken HTML içinde bir dize içeriyorsa, Latte'nin onu otomatik olarak (ve dolayısıyla çift olarak) kaçırmaması için onu işaretleyebilirsiniz. Bu, şablonda |noescape belirtme ihtiyacını ortadan kaldırır.

En basit yol, dizeyi bir Latte\Runtime\Html nesnesine sarmaktır:

$params = [
	'articleBody' => new Latte\Runtime\Html($article->htmlBody),
];

Latte ayrıca Latte\HtmlStringable arayüzünü uygulayan tüm nesneleri kaçırmaz. Böylece, __toString() metodu otomatik olarak kaçırılmayacak HTML kodu döndüren kendi sınıfınızı oluşturabilirsiniz:

class Emphasis extends Latte\HtmlStringable
{
	public function __construct(
		private string $str,
	) {
	}

	public function __toString(): string
	{
		return '<em>' . htmlspecialchars($this->str) . '</em>';
	}
}

$params = [
	'foo' => new Emphasis('hello'),
];

__toString metodu doğru HTML döndürmeli ve parametrelerin kaçışını sağlamalıdır, aksi takdirde bir XSS güvenlik açığı oluşabilir!

Latte'yi Filtreler, Etiketler vb. ile Nasıl Genişletirsiniz?

Latte'ye kendi filtrenizi, fonksiyonunuzu, etiketinizi vb. nasıl eklersiniz? Bu konu Latte'yi genişletme bölümünde ele alınmaktadır. Değişikliklerinizi farklı projelerde yeniden kullanmak veya başkalarıyla paylaşmak istiyorsanız, bir uzantı oluşturmalısınız.

Şablonda Herhangi Bir Kod {php ...}

{do} etiketi içinde yalnızca PHP ifadeleri yazılabilir, bu nedenle örneğin if ... else gibi yapılar veya noktalı virgülle biten deyimler ekleyemezsiniz.

Ancak, {php ...} etiketini ekleyen RawPhpExtension uzantısını kaydedebilirsiniz. Bunu kullanarak herhangi bir PHP kodu ekleyebilirsiniz. Sandbox modu kurallarının hiçbiri geçerli değildir, bu nedenle kullanım şablon yazarının sorumluluğundadır.

$latte->addExtension(new Latte\Essential\RawPhpExtension);

Oluşturulan Kodu Kontrol Etme

Latte, şablonları PHP koduna derler. Elbette, oluşturulan kodun sözdizimsel olarak geçerli olmasını sağlar. Ancak, üçüncü taraf uzantıları veya RawPhpExtension kullanırken Latte, oluşturulan dosyanın doğruluğunu garanti edemez. Ayrıca, PHP'de sözdizimsel olarak doğru ancak yasaklanmış (örneğin, $this değişkenine değer atama) ve PHP Compile Error'a neden olan kod yazmak mümkündür. Böyle bir işlemi şablonda yazarsanız, oluşturulan PHP koduna da girer. PHP'de iki yüzden fazla farklı yasaklanmış işlem olduğundan, Latte'nin bunları tespit etme iddiası yoktur. Yalnızca PHP'nin kendisi oluşturma sırasında bunlara dikkat çeker, bu da genellikle bir sorun teşkil etmez.

Ancak, şablonun derlenmesi sırasında zaten hiçbir PHP Compile Error içermediğini bilmek istediğiniz durumlar vardır. Özellikle, şablonlar kullanıcılar tarafından düzenlenebiliyorsa veya Sandbox kullanıyorsanız. Bu durumda, şablonları derleme sırasında kontrol ettirin. Bu işlevselliği Engine::enablePhpLint() metoduyla etkinleştirirsiniz. Kontrol için PHP ikili dosyasını çağırması gerektiğinden, yolunu parametre olarak iletin:

$latte = new Latte\Engine;
$latte->enablePhpLinter('/path/to/php');

try {
	$latte->compile('home.latte');
} catch (Latte\CompileException $e) {
	// Latte'deki hataları ve ayrıca PHP'deki Compile Error'ı yakalar
	echo 'Hata: ' . $e->getMessage();
}

Yerel Ayarlar

Latte, sayıların, tarihlerin biçimlendirilmesini ve sıralamayı etkileyen yerel ayarları ayarlamanıza olanak tanır. setLocale() metodu kullanılarak ayarlanır. Yerel ayar tanımlayıcısı, PHP intl uzantısı tarafından kullanılan IETF dil etiketi standardını takip eder. Dil kodundan ve isteğe bağlı olarak ülke kodundan oluşur, ör. Amerika Birleşik Devletleri'nde İngilizce için en_US, Almanya'da Almanca için de_DE vb.

$latte = new Latte\Engine;
$latte->setLocale('tr_TR');

Yerel ayar ayarı localDate, sort, number ve bytes filtrelerini etkiler.

PHP intl uzantısını gerektirir. Latte'deki ayar, PHP'deki genel yerel ayar ayarını etkilemez.

Katı Mod

Katı ayrıştırma modunda Latte, kapanış HTML etiketlerinin eksik olup olmadığını kontrol eder ve ayrıca $this değişkeninin kullanımını yasaklar. Şu şekilde etkinleştirirsiniz:

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

declare(strict_types=1) başlığıyla şablon oluşturmayı şu şekilde etkinleştirirsiniz:

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

Şablonlarda Çeviri

TranslatorExtension uzantısını kullanarak şablona {_...}, {translate} etiketlerini ve translate filtresini eklersiniz. Değerleri veya şablonun bölümlerini diğer dillere çevirmek için kullanılırlar. Parametre olarak çeviriyi gerçekleştiren metodu (PHP çağrılabilir) belirtiriz:

class MyTranslator
{
	public function __construct(private string $lang)
	{}

	public function translate(string $original): string
	{
		// $original'dan $this->lang'a göre $translated oluşturacağız
		return $translated;
	}
}

$translator = new MyTranslator($lang);
$extension = new Latte\Essential\TranslatorExtension(
	$translator->translate(...), // PHP 8.0'da [$translator, 'translate']
);
$latte->addExtension($extension);

Çevirmen, şablon oluşturulurken çalışma zamanında çağrılır. Latte ovšem umí všechny statické texty překládat už během kompilace šablony. Tím se ušetří výkon, protože každý řetězec se přeloží jen jednou a výsledný překlad se zapíše do zkompilované podoby. V adresáři s cache tak vznikne více zkompilovaných verzí šablony, jedna pro každý jazyk. K tomu stačí pouze uvést jazyk jako druhý parametr:

$extension = new Latte\Essential\TranslatorExtension(
	$translator->translate(...),
	$lang,
);

Statik metin, örneğin {_'merhaba'} veya {translate}merhaba{/translate} anlamına gelir. Statik olmayan metinler, örneğin {_$foo}, çalışma zamanında çevrilmeye devam edecektir.

Çevirmene şablondan {_$original, foo: bar} veya {translate foo: bar} kullanarak ek parametreler de iletilebilir, bunlar $params dizisi olarak alınır:

public function translate(string $original, ...$params): string
{
	// $params['foo'] === 'bar'
}

Hata Ayıklama ve Tracy

Latte, geliştirmeyi sizin için olabildiğince keyifli hale getirmeye çalışır. Doğrudan hata ayıklama amacıyla üç etiket vardır: {dump}, {debugbreak} ve {trace}.

En büyük rahatlığı, harika hata ayıklama aracı Tracy'yi de yükleyip Latte için eklentiyi etkinleştirdiğinizde elde edersiniz:

// Tracy'yi açar
Tracy\Debugger::enable();

$latte = new Latte\Engine;
// Tracy için uzantıyı etkinleştirir
$latte->addExtension(new Latte\Bridges\Tracy\TracyExtension);

Artık tüm hatalar, satır ve sütun vurgulamasıyla birlikte şablonlardaki hatalar da dahil olmak üzere net kırmızı ekranda görüntülenecektir (video). Aynı zamanda, sağ alt köşedeki Tracy Bar'da Latte için bir sekme görünecektir, burada oluşturulan tüm şablonlar ve karşılıklı ilişkileri (şablona veya derlenmiş koda tıklama seçeneği dahil) ve ayrıca değişkenler açıkça görülebilir:

Latte şablonları anlaşılır PHP koduna derlediğinden, IDE'nizde rahatça adım adım ilerleyebilirsiniz.

Linter: Şablon Sözdizimi Doğrulaması

Tüm şablonları gözden geçirmek ve sözdizimsel hata içerip içermediklerini kontrol etmek için Linter aracı size yardımcı olacaktır. Konsoldan çalıştırılır:

vendor/bin/latte-lint <yol>

--strict parametresi katı modu etkinleştirir.

Kendi özel etiketlerinizi kullanıyorsanız, kendi Linter sürümünüzü de oluşturun, ör. custom-latte-lint:

#!/usr/bin/env php
<?php

// autoload.php dosyasına gerçek yolu girin
require __DIR__ . '/vendor/autoload.php';

$path = $argv[1] ?? '.';

$linter = new Latte\Tools\Linter;
$latte = $linter->getEngine();
// buraya kendi uzantılarınızı ekleyin
$latte->addExtension(/* ... */);

$ok = $linter->scanDirectory($path);
exit($ok ? 0 : 1);

Alternatif olarak, kendi Latte\Engine nesnenizi Linter'a iletebilirsiniz:

$latte = new Latte\Engine;
// burada $latte nesnesini yapılandıracağız
$linter = new Latte\Tools\Linter(engine: $latte);

Şablonları Dizeden Yükleme

Test amacıyla dosyalar yerine dizelerden şablon yüklemeniz mi gerekiyor? StringLoader size yardımcı olacaktır:

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

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

İstisna İşleyici

Beklenen istisnalar için kendi özel işleyici işleyicinizi tanımlayabilirsiniz. {try} içinde ve sandbox içinde oluşan istisnalar ona iletilir.

$loggingHandler = function (Throwable $e, Latte\Runtime\Template $template) use ($logger) {
	$logger->log($e);
};

$latte = new Latte\Engine;
$latte->setExceptionHandler($loggingHandler);

Otomatik Düzen Arama

{layout} etiketiyle şablon, üst şablonunu belirtir. Düzenin otomatik olarak aranmasını sağlamak da mümkündür, bu da şablon yazmayı basitleştirir, çünkü içlerinde {layout} etiketini belirtmek gerekmeyecektir.

Bu şu şekilde elde edilir:

$finder = function (Latte\Runtime\Template $template) {
	if (!$template->getReferenceType()) {
		// düzen dosyasının yolunu döndürür
		return 'automatic.layout.latte';
	}
};

$latte = new Latte\Engine;
$latte->addProvider('coreParentFinder', $finder);

Şablonun bir düzeni olmaması gerekiyorsa, bunu {layout none} etiketiyle bildirir.

versiyon: 3.0