Einen Template-Operator in PHP schreiben #

Diese Anleitung richtet sich an PHP-Entwickler, die Templates einen neuen Operator geben, etwa {$amount|acmereport_money( 'EUR' )}. Ein Operator ist eine PHP-Klasse, die die Template-Engine (lib/eztemplate/) mit dem weitergeleiteten Wert und den Parametern aufruft. Template-Autoren finden die mitgelieferten Operatoren im Abschnitt Template-Operatoren; die Anwendungssicht ist Template-Operatoren schreiben.

Inhalt #

1. Schritt 1: den Autoload-Pfad registrieren
2. Schritt 2: den Operator auflisten
3. Schritt 3: die Operator-Klasse
4. Schritt 4: verwenden
5. Ein- und Ausgabe
6. Maskierung
7. Performance und kompilierte Templates
8. modify() testen

Schritt 1: den Autoload-Pfad registrieren #

extension/acmereport/settings/site.ini.append.php:

<?php /* #?ini charset="utf-8"?
[TemplateSettings]
ExtensionAutoloadPath[]=acmereport
*/ ?>

Die Template-Engine liest dann extension/acmereport/autoloads/eztemplateautoload.php, so wie sie es für ezjscore tut (extension/ezjscore/settings/site.ini.append.php).

Schritt 2: den Operator auflisten #

extension/acmereport/autoloads/eztemplateautoload.php:

<?php
$eZTemplateOperatorArray = array();
$eZTemplateOperatorArray[] = array(
    'script' => 'extension/acmereport/autoloads/acmereporttemplateoperators.php',
    'class' => 'acmeReportTemplateOperators',
    'operator_names' => array( 'acmereport_money' ) );

Die Engine lädt die Klasse erst, wenn ein Template einen der Namen verwendet, sodass viele Operatoren nichts kosten, bis sie verwendet werden. extension/ezjscore/autoloads/eztemplateautoload.php registriert json_encode, ezscript und andere auf dieselbe Weise.

Schritt 3: die Operator-Klasse #

extension/acmereport/autoloads/acmereporttemplateoperators.php:

<?php
class acmeReportTemplateOperators
{
    function operatorList()
    {
        return array( 'acmereport_money' );
    }

    function namedParameterPerOperator()
    {
        return true;
    }

    function namedParameterList()
    {
        return array(
            'acmereport_money' => array(
                'currency' => array( 'type' => 'string', 'required' => false, 'default' => 'EUR' ),
                'decimals' => array( 'type' => 'integer', 'required' => false, 'default' => 2 ) ) );
    }

    function modify( $tpl, $operatorName, $operatorParameters, $rootNamespace, $currentNamespace,
                     &$operatorValue, $namedParameters )
    {
        switch ( $operatorName )
        {
            case 'acmereport_money':
            {
                $decimals = max( 0, min( 4, (int)$namedParameters['decimals'] ) );
                $operatorValue = number_format( (float)$operatorValue, $decimals ) . ' ' . $namedParameters['currency'];
            } break;
        }
    }
}

Schritt 4: verwenden #

{$item.amount|acmereport_money()|wash}
{$item.amount|acmereport_money( 'USD', 0 )|wash}

Generieren Sie die Autoloads neu und leeren Sie die Template-Caches (php bin/php/ezcache.php --clear-tag=template); unter Velocity verwenden Sie exp:velocity deploy.

Ein- und Ausgabe #

Ein Operator, der ohne weitergeleiteten Wert verwendet wird ({acmereport_money( 12 )}), erhält null in $operatorValue; deklarieren Sie den Wert als Parameter, wenn er so verwendet wird.

Maskierung #

Geben Sie Werte zurück, kein HTML, und lassen Sie das Template sie über |wash ausgeben. Wenn ein Operator Markup zurückgeben muss, maskieren Sie jedes Eingabestück darin mit htmlspecialchars( $value, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8' ) (die Flags sind für PHP 8.0 nötig, siehe Ausgaben aus PHP maskieren), und fügen Sie niemals Inline-style="" oder <script> ein (Content Security Policy für Ihren Code).

Performance und kompilierte Templates #

• Operatoren laufen bei jedem Rendern, auch in Schleifen. Halten Sie modify() schnell und frei von Datenbankabfragen; Daten gehören in eine Fetch-Funktion (Eine Fetch-Funktion schreiben).
• Templates werden zu PHP kompiliert. Reine Kernel-Operatoren können sich mit operatorTemplateHints() selbst beschreiben, damit der Compiler sie inline einsetzt (kernel/common/ezkerneloperator.php ist ein Beispiel); Ihr Operator funktioniert auch ohne.
• Keine Nebenwirkungen: Innerhalb eines {cache-block} läuft der Operator erst wieder, wenn der Block abläuft.

modify() testen #

modify() ist eine einfache Methode; rufen Sie sie in einem Test ohne Datenbank auf:

public function testMoneyFormatsTwoDecimals()
{
    $operators = new acmeReportTemplateOperators();
    $value = 12.5;
    $operators->modify( null, 'acmereport_money', array(), '', '', $value,
                        array( 'currency' => 'EUR', 'decimals' => 2 ) );
    $this->assertSame( '12.50 EUR', $value );
}

Verwandte Seiten #

• Template-Operatoren (Erweiterungsentwickler)
• Das Muster Template-Operator
• Die Template-Sprache
• Freie Dokumentation: diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.