Razširjanje Latte

Latte je zasnovan z mislijo na razširljivost. Čeprav njegov standardni nabor značk, filtrov in funkcij pokriva številne primere uporabe, pogosto potrebujete dodati lastno specifično logiko ali pomožna orodja. Ta stran ponuja pregled načinov, kako razširiti Latte, da bo popolnoma ustrezal zahtevam vašega projekta – od preprostih pomočnikov do kompleksne nove sintakse.

Načini razširitve Latte

Tukaj je hiter pregled glavnih načinov, kako lahko prilagodite in razširite Latte:

  • Filtri po meri: Za formatiranje ali preoblikovanje podatkov neposredno v izpisu predloge (npr. {$var|myFilter}). Idealno za naloge, kot so formatiranje datumov, urejanje besedila ali uporaba specifičnega ubežanja znakov. Uporabite jih lahko tudi za urejanje večjih blokov vsebine HTML tako, da vsebino ovijete v anonimni {block} in nanjo uporabite filter po meri.
  • Funkcije po meri: Za dodajanje ponovno uporabne logike, ki jo je mogoče klicati znotraj izrazov v predlogi (npr. {myFunction($arg1, $arg2)}). Uporabno za izračune, dostop do pomožnih funkcij aplikacije ali generiranje majhnih delov vsebine.
  • Oznake po meri: Za ustvarjanje popolnoma novih jezikovnih konstruktov ({mytag}...{/mytag} ali n:mytag). Oznake ponujajo največ možnosti, omogočajo definiranje lastnih struktur, nadzor nad razčlenjevanjem predloge in implementacijo kompleksne logike izrisa.
  • Prevajalni prehodi: Funkcije, ki spreminjajo abstraktno sintaktično drevo (AST) predloge po razčlenjevanju, vendar pred generiranjem kode PHP. Uporabljajo se za napredne optimizacije, varnostne preglede (kot je Sandbox) ali samodejne spremembe kode.
  • Nalagatelji po meri: Za spremembo načina, kako Latte išče in nalaga datoteke predlog (npr. nalaganje iz baze podatkov, šifriranega pomnilnika itd.).

Izbira prave metode razširitve je ključna. Preden ustvarite zapleteno značko, razmislite, ali bi zadostoval preprostejši filter ali funkcija. Poglejmo si primer: implementacija generatorja Lorem ipsum, ki kot argument sprejme število besed za generiranje.

  • Kot značka? {lipsum 40} – Možno, vendar so značke primernejše za krmilne strukture ali generiranje zapletenih oznak. Značk ni mogoče uporabiti neposredno v izrazih.
  • Kot filter? {=40|lipsum} – Tehnično deluje, vendar so filtri namenjeni preoblikovanju vhodne vrednosti. Tukaj je 40 argument, ne vrednost, ki se preoblikuje. To se zdi semantično napačno.
  • Kot funkcija? {lipsum(40)} – To je najbolj naravna rešitev! Funkcije sprejemajo argumente in vračajo vrednosti, kar je idealno za uporabo v katerem koli izrazu: {var $text = lipsum(40)}.

Splošno priporočilo: Uporabljajte funkcije za izračune/generiranje, filtre za preoblikovanje in značke za nove jezikovne konstrukte ali zapletene oznake. Prehode uporabljajte za manipulacijo z AST in nalagatelje za pridobivanje predlog.

Neposredna registracija

Za pomožna orodja, specifična za projekt, ali hitre razširitve Latte omogoča neposredno registracijo filtrov in funkcij v objekt Latte\Engine.

Za registracijo filtra uporabite metodo addFilter(). Prvi argument vaše filtrirne funkcije bo vrednost pred znakom |, naslednji argumenti pa so tisti, ki se posredujejo za dvopičjem :.

$latte = new Latte\Engine;

// Definicija filtra (klicni objekt: funkcija, statična metoda itd.)
$myTruncate = fn(string $s, int $length = 50) => mb_substr($s, 0, $length);

// Registracija
$latte->addFilter('truncate', $myTruncate);

// Uporaba v predlogi: {$text|truncate} ali {$text|truncate:100}

Lahko registrirate tudi Nalagatelj filtrov (Filter Loader), funkcijo, ki dinamično zagotavlja klicne objekte filtrov glede na zahtevano ime:

$latte->addFilterLoader(fn(string $name) => /* vrne klicni objekt ali null */);

Za registracijo funkcije, uporabne v izrazih predloge, uporabite addFunction().

$latte = new Latte\Engine;

// Definicija funkcije
$isWeekend = fn(DateTimeInterface $date) => $date->format('N') >= 6;

// Registracija
$latte->addFunction('isWeekend', $isWeekend);

// Uporaba v predlogi: {if isWeekend($myDate)}Vikend!{/if}

Več informacij najdete v razdelku Ustvarjanje filtrov po meri in Funkcij.

Robusten način: Razširitev Latte

Medtem ko je neposredna registracija preprosta, je standardni in priporočeni način za pakiranje in distribucijo razširitev Latte prek razredov Extension. Razširitev služi kot osrednja konfiguracijska točka za registracijo več značk, filtrov, funkcij, prevajalnih prehodov in drugih elementov.

Zakaj uporabljati razširitve?

  • Organizacija: Ohranja povezane razširitve (značke, filtri itd. za določeno funkcijo) skupaj v enem razredu.
  • Ponovna uporabnost in deljenje: Enostavno zapakirate svoje razširitve za uporabo v drugih projektih ali za deljenje s skupnostjo (npr. prek Composerja).
  • Polna moč: Značke po meri in prevajalne prehode lahko registrirate samo prek razširitev.

Registracija razširitve

Razširitev se registrira v Latte z metodo addExtension() (ali prek konfiguracijske datoteke):

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

Če registrirate več razširitev in te definirajo enako poimenovane značke, filtre ali funkcije, ima prednost zadnja dodana razširitev. To tudi pomeni, da lahko vaše razširitve prepišejo izvorne značke/filtre/funkcije.

Kadar koli naredite spremembo v razredu in samodejno osveževanje ni izklopljeno, bo Latte samodejno ponovno prevedel vaše predloge.

Ustvarjanje razširitve

Za ustvarjanje lastne razširitve morate ustvariti razred, ki deduje od Latte\Extension. Za predstavo, kako taka razširitev izgleda, si oglejte vgrajeno CoreExtension.

Poglejmo si metode, ki jih lahko implementirate:

beforeCompile (Latte\Engine $engine): void

Pokliče se pred prevajanjem predloge. Metodo lahko uporabite na primer za inicializacije, povezane s prevajanjem.

getTags(): array

Pokliče se med prevajanjem predloge. Vrne asociativno polje ime značke ⇒ klicni objekt, kar so funkcije za razčlenjevanje značk. Več informacij.

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

Značka n:baz predstavlja čisti n:atribut, torej značko, ki jo je mogoče zapisati samo kot atribut.

Pri značkah foo in bar Latte samodejno prepozna, ali gre za parne značke, in če da, jih je mogoče samodejno zapisati z n:atributi, vključno z različicami s predponami n:inner-foo in n:tag-foo.

Vrstni red izvajanja takšnih n:atributov je določen z njihovim vrstnim redom v polju, ki ga vrne metoda getTags(). Tako se n:foo vedno izvede pred n:bar, tudi če so atributi v HTML oznaki navedeni v obratnem vrstnem redu kot <div n:bar="..." n:foo="...">.

Če morate določiti vrstni red n:atributov med več razširitvami, uporabite pomožno metodo order(), kjer parameter before xor after določa, katere značke so razvrščene pred ali za značko.

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

getPasses(): array

Pokliče se med prevajanjem predloge. Vrne asociativno polje ime prehoda ⇒ klicni objekt, kar so funkcije, ki predstavljajo t.i. prevajalni prehodi, ki prehajajo in spreminjajo AST.

Tudi tukaj lahko uporabite pomožno metodo order(). Vrednost parametrov before ali after je lahko * s pomenom pred/po vseh.

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

beforeRender (Latte\Engine $engine): void

Pokliče se pred vsakim izrisom predloge. Metodo lahko uporabite na primer za inicializacijo spremenljivk, ki se uporabljajo med izrisom.

getFilters(): array

Pokliče se pred izrisom predloge. Vrne filtre kot asociativno polje ime filtra ⇒ klicni objekt. Več informacij.

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

getFunctions(): array

Pokliče se pred izrisom predloge. Vrne funkcije kot asociativno polje ime funkcije ⇒ klicni objekt. Več informacij.

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

getProviders(): array

Pokliče se pred izrisom predloge. Vrne polje ponudnikov, ki so običajno objekti, ki jih značke uporabljajo med izvajanjem. Dostopa se jim prek $this->global->.... Več informacij.

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

getCacheKey (Latte\Engine $engine): mixed

Pokliče se pred izrisom predloge. Vračana vrednost postane del ključa, katerega zgoščena vrednost je vsebovana v imenu datoteke prevedene predloge. Za različne vračane vrednosti torej Latte generira različne datoteke predpomnilnika.

različica: 3.0