Şablon Yükleyiciler

Yükleyiciler, Latte'nin şablonlarınızın kaynak kodunu almak için kullandığı mekanizmadır. Genelde şablonlar diskte depolanan dosyalardır, ancak Latte'nin esnek yükleyici sistemi bunları neredeyse her yerden yüklemenize ve hatta dinamik olarak oluşturmanıza olanak tanır.

Yükleyici nedir?

Tipik olarak, şablonlarla çalıştığınızda, projenizin dizin yapısında bulunan .latte dosyalarını düşünürsünüz. Bu Latte'nin varsayılan FileLoader'ı tarafından gerçekleştirilir. Ancak, bir şablon adı ( 'main.latte' veya 'components/card.latte' gibi) ile gerçek kaynak kodu içeriği arasındaki bağlantı doğrudan bir dosya yolu eşlemesi olmak zorunda değildir.

İşte bu noktada yükleyiciler devreye girer. Yükleyici, bir şablon adını (bir tanımlayıcı dizesi) almaktan ve Latte'ye kaynak kodunu sağlamaktan sorumlu bir nesnedir. Latte bu görev için tamamen yapılandırılmış yükleyiciye güvenir. Bu sadece $latte->render('main.latte') aracılığıyla talep edilen ilk şablon için değil, aynı zamanda {include ...}, {layout ...}, {embed ...} veya {import ...} gibi etiketler kullanılarak içinde referans verilen her şablon için de geçerlidir.

Neden özel bir yükleyici kullanmalı?

  • Alternatif kaynaklardan yükleme:** Bir veritabanında, bir önbellekte (Redis veya Memcached gibi), bir sürüm kontrol sisteminde (Git gibi, belirli bir işleme dayalı olarak) depolanan veya dinamik olarak oluşturulan şablonları getirin.
  • Özel adlandırma kurallarını uygulama:** Şablonlar için daha kısa takma adlar kullanmak veya belirli bir arama yolu mantığı uygulamak isteyebilirsiniz (örneğin, önce bir tema dizinine bakmak, ardından varsayılan bir dizine geri dönmek).
  • Güvenlik veya erişim kontrolü ekleme:** Özel bir yükleyici, belirli şablonları yüklemeden önce kullanıcı izinlerini doğrulayabilir.
  • Ön işleme:** Genel olarak tavsiye edilmese de(derleyici geçişleri daha iyidir), bir yükleyici şablon içeriğini Latte'ye vermeden önce teorik olarak ön işleme tabi tutabilir.

    Latte\Engine örneğiniz için yükleyiciyi setLoader() yöntemini kullanarak yapılandırırsınız:

$latte = new Latte\Engine;

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

Bir yükleyici Latte\Loader arayüzünü uygulamalıdır.

Yerleşik Yükleyiciler

Latte birkaç standart yükleyici sağlar:

FileLoader

Bu, başka bir yükleyici belirtilmemişse Latte\Engine tarafından kullanılan varsayılan yükleyicidir. Şablonları doğrudan dosya sisteminden yükler.

İsteğe bağlı olarak erişimi kısıtlamak için bir kök dizin ayarlayabilirsiniz:

use Latte\Loaders\FileLoader;

// Aşağıdakiler yalnızca /var/www/html/templates içindeki şablonların yüklenmesine izin verecektir
$loader = new FileLoader('/var/www/html/templates');
$latte->setLoader($loader);

// $latte->render('../../../etc/passwd'); // Bu bir istisna oluşturur

// Render template located at /var/www/html/templates/pages/contact.latte
$latte->render('pages/contact.latte');

Mutlak bir yol verilmediği sürece, {include} veya {layout} gibi etiketler kullanıldığında şablon adlarını geçerli şablona göre çözümler.

StringLoader

Bu yükleyici, şablon içeriğini, anahtarların şablon adları (tanımlayıcılar) ve değerlerin şablon kaynak kodu dizeleri olduğu bir ilişkisel diziden alır. Şablonların PHP kodu içinde saklanabileceği testler veya küçük uygulamalar için özellikle kullanışlı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ğinde daha fazla şablon ekleyin
]);

$latte->setLoader($loader);

$latte->render('main.latte', ['name' => 'World']);
// Çıktılar: Merhaba Dünya, include aşağıdaki gibidir: Included content: 10

Diğer adlandırılmış dize şablonlarına başvuran içerme veya kalıtıma ihtiyaç duymadan doğrudan bir dizeden yalnızca tek bir şablon oluşturmanız gerekiyorsa, StringLoader adresini dizi olmadan kullanırken dizeyi doğrudan render() veya renderToString() adresine aktarabilirsiniz:

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

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

Özel Yükleyici Oluşturma

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

Şimdi her bir yöntemin ne yapması gerektiğine bakalım.

getContent (string $name): string

Bu, yükleyicinin temel yöntemidir. Sorumluluğu, $name tarafından tanımlanan şablon için tam kaynak kodu içeriğini almak ve döndürmektir ( $latte->render() 'a aktarıldığı veya getReferredName() tarafından döndürüldüğü gibi).

Şablon bulunamaz veya şablona erişilemezse, bu yöntem bir Latte\RuntimeException atmalıdır.

public function getContent(string $name): string
{
	// Örnek: Varsayımsal bir dahili depolama alanından getirme
	$content = $this->storage->read($name);
	if ($content === null) {
		throw new Latte\RuntimeException("Template '$name' cannot be loaded.");
	}
	return $content;
}

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

Bu yöntem, {include}, {layout} gibi etiketler içinde kullanılan şablon adlarının çözümlenmesiyle ilgilenir. Latte, örneğin main.latte içinde {include 'partial.latte'} ile karşılaştığında, bu yöntemi $name = 'partial.latte' ve $referringName = 'main.latte' ile çağırır.

Yöntemin görevi, $name adresini, $referringName tarafından sağlanan bağlama dayalı olarak diğer yükleyici yöntemlerini çağırırken kullanılacak kanonik bir tanımlayıcıya (örneğin, mutlak bir yol, benzersiz bir veritabanı anahtarı) çözümlemektir.

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

getUniqueId (string $name): string

Latte performans için derlenmiş şablon önbelleğini kullanır. Derlenen her şablon dosyası, kaynak şablonun tanımlayıcısından türetilen benzersiz bir isme ihtiyaç duyar. Bu yöntem, $name şablonunu özel olarak tanımlayan bir dize sağlar.

Dosya tabanlı şablonlar için mutlak yol işe yarayabilir. Veritabanı şablonları için, bir önek ve veritabanı kimliğinin bir kombinasyonu yaygındır.

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

Örnek: Basit Veritabanı Yükleyici

Bu örnek, name (benzersiz tanımlayıcı), content ve updated_at sütunlarıyla templates adlı bir veritabanı tablosunda depolanan şablonları alan bir yükleyicinin temel yapısını göstermektedir.

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\RuntimeException("Template '$name' not found in database.");
		}
		return $content;
	}

	// Bu basit örnek, şablon adlarının ('ana sayfa', 'makale', vb.)
	// benzersiz kimliklerdir ve şablonlar birbirlerine göreceli olarak referans vermezler.
	public function getReferredName(string $name, string $referringName): string
	{
		return $name;
	}

	public function getUniqueId(string $name): string
	{
		// Burada bir önek ve ismin kendisini kullanmak benzersizdir ve yeterlidir
		return 'db_' . $name;
	}
}

// Kullanım şekli:
$pdo = new \PDO(/* connection details */);
$loader = new DatabaseLoader($pdo);
$latte->setLoader($loader);
$latte->render('homepage'); // DB'den 'anasayfa' adlı şablonu yükler

Özel yükleyiciler, Latte şablonlarınızın nereden geldiği üzerinde tam kontrol sahibi olmanızı sağlayarak çeşitli depolama sistemleri ve iş akışlarıyla entegrasyona olanak tanır.

versiyon: 3.0