Loader'lar

Loader'lar, Latte'nin şablonlarınızın kaynak kodunu almak için kullandığı mekanizmadır. Şablonlar çoğu zaman diskte saklanan dosyalardır, ama Latte'nin esnek loader sistemi onları hemen hemen her yerden yüklemenize, hatta dinamik olarak üretmenize olanak tanır.

Loader nedir?

Şablonlarla çalışırken genellikle projenizin dizin yapısında bulunan .latte dosyalarını düşünürsünüz. Bunu Latte'nin varsayılan FileLoader'ı halleder. Ancak bir şablon adı ('main.latte' veya 'components/card.latte' gibi) ile onun asıl kaynak kodu içeriği arasındaki bağın doğrudan bir dosya yolu eşlemesi olması gerekmez.

İşte loader'lar burada devreye girer. Bir loader, bir şablon adını (bir tanımlayıcı dizeyi) alıp Latte'ye onun kaynak kodunu sağlamakla görevli bir nesnedir. Latte bu iş için tamamen yapılandırılmış loader'a güvenir. Bu yalnızca $latte->render('main.latte') ile istenen ilk şablon için değil, {include ...}, {layout ...}, {embed ...} veya {import ...} gibi etiketlerle içeride başvurulan her şablon için de geçerlidir.

Neden özel bir loader kullanılır?

  • Alternatif kaynaklardan yükleme: Bir veritabanında, bir önbellekte (Redis veya Memcached gibi), bir sürüm denetim sisteminde (Git gibi, belirli bir commit'e göre) saklanan ya da dinamik olarak üretilen şablonları almak.
  • Özel adlandırma uzlaşımları uygulama: Şablonlar için daha kısa takma adlar kullanmak ya da belirli bir arama yolu mantığı uygulamak isteyebilirsiniz (örneğin önce bir tema dizinine bakıp sonra varsayılan dizine geri düşmek).
  • Güvenlik veya erişim denetimi ekleme: Özel bir loader, belirli şablonları yüklemeden önce kullanıcı izinlerini doğrulayabilir.
  • Ön işleme: Genellikle önerilmese de (compiler pass'leri daha iyidir), bir loader teorik olarak şablon içeriğini Latte'ye vermeden önce ön işleyebilir.

Bir Latte\Engine örneği için loader'ı setLoader() metoduyla ayarlarsınız:

$latte = new Latte\Engine;

// '/path/to/templates' içindeki dosyalar için varsayılan FileLoader kullanılıyor
$loader = new Latte\Loaders\FileLoader('/path/to/templates');
$latte->setLoader($loader);

Bir loader, Latte\Loader arayüzünü uygulamalıdır.

Yerleşik loader'lar

Latte birkaç standart loader sunar:

FileLoader

Bu, başka bir loader belirtilmezse Latte\Engine sınıfının kullandığı varsayılan loader'dır. Şablonları doğrudan dosya sisteminden yükler.

Erişimi kısıtlamak için isteğe bağlı olarak bir kök dizin ayarlayabilirsiniz:

use Latte\Loaders\FileLoader;

// Aşağıdaki yalnızca /var/www/html/templates dizininden şablon yüklenmesine izin verir
$loader = new FileLoader('/var/www/html/templates');
$latte->setLoader($loader);

// $latte->render('../../../etc/passwd'); // Bu bir istisna fırlatırdı

// /var/www/html/templates/pages/contact.latte konumundaki şablonu render etme
$latte->render('pages/contact.latte');

{include} veya {layout} gibi etiketler kullanıldığında, mutlak bir yol belirtilmedikçe şablon adlarını geçerli şablona göreli çözer. Ancak bir kök dizin ayarlandıysa, tüm adlar geçerli şablona göreli çözülür.

StringLoader

Bu loader, şablon içeriğini anahtarları şablon adları (tanımlayıcılar), değerleri ise şablonun kaynak kodu dizeleri olan ilişkisel bir diziden alır. Özellikle testlerde ya da şablonların doğrudan PHP kodunda saklanabildiği küçük uygulamalarda yararlıdır.

use Latte\Loaders\StringLoader;

$loader = new StringLoader([
	'main.latte' => 'Hello {$name}, include is below:{include helper.latte}',
	'helper.latte' => '{var $x = 10}Included content: {$x}',
	// Gerektiği kadar şablon ekleyin
]);

$latte->setLoader($loader);

$latte->render('main.latte', ['name' => 'World']);
// Çıktı: Hello World, include is below:Included content: 10

Başka adlandırılmış dize şablonlarına başvuran include'lara veya kalıtıma ihtiyaç duymadan yalnızca tek bir şablonu doğrudan bir dizeden render etmeniz gerekiyorsa, StringLoader'ı dizisiz kullanırken dizeyi doğrudan render() veya renderToString() metoduna verebilirsiniz:

$loader = new StringLoader;
$latte->setLoader($loader);

$templateString = 'Hello {$name}!';
$output = $latte->renderToString($templateString, ['name' => 'Alice']);
// $output 'Hello Alice!' içerir

Özel loader oluşturma

Kendi loader'ınızı oluşturmak için (örneğin şablonları bir veritabanından, önbellekten, sürüm denetim sisteminden veya başka bir kaynaktan yüklemek üzere), Latte\Loader arayüzünü uygulayan bir sınıf oluşturmanız gerekir.

Her metodun ne yapması gerektiğine bakalım.

getContent (string $name): string

Bu, loader'ın çekirdek metodudur. Görevi, $name ile tanımlanan şablonun ($latte->render() metoduna verildiği ya da getReferredName() metodunun döndürdüğü haliyle) tam kaynak kodunu alıp döndürmektir.

Şablon bulunamıyor veya erişilemiyorsa, bu metot bir Latte\TemplateNotFoundException fırlatmalıdır.

public function getContent(string $name): string
{
	// Örnek: varsayımsal bir iç depodan yükleme
	$content = $this->storage->read($name);
	if ($content === null) {
		throw new Latte\TemplateNotFoundException("Template '$name' cannot be loaded.");
	}
	return $content;
}

getReferredName (string $name, string $referringName): string

Bu metot, {include}, {layout} vb. etiketlerin içinde kullanılan şablon adlarının çözümlenmesini üstlenir. Latte, örneğin main.latte içinde {include 'partial.latte'} ile karşılaştığında, bu metodu $name = 'partial.latte' ve $referringName = 'main.latte' ile çağırır.

Metodun işi, $referringName'in sağladığı bağlama göre $name'i, diğer loader metotları çağrılırken kullanılacak kanonik bir tanımlayıcıya (örneğin mutlak bir yola, benzersiz bir veritabanı anahtarına) çözmektir.

public function getReferredName(string $name, string $referringName): string
{
	return ...;
}

getUniqueId (string $name): string

Latte, performansı artırmak için derlenmiş şablonların önbelleğini kullanır. Derlenmiş her şablon dosyasının, kaynak şablonun tanımlayıcısından türetilmiş benzersiz bir ada ihtiyacı vardır. Bu metot, $name şablonunu benzersiz biçimde tanımlayan bir dize sağlar.

Dosya tabanlı şablonlarda mutlak yol bu amaca hizmet edebilir. Veritabanındaki şablonlarda bir ön ek ile veritabanı ID'sinin birleşimi yaygındır.

public function getUniqueId(string $name): string
{
	return ...;
}

Örnek: basit bir veritabanı loader'ı

Bu örnek, name (benzersiz tanımlayıcı), content ve updated_at sütunlarına sahip templates adlı bir veritabanı tablosunda saklanan şablonları yükleyen bir loader'ın temel yapısını gösterir.

use Latte;

class DatabaseLoader implements Latte\Loader
{
	public function __construct(
		private \PDO $db,
	) {
	}

	public function getContent(string $name): string
	{
		$stmt = $this->db->prepare('SELECT content FROM templates WHERE name = ?');
		$stmt->execute([$name]);
		$content = $stmt->fetchColumn();
		if ($content === false) {
			throw new Latte\TemplateNotFoundException("Template '$name' not found in database.");
		}
		return $content;
	}

	// Bu basit örnek, şablon adlarının ('homepage', 'article' vb.)
	// benzersiz ID olduğunu ve şablonların birbirine göreli başvurmadığını varsayar.
	public function getReferredName(string $name, string $referringName): string
	{
		return $name;
	}

	public function getUniqueId(string $name): string
	{
		// Bir ön ek ile adın kendisini kullanmak burada benzersiz ve yeterli
		return 'db_' . $name;
	}
}

// Kullanım:
$pdo = new \PDO(/* bağlantı ayrıntıları */);
$loader = new DatabaseLoader($pdo);
$latte->setLoader($loader);
$latte->render('homepage'); // 'homepage' adlı şablonu veritabanından yükler

Özel loader'lar, Latte şablonlarınızın nereden geleceği üzerinde tam denetim verir ve çeşitli depolama sistemleriyle ve iş akışlarıyla entegrasyona olanak tanır.

versiyon: 3.x