`[t]`-Modul programmieren

Um Textdateien einzubinden, verwendet man in Aneamal das [t]-Element. Dabei kann man den Inhalt der Textdatei von einem Zusatzmodul auch noch verarbeiten und aufbereiten lassen. Der Name eines solchen Moduls könnte zum Beispiel excel, kochrezept oder rex lauten und wird im [t]-Element nach einem Bindestrich angegeben:

[t-rex]->dateipfad-einer-textdatei

Anstatt eine Textdatei zu laden, kann man das Zusatzmodul auch mit einer eingebetteten Pseudodatei nutzen. Außerdem kann man hinter einem Doppelpunkt im [t]-Element bei Bedarf ein Argument mitliefern:

[t-rex:cuddly]
|Der beißt nicht, der spielt nur.

Auf dieser Seite findest Du erklärt, wie man ein [t]-Modul zur Verarbeitung von Textdateien baut. Diese Informationen richten sich an Programmierer – PHP-Kenntnisse werden vorausgesetzt.

Platz fürs Zusatzmodul

Das Modul wird in einem Unterordner des aneamal-Verzeichnisses abgelegt, der t-rex heißt, wenn der Name des Moduls rex ist. Die Hauptdatei darin muss index.php heißen. Insgesamt lautet der Dateipfad der Hauptdatei also /aneamal/t-rex/index.php. Beachte, dass der Dateipfad immer kleinbuchstabig ist. Weitere Dateien werden nicht erwartet, können aber nach Gusto des Entwicklers im gleichen Ordner angelegt werden.

Aufbau von index.php

Die Hauptdatei des Zusatzmoduls sollte wie folgt aufgebaut sein.

<?php namespace dein_einzigartiger_namensraum;

// hier Konstanten, Funktion etc. einfügen (optional)

return function (array $_) {

    // hier Hauptprogramm einfügen

    return $verarbeiteter_text;
};

Das Modul soll also mit return eine unbenannte function an den Aneamal-Konverter geben, in dem die Verarbeitung des Inhalts einer Textdatei beziehungsweise einer eingebetteten Pseudodatei vollzogen wird. Dafür übergibt der Aneamal-Konverter der Funktion Informationen in Form eines Felds (array), hier beispielhaft $_ genannt.

Parameter der unbenannten Hauptfunktion

Das vom Aneamal-Konverter ans Zusatzmodul übergebene Feld, hier beispielhaft $_ genannt, enthält vier Elemente, allesamt vom Typ Zeichenkette (string):

$_[0]: enthält den Inhalt der Textdatei beziehungsweise eingebetteten Pseudodatei, beispielsweise: Ich habe Hunger!
$_[1]: enthält das optionale Zusatzargument beim Einbinden der Textdatei, im Beispiel: laut
$_[2]: enthält eine URL zum Verzeichnis des Zusatzmoduls, relativ zur Domain, ohne Schrägstrich am Ende, beispielsweise: /aneamal/t-felin
$_[3]: enthält eine URL, relativ zur Domain, welche ohne Schrägstrich am Ende auf jenes Verzeichnis zeigt, in welchem die Aneamaldatei liegt, die das Modul gerade einbindet, in diesem Fall: /projekt/aneamal/module

Beispielmodul

Als Beispiel habe ich ein Modul programmiert, dass Texte jeder Sprache nach Kätzisch übersetzt:

<?php namespace felina\katzenklang;

return function (array $_) {
    // Parameter auf benannte Variablen verteilen
    list ($text, $lautstaerke, $pfad) = $_;

    // so viele Miaus zusammenfügen wie Worte im Text existieren
    $anzahl = count (preg_split ('/\s+/', trim ($text)));
    $miauen = rtrim (str_repeat ('miau ', $anzahl));

    // abhängig von der Lautstärke in Großbuchstaben umwandeln
    if ($lautstaerke === 'laut'):
        $miauen = strtoupper ($miauen) . '!';
    else:
        $miauen = ucfirst ($miauen) . '.';
    endif;

    // HTML-Code fürs obligatorische Katzenbild vorbereiten
    $pfad = htmlspecialchars ($pfad, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
    $bild = '<img src="' . $pfad . '/katze.png" style="height:1em" alt="">';

    // Katzensprache und Antlitz an den Aneamal-Konverter übergeben
    return '<p>' . $miauen . ' ' . $bild . '</p>';
};

Das Programm habe ich als index.php zusammen mit einem Bild in den Ordner /aneamal/t-felin/ gelegt, sodass die Verzeichnisstruktur nun so aussieht:

 aneamal/
 └─ t-felin/
    └─ index.php
    └─ katze.png

Probieren wir es aus! Grün ist hinterlegt, was in einer Aneamaldatei steht. Gelb ist hinterlegt, wie es dann im Webbrowser angezeigt wird:

[t-felin]
|Eine schwarze Katze von rechts bringt Freude!

Miau miau miau miau miau miau miau.

Demo Nummer zwei – in der Textdatei hunger.txt steht diesmal der Satz: „Ich habe Hunger!“

[t-felin:laut]->hunger.txt

MIAU MIAU MIAU!

Bitte beachten

Ein Modul soll problemlos umbenannt werden können

Baue den Namen des Ordners, in dem dein Zusatzmodul liegt, nicht fest in dein Modul ein. Verwende stattdessen den übergebenen Parameter $_[2], wenn du einen Link zu Dateien in dem Modulordner benötigst. Hintergrund: Wenn du dein Zusatzmodul an jemanden weitergibst, der schon ein anderes Modul mit dem gleichen Namen nutzt, braucht er nur deinen Ordner umzubenennen, um beide Module nutzen zu können.

Verschiedene Module sollen parallel funktionieren

Damit es zu keinen Konflikten bei Namen von Funktionen und Konstanten zwischen verschiedenen Zusatzmodulen kommt, solltest du einen wirklich individuellen namespace am Anfang deiner PHP-Datei(en) verwenden.

Dein Modul muss UTF-8-kodierten HTML-Code ausgeben

Was deine Hauptfunktion zurückgibt, wird so in den HTML-Code deiner Webseite eingebaut. Es sollte sich also um gültiges HTML handeln und die Zeichenkodierung UTF-8 genutzt werden. UTF-8 ist nicht nur Aneamals Standardzeichensatz, sondern auch die mit Abstand am weitesten verbreitete Kodierung im weltweiten Netz. US-ASCII ist auch fein – das ist nämlich eine Teilmenge von UTF-8.

Dein Modul soll sicher sein

Mach keinen Quatsch. :)

[t]-Modul programmieren