Φορτωτές προτύπων

Οι φορτωτές είναι ο μηχανισμός που χρησιμοποιεί το Latte για να ανακτήσει τον πηγαίο κώδικα των προτύπων σας. Συνήθως, τα πρότυπα είναι αρχεία αποθηκευμένα στο δίσκο, αλλά το ευέλικτο σύστημα φορτωτών του Latte σας επιτρέπει να τα φορτώνετε σχεδόν από οπουδήποτε, ή ακόμα και να τα δημιουργείτε δυναμικά.

Τι είναι ο φορτωτής;

Συνήθως, όταν εργάζεστε με πρότυπα, σκέφτεστε τα αρχεία .latte που βρίσκονται στη δομή καταλόγου του έργου σας. Αυτό το χειρίζεται ο προεπιλεγμένος FileLoader της Latte. Ωστόσο, η σύνδεση μεταξύ του ονόματος ενός προτύπου (όπως 'main.latte' ή 'components/card.latte') και του πραγματικού περιεχομένου του πηγαίου κώδικα δεν πρέπει να είναι μια άμεση αντιστοίχιση της διαδρομής του αρχείου.

Σε αυτό το σημείο έρχονται οι φορτωτές. Ένας φορτωτής είναι ένα αντικείμενο που είναι υπεύθυνο για τη λήψη ενός ονόματος προτύπου (μια συμβολοσειρά αναγνώρισης) και την παροχή στον Latte του πηγαίου του κώδικα. Το Latte βασίζεται εξ ολοκλήρου στον ρυθμισμένο φορτωτή για αυτό το έργο. Αυτό ισχύει όχι μόνο για το αρχικό πρότυπο που ζητείται μέσω του $latte->render('main.latte') αλλά και για κάθε πρότυπο που αναφέρεται μέσα σε αυτό χρησιμοποιώντας ετικέτες όπως {include ...}, {layout ...}, {embed ...} ή {import ...}.

Γιατί να χρησιμοποιήσετε έναν προσαρμοσμένο φορτωτή;

  • Φορτώνοντας από εναλλακτικές πηγές: Φέρτε πρότυπα αποθηκευμένα σε μια βάση δεδομένων, μια κρυφή μνήμη (όπως το Redis ή το Memcached), ένα σύστημα ελέγχου εκδόσεων (όπως το Git, με βάση μια συγκεκριμένη δέσμευση), ή που παράγονται δυναμικά.
  • Εφαρμογή προσαρμοσμένων συμβάσεων ονοματοδοσίας: Μπορεί να θέλετε να χρησιμοποιήσετε συντομότερα ψευδώνυμα για τα πρότυπα ή να εφαρμόσετε μια συγκεκριμένη λογική διαδρομής αναζήτησης (π.χ., να αναζητάτε πρώτα σε έναν κατάλογο θεμάτων, και στη συνέχεια να επιστρέφετε σε έναν προεπιλεγμένο κατάλογο).
  • Προσθήκη ασφάλειας ή ελέγχου πρόσβασης: Ένας προσαρμοσμένος φορτωτής θα μπορούσε να ελέγχει τα δικαιώματα του χρήστη πριν από τη φόρτωση ορισμένων προτύπων.
  • Προεπεξεργασία: Αν και γενικά αποθαρρύνεται(τα περάσματα του μεταγλωττιστή είναι καλύτερα), ένας φορτωτής θα μπορούσε θεωρητικά να προεπεξεργάζεται το περιεχόμενο των προτύπων πριν το παραδώσει στο Latte.

Ρυθμίζετε τον φορτωτή για την περίπτωσή σας Latte\Engine χρησιμοποιώντας τη μέθοδο setLoader():

$latte = new Latte\Engine;

// Χρήση του προεπιλεγμένου FileLoader για αρχεία στο '/path/to/templates'
$loader = new Latte\Loaders\FileLoader('/path/to/templates');
$latte->setLoader($loader);

Ένας φορτωτής πρέπει να υλοποιεί τη διεπαφή Latte\Loader.

Ενσωματωμένοι φορτωτές

Η Latte παρέχει διάφορους τυπικούς φορτωτές:

FileLoader

Αυτός είναι ο προεπιλεγμένος φορτωτής που χρησιμοποιείται από το Latte\Engine εάν δεν έχει καθοριστεί άλλος φορτωτής. Φορτώνει τα πρότυπα απευθείας από το σύστημα αρχείων.

Μπορείτε προαιρετικά να ορίσετε έναν ριζικό κατάλογο για να περιορίσετε την πρόσβαση:

use Latte\Loaders\FileLoader;

// Τα παρακάτω θα επιτρέψουν μόνο τη φόρτωση προτύπων μέσα στο /var/www/html/templates
$loader = new FileLoader('/var/www/html/templates');
$latte->setLoader($loader);

// $latte->render('../../../../etc/passwd'); // Αυτό θα προκαλούσε μια εξαίρεση

// Απόδοση προτύπου που βρίσκεται στη διεύθυνση /var/www/html/templates/pages/contact.latte
$latte->render('pages/contact.latte');

{include} {layout}, εκτός αν έχει δοθεί απόλυτη διαδρομή.

StringLoader

Αυτός ο φορτωτής ανακτά περιεχόμενο προτύπων από έναν συσχετιστικό πίνακα όπου τα κλειδιά είναι ονόματα προτύπων (αναγνωριστικά) και οι τιμές είναι οι συμβολοσειρές του πηγαίου κώδικα προτύπων. Είναι ιδιαίτερα χρήσιμο για δοκιμές ή μικρές εφαρμογές όπου τα πρότυπα μπορεί να είναι αποθηκευμένα μέσα στον ίδιο τον κώδικα PHP.

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}',
	// Προσθέστε περισσότερα πρότυπα ανάλογα με τις ανάγκες
]);

$latte->setLoader($loader);

$latte->render('main.latte', ['name' => 'World']);
// Έξοδοι: Περιλαμβάνεται το περιεχόμενο: Hello World, include is below:Included content: 10

Αν χρειάζεστε μόνο την απόδοση ενός προτύπου απευθείας από μια συμβολοσειρά χωρίς να χρειάζεστε include ή κληρονομικότητα που παραπέμπει σε άλλα ονομαστικά πρότυπα συμβολοσειρών, μπορείτε να περάσετε τη συμβολοσειρά απευθείας στο render() ή στο renderToString() όταν χρησιμοποιείτε το StringLoader χωρίς πίνακα:

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

$templateString = 'Hello {$name}!';
$output = $latte->renderToString($templateString, ['name' => 'Alice']);
// $output περιέχει 'Hello Alice!'

Δημιουργία ενός προσαρμοσμένου φορτωτή

Για να δημιουργήσετε το δικό σας φορτωτή (π.χ. για να φορτώσετε πρότυπα από μια βάση δεδομένων, μια κρυφή μνήμη, έναν έλεγχο έκδοσης ή άλλη πηγή), πρέπει να δημιουργήσετε μια κλάση που υλοποιεί τη διεπαφή Latte\Loader.

Ας δούμε τι πρέπει να κάνει κάθε μέθοδος.

getContent (string $name): string

Αυτή είναι η βασική μέθοδος του φορτωτή. Η αρμοδιότητά της είναι να ανακτήσει και να επιστρέψει το πλήρες περιεχόμενο του πηγαίου κώδικα για το πρότυπο που προσδιορίζεται από το $name (όπως περνάει στο $latte->render() ή επιστρέφεται από την getReferredName()).

Εάν το πρότυπο δεν μπορεί να βρεθεί ή να προσπελαστεί, αυτή η μέθοδος πρέπει να πετάξει ένα Latte\RuntimeException.

public function getContent(string $name): string
{
	// Παράδειγμα: από έναν υποθετικό εσωτερικό αποθηκευτικό χώρο
	$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

Αυτή η μέθοδος χειρίζεται την επίλυση των ονομάτων προτύπων που χρησιμοποιούνται σε ετικέτες όπως {include}, {layout}, κ.λπ. Όταν η Latte συναντά, για παράδειγμα, το {include 'partial.latte'} μέσα στο main.latte, καλεί αυτή τη μέθοδο με το $name = 'partial.latte' και το $referringName = 'main.latte'.

Η δουλειά της μεθόδου είναι να επιλύσει το $name σε ένα κανονικό αναγνωριστικό (π.χ. μια απόλυτη διαδρομή, ένα μοναδικό κλειδί βάσης δεδομένων), το οποίο θα χρησιμοποιηθεί κατά την κλήση άλλων μεθόδων φορτωτή, με βάση το πλαίσιο που παρέχεται από το $referringName.

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

getUniqueId (string $name): string

Η Latte χρησιμοποιεί την κρυφή μνήμη προτύπων που έχει μεταγλωττιστεί για λόγους απόδοσης. Κάθε αρχείο μεταγλωττισμένου προτύπου χρειάζεται ένα μοναδικό όνομα που προέρχεται από το αναγνωριστικό του πηγαίου προτύπου. Αυτή η μέθοδος παρέχει μια συμβολοσειρά που μοναδικά προσδιορίζει το πρότυπο $name.

Για πρότυπα που βασίζονται σε αρχεία, η απόλυτη διαδρομή μπορεί να λειτουργήσει. Για πρότυπα βάσης δεδομένων, ένας συνδυασμός προθέματος και του αναγνωριστικού της βάσης δεδομένων είναι συνηθισμένος.

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

Παράδειγμα: Φορτωτής απλής βάσης δεδομένων

Αυτό το παράδειγμα δείχνει τη βασική δομή ενός φορτωτή που ανακτά πρότυπα αποθηκευμένα σε έναν πίνακα της βάσης δεδομένων με όνομα templates και στήλες name (μοναδικό αναγνωριστικό), content και updated_at.

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;
	}

	// Αυτό το απλό παράδειγμα υποθέτει ονόματα προτύπων ('homepage', 'article', κ.λπ.)
	// είναι μοναδικά αναγνωριστικά και τα πρότυπα δεν αναφέρονται σχετικά μεταξύ τους.
	public function getReferredName(string $name, string $referringName): string
	{
		return $name;
	}

	public function getUniqueId(string $name): string
	{
		// Η χρήση ενός προθέματος και το ίδιο το όνομα είναι μοναδικό και επαρκές εδώ
		return 'db_' . $name;
	}
}

// Χρήση:
$pdo = new \PDO(/* connection details */);
$loader = new DatabaseLoader($pdo);
$latte->setLoader($loader);
$latte->render('homepage'); // από τη ΒΔ.

Οι προσαρμοσμένοι φορτωτές σας δίνουν πλήρη έλεγχο του από πού προέρχονται τα πρότυπα Latte, επιτρέποντας την ενσωμάτωση με διάφορα συστήματα αποθήκευσης και ροές εργασίας.

έκδοση: 3.0