Geliştiriciler için Uygulamalar
*******************************


Kurulum .[#toc-installation]
============================

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

```shell
composer require latte/latte
```

Desteklenen PHP sürümleri (en son yama 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 .[#toc-how-to-render-a-template]
=============================================================

Bir şablon nasıl oluşturulur? Sadece bu basit kodu kullanın:

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

$params = [ /* template variables */ ];
// veya $params = new TemplateParameters(/* ... */);

// çıktıya render et
$latte->render('template.latte', $params);
// veya değişkene dönüştürme
$output = $latte->renderToString('template.latte', $params);
```

Parametreler diziler veya daha da iyisi [nesne |#Parameters as a class] olabilir, bu da editörde tür denetimi ve öneri sağlayacaktır.

.[note]
Kullanım örneklerini [Latte examples |https://github.com/nette-examples/latte] deposunda da bulabilirsiniz.


Performans ve Önbellekleme .[#toc-performance-and-caching]
==========================================================

Latte şablonları son derece hızlıdır, çünkü Latte bunları doğrudan PHP koduna derler ve diskte önbelleğe alır. Bu nedenle, saf PHP ile yazılmış şablonlara kıyasla ekstra ek yükleri yoktur.

Kaynak dosyayı her değiştirdiğinizde önbellek otomatik olarak yeniden oluşturulur. Böylece geliştirme sırasında Latte şablonlarınızı rahatça düzenleyebilir ve değişiklikleri hemen tarayıcıda görebilirsiniz. Bu özelliği üretim ortamında devre dışı bırakabilir ve performanstan biraz tasarruf edebilirsiniz:

```php
$latte->setAutoRefresh(false);
```

Bir üretim sunucusuna yerleştirildiğinde, özellikle büyük uygulamalar için ilk önbellek oluşturma işlemi anlaşılabilir bir şekilde biraz zaman alabilir. Latte "önbellek izdihamına":https://en.wikipedia.org/wiki/Cache_stampede karşı yerleşik bir önleme sahiptir.
Bu, sunucunun çok sayıda eş zamanlı istek aldığı bir durumdur ve Latte'nin önbelleği henüz mevcut olmadığından, hepsi aynı anda oluşturacaktır. Bu da CPU'yu yükseltir.
Latte akıllıdır ve birden fazla eşzamanlı istek olduğunda, yalnızca ilk iş parçacığı önbelleği oluşturur, diğerleri bekler ve sonra kullanır.


Sınıf Olarak Parametreler .[#toc-parameters-as-a-class]
=======================================================

Değişkenleri şablona diziler olarak geçirmekten daha iyisi bir sınıf oluşturmaktır. [Tip güvenli gösterim |type-system], [IDE'de güzel öneri |recipes#Editors and IDE] ve [filtreler |extending-latte#Filters Using the Class] ile [fonksiyonları |extending-latte#Functions Using the Class] [kaydetmek |extending-latte#Filters Using the Class] için bir yol elde edersiniz.

```php
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şkenin Otomatik Çıkmasını Devre Dışı Bırakma .[#toc-disabling-auto-escaping-of-variable]
============================================================================================

Değişken bir HTML dizesi içeriyorsa, Latte'nin otomatik olarak (ve bu nedenle çift) kaçış yapmaması için onu işaretleyebilirsiniz. Bu, şablonda `|noescape` belirtme ihtiyacını ortadan kaldırır.

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

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

Latte ayrıca `Latte\HtmlStringable` arayüzünü uygulayan tüm nesnelerden kaçış yapmaz. Böylece, `__toString()` yöntemi otomatik olarak kaçılmayacak HTML kodu döndürecek olan kendi sınıfınızı oluşturabilirsiniz:

```php
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'),
];
```

.[warning]
 `__toString` yöntemi doğru HTML döndürmeli ve parametre kaçışını sağlamalıdır, aksi takdirde bir XSS güvenlik açığı oluşabilir!


Latte Filtreler, Etiketler vb. ile Nasıl Genişletilir? .[#toc-how-to-extend-latte-with-filters-tags-etc]
========================================================================================================

Latte'ye özel bir filtre, fonksiyon, etiket vb. nasıl eklenir? Latte'yi [genişletme |extending Latte] bölümünde bulabilirsiniz.
Yaptığınız değişiklikleri farklı projelerde yeniden kullanmak veya başkalarıyla paylaşmak istiyorsanız, [bir uzantı oluşturmalısınız |creating-extension].


Şablondaki Herhangi Bir Kod `{php ...}` .{toc: RawPhpExtension}
===============================================================

İçerisine sadece PHP ifadeleri yazılabilir. [`{do}` |tags#do] etiketini kullanamazsınız, bu nedenle örneğin `if ... else` gibi yapılar veya noktalı virgülle sonlandırılmış ifadeler ekleyemezsiniz.

Ancak, `{php ...}` etiketini ekleyen `RawPhpExtension` uzantısını kaydedebilirsiniz. Bunu herhangi bir PHP kodu eklemek için kullanabilirsiniz. Herhangi bir sandbox modu kuralına tabi değildir, bu nedenle kullanım şablon yazarının sorumluluğundadır.

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


Oluşturulan Kodun Kontrol Edilmesi .[#toc-checking-generated-code]{data-version:3.0.7}
======================================================================================

Latte şablonları PHP koduna derler. Elbette, oluşturulan kodun sözdizimsel olarak geçerli olmasını sağlar. Ancak, üçüncü parti eklentiler veya RawPhpExtension kullanıldığında, Latte oluşturulan dosyanın doğruluğunu garanti edemez.
Ayrıca, PHP'de sözdizimsel olarak doğru olan ancak yasak olan (örneğin, $this değişkenine bir değer atamak) ve PHP Derleme Hatasına neden olan bir kod yazabilirsiniz.
Böyle bir işlemi bir şablona yazarsanız, oluşturulan PHP koduna da dahil edilecektir. PHP'de iki yüzden fazla farklı yasaklı işlem olduğundan, Latte bunları tespit etmeyi amaçlamaz. PHP'nin kendisi bunları oluşturma sırasında işaretleyecektir ve bu genellikle bir sorun teşkil etmez.

Ancak, şablon derlemesi sırasında PHP Derleme Hatası içermediğini bilmek istediğiniz durumlar vardır. Özellikle şablonlar kullanıcılar tarafından düzenlenebiliyorsa veya [Sandbox |Sandbox] kullanıyorsanız. Böyle bir durumda, derleme sırasında şablonları kontrol ettirin.
Bu işlevi Engine::enablePhpLint() yöntemini kullanarak etkinleştirebilirsiniz. Kontrol için PHP ikilisini çağırması gerektiğinden, yolunu bir parametre olarak geçirin:

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

try {
	$latte->compile('home.latte');
} catch (Latte\CompileException $e) {
	// PHP'de Latte hatalarını ve ayrıca Derleme Hatasını yakalar
	echo 'Error: ' . $e->getMessage();
}
```


Sıkı Mod .[#toc-strict-mode]{data-version:3.0.8}
================================================

Sıkı ayrıştırma modunda, Latte eksik kapanış HTML etiketlerini kontrol eder ve ayrıca `$this` değişkeninin kullanımını devre dışı bırakır. Bunu açmak için:

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

 `declare(strict_types=1)` başlığıyla şablon oluşturmak için aşağıdakileri yapın:

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


Şablonlarda Çeviri .{toc: TranslatorExtension}
==============================================

Eklemek için `TranslatorExtension` uzantısını kullanın [`{_...}` |tags#_], [`{translate}` |tags#translate] ve filtre [`translate` |filters#translate] şablona eklenir. Şablonun değerlerini veya bölümlerini diğer dillere çevirmek için kullanılırlar. Değiştirge, çeviriyi gerçekleştiren yöntemdir (PHP çağrılabiliri):

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

	public function translate(string $original): string
	{
		// $this->lang'a göre $original'den $translated oluşturun
		return $translated;
	}
}

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

Çevirmen, şablon işlendiğinde çalışma zamanında çağrılır. Ancak Latte, şablon derlemesi sırasında tüm statik metinleri çevirebilir. Bu performans tasarrufu sağlar çünkü her dize yalnızca bir kez çevrilir ve sonuçta ortaya çıkan çeviri derlenmiş dosyaya yazılır. Bu, önbellek dizininde şablonun her dil için bir tane olmak üzere birden fazla derlenmiş sürümünü oluşturur. Bunu yapmak için sadece ikinci parametre olarak dili belirtmeniz gerekir:

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

Statik metin ile örneğin `{_'hello'}` veya `{translate}hello{/translate}` kastedilmektedir. `{_$foo}` gibi statik olmayan metinler çalışma zamanında çevrilmeye devam edecektir.

Şablon, `$params` dizisi olarak aldığı `{_$original, foo: bar}` veya `{translate foo: bar}` aracılığıyla çevirmene ek parametreler de iletebilir:

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


Hata Ayıklama ve Tracy .[#toc-debugging-and-tracy]
==================================================

Latte, geliştirmeyi mümkün olduğunca keyifli hale getirmeye çalışır. Hata ayıklama amacıyla, üç etiket vardır [`{dump}` |tags#dump], [`{debugbreak}` |tags#debugbreak] ve [`{trace}` |tags#trace].

Harika [hata ayıklama aracı Tracy |tracy:] 'yi yüklerseniz ve Latte eklentisini etkinleştirirseniz en fazla konforu elde edersiniz:

```php
// Tracy'nin
Tracy\Debugger::enable();

$latte = new Latte\Engine;
// Tracy'nin uzantısını etkinleştirir
$latte->addExtension(new Latte\Bridges\Tracy\TracyExtension);
```

Artık satır ve sütun vurgulamalı şablonlardaki hatalar da dahil olmak üzere tüm hataları düzgün bir kırmızı ekranda göreceksiniz[(video |https://github.com/nette/tracy/releases/tag/v2.9.0]).
Aynı zamanda, Tracy Bar olarak adlandırılan sağ alt köşede, tüm işlenmiş şablonları ve ilişkilerini (şablona veya derlenmiş koda tıklama imkanı dahil) ve değişkenleri açıkça görebileceğiniz Latte için bir sekme görünür:

[* latte-debugging.webp *]

Latte şablonları okunabilir PHP koduna derlediğinden, IDE'nizde rahatça adım atabilirsiniz.


Linter: Şablon Sözdizimini Doğrulama .{toc: Linter}
===================================================

Linter aracı tüm şablonları gözden geçirmenize ve sözdizimi hatalarını kontrol etmenize yardımcı olacaktır. Konsoldan başlatılır:

```shell
vendor/bin/latte-lint <path>
```

[Sıkı modu|#strict mode] etkinleştirmek için `--strict` parametresini kullanın.

Özel etiketler kullanıyorsanız, özelleştirilmiş Linter'ınızı da oluşturun, örneğin `custom-latte-lint`:

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

// autoload.php dosyasının gerçek yolunu girin
require __DIR__ . '/vendor/autoload.php';

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

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

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

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

```php
$latte = new Latte\Engine;
// burada $latte nesnesini yapılandırıyoruz
$linter = new Latte\Tools\Linter(engine: $latte);
```


Dizeden Şablon Yükleme .[#toc-loading-templates-from-a-string]
==============================================================

Belki de test amacıyla şablonları dosyalar yerine dizelerden yüklemeniz mi gerekiyor? [StringLoader |extending-latte#stringloader] size yardımcı olacaktır:

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

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


İstisna İşleyici .[#toc-exception-handler]
==========================================

Beklenen istisnalar için kendi işleyicinizi tanımlayabilirsiniz. İçinde yükseltilen istisnalar [`{try}` |tags#try] ve [sandbox |sandbox] 'ta ona aktarılır.

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

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


Otomatik Yerleşim Arama .[#toc-automatic-layout-lookup]
=======================================================

Etiketi kullanma [`{layout}` |template-inheritance#layout-inheritance]'de, şablon kendi üst şablonunu belirler. Düzenin otomatik olarak aranmasını sağlamak da mümkündür, bu da `{layout}` etiketini içermeleri gerekmeyeceğinden şablon yazmayı basitleştirecektir.

Bu, aşağıdaki şekilde gerçekleştirilir:

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

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

Şablonun bir düzene sahip olmaması gerekiyorsa, bunu `{layout none}` etiketiyle belirtecektir.