De:Snippets erstellen
From MODx Wiki
| Dieser Artikel kann noch eine Rechtschreibprüfung vertragen. Wenn du gut Deutsch kannst, schau mal drüber. |
| Dieser Artikel ist eine Übersetzung aus dem englischen Wiki.
Vielleicht gibt es noch Übersetzungsfehler oder andere Ungereimtheiten. Wenn du gut Englisch versteht vergleiche doch mal die beiden Artikel. |
Tipps
Hier sind einige Regeln, die als gutes Vorgehen für Add-On Entwickler befunden wurden. Du musst nicht alle exakt befolgen, aber es ist gut wenn du sie immer im Hinterkopf hast.
Die Id des aktuellen Dokuments holen
$id = $modx->documentIdentifier
Niemals folgendes verwenden:
$id = $modx->getDocumentIdentifier('id');
Das würde dazu führen, dass dein Snippet komische Ergebnisse liefert, wenn du Freundliche URLs benutzt.
Einfache Anführungszeichen statt doppelte verwenden
Einfache Anführungszeichen können von PHP schneller verarbeitet werden
echo "MODx"; // böse echo 'MODx'; // gut
Verkettungen verwenden anstatt Variablen in doppelte Anführungszeichen zu setzen
Wenn du einen String mit doppelten Anführungszeichen verwendest kannst du $Variablen direkt in den String schreiben und sie werden von PHP verarbeitet. Wie auch immer, dadurch wird die Lesbarkeit des Codes vermindert und Verkettungen sind außerdem schneller.
echo "Mein Name ist $name"; // schlecht echo 'Mein Name ist '.$name; // gut
Alle Variablen, Funktionen und Klassen sollten mit den Initialen deiner Resource beginnen
So verhinderst du Namenskollisionen und es ist allgemein eine gute Vorhergehensweise.
Variablen:
$sprache; // böse $rnSprache; // gut, (Der Name der Resource ist hier ResourceName)
Funktionsname (wenn nicht innerhalb einer Klasse):
function zeilenZaehlen() { ... } // böse
function rnZeilenZaehlen() { ... } // gut
Klassennamen:
class ZeilenKlasse { ... } // böse
class RnZeilenKlasse { ... } // gut
Variablen so bennenen, dass ihr Inhalt erkannt werden kann
Bennene Variablen so, dass ihr Format von ihrem Namen erkannt werden kann. So verbessert sich die Lesbarkeit des Codes. Zum Beispiel:
$land = "Japan"; // schlecht $rnStrLand = "Japan"; // gut, 'Str' macht klar, dass es ein String ist $rn_str_land = "Japan"; // auch okay $zaehler = 1; // schlecht $rnNrZaehler = 1; // gut, 'Nr' macht klar, dass es eine Zahl ist $rn_int_zaehler = 1; // auch okay $zeilen = array(); // schlecht $rnArrayZeilen = array(); // gut, 'Array' macht klar, dass es ein Array ist $nr_ar_zeilen; // gut
Bennene Funktionen so, dass ihre Aktionen und Rückgabewerte erkannt werden können
Die Funktionsnamen sollten klar machen, was sie tun und was/ob sie etwas zurückgeben und evtl. das Rückgabeformat.
function name($userid) { return $name; } // böse
function rnGetStrName($rnNrUserId) { return $rnStrName; } // gut, die Funktion gibt einen Namen als String zurück
function rnIstValiedesMitglied($rnNrUserId) { return true; } // gut, eine Funktion die einen boolschen Wert zurückgibt.
Stecke Funktionen in eine !function_exists-Bedingung, wenn deine Resource mehrmals auf der Seite ausgeführt wird
Wenn du ein Snippet zwei mal auf einer Seite aufrufst wird ein Parse-Error wie "Cannot redeclare functionName()" erscheinen. Soll dein Snippet also mehrmals pro Seite laufen musst du die Funktionen in eine !function_exists Bedingung schreiben, damit sie nicht mehrmals definiert wird.
function rnZaehleZeilen() { ... } // schlecht
if(!function_exists(rnZaehleZeilen)) { // gut
function rnZaehleZeilen() { ... }
}
Variablen deklarieren oder initialisieren bevor sie benutzt werden
So ist dein Script vor Inject-Attacken sicher
echo $rnStrLand; // böse $rnStrLand = 'Japan'; echo $rnStrLand; // gut $rnStrLand = ''; echo $rnStrLand; // gut
Variablen und Objekte, die während der Ausführung einer Resource erzeugt wurden, sollten zerstört werden
Variablen und Objekte die du in deinem Snippet erzeugst solltest du danach wieder zerstören - es ist einfach guter Stil. So hast du auf dem Server wieder ein paar freie Resourcen wie z.B. Arbeitsspeicher. Ein bisschen freier Arbeitsspeicher kann ja nie schaden.
$rnStrLand = 'Japan'; // end deiner Resource // schlecht $rnStrLand = 'Japan'; unset($rnStrLand); // gut
Unset kann man gut am Ende einer Resource verwenden. Wenn du aber mal eine große Resource in den Speicher laden musst kann es auch helfen sie direkt nach der Benutzung wieder zu zerstören und nicht bis zum Ende vom Script zu warten.
Validiere Snippet Parameter so gut wie möglich
Du solltest immer alle Werte die ein Benutzer eingeben kann validieren.
// Parameter : param=$timestamp; $rnTimeStamp = $param; // böse if (isTimestamp($param)) $rnTimeStamp = $param; // gut
Snippet Paramter sollten immer einen Standardwert haben
Die konfigurierbaren Paramter eines Snippets sollten im Standardwerte festgelegt haben. So vermeidest du Fehler wenn einige Paramter nicht initalisiert wurden und kannst das Snippet so leicht benutzbar wie möglich machen - aus der Endnutzersicht. Wenn einige Paramter keine Standardwerte haben dürfen solltest du sie im Snippet-Code überprüfen und wenn sie nicht belegt sind sollte der Benutzer eine Fehlermeldung erhalten.
$rnStrName = $param; // böse $rnStrName = isset($param) ? $param : 'Standardwert'; // gut
Snippets und Plugins sollten keinen Ebenen-Code enthalten
Snippets und Plugins sollten keinen Ebenen-Code entahlten, so sollte z.B. kein (X)HTML-Code fest in den Snippet-Code geschrieben werden. Anstatt dessen kannst du die Templat-Möglichkeiten von MODx verwenden um die Ausgabe von einem Template Chunk zu holen. Das hat eine Menge vorteile, z.B. wird deine Resource dadurch felxibler für die Endnutzer und die Lesbarkeit deines Codes wird vergrößert und die Übersetzung erleichtert.
// böse
$ausgabe = '<p>'.$rnStrName.'</p>';
return $ausgabe;
// gut
// in chunck, user has: <p>[+rnStrName+]</p>
$modx->setPlaceholder('rnStrName', $rnStrName);
return;
Benutze strftime() anstatt date() um das Datum zu formatieren
Du solltest strftime() anstatt date() verwenden um die Datumsausgabe zu formatieren. So verbesserst du die Internationalisierung deines Codes, da strftime() das Datum nach den lokalen Einstellungen des Servers formatiert ausgibt.
// schlecht $rnStrFormat = 'F j, Y, g:i a'; $rnStrHeute = date($rnStrFormat); // March 10, 2006, 1:23 pm // gut // davon ausgehend, dass der Benutzer seine Sprache eingestellt hat z.B. in confic.inc.php $locale = setlocale(LC_ALL, 'de_DE.UTF-8'); $rnStrFormat = '%B %d, %Y, %H:%S'; $rnStrHeut = strftime($rnStrFormat); // März 23, 2006, 13:23
Nur die Konfiguration im Snippet-Code, die Programmlogik per include() einbinden
Wenn dein Snippetcode ziemlich lang ist solltest du externe Dateien für die Programmlogik verwenden. Es ist eine gute Idee die einzelnen Teile eines Snippets in verschiedenen Dateien zu sortieren, z.B. Programmlogik und Funktionen in eine andere.
Es ist immer gut wenn der Benutzer so wenig Code wie Möglich in die textarea kopieren muss - um so weniger kann er kaputt machen. Heutzutage wo immer mehr Server mod_security verwenden kann es zu Problemen beim Speichern kommen, da mod_security bestimmte Wert in POST-Daten verbietet.
Außerdem solltest du include_once() anstatt include() und require_once() statt require() verwenden um zu verhindern, dass der "Cannot redeclare functionName()"-Fehler, wie oben beschrieben, auftritt. Du solltest $modx->config['base_url'] im Pfad verwenden, da es sonst zu Problemen auf Server kommen kann, die open_basedir()-Restriktionen verwenden.
// böse
$rnNrAnzahl = 10;
for ($rnIndex = 0; $rnIndex < $rnNrAnzahl; $rnIndex++) {
... etc, ganz viele Zeilen Programmlogik ...
}
// gut
$rnStrName = isset($rnStrName) ? $rnStrName : 'standardwert';
include_once($modx->config['base_url'].'assets/snippets/deinsnippet/deinprogramm.inc.php');
Benutze erklärende Header in deinem Code
Du solltest in deinem Code einen Header als PHP-Comment schreiben, der folgende Elemente enthält:
- Name der Resource
- Name des Autors
- Nickname des Autors (z.B. MODx Forenbenutzername, wenn du einen hast)
- Version
- Kompatibiltätsinfo
- Datum der Veröffentlichung
- Kurzbeschreibung
Außerdem solltest du immer die folgende Dokumentation zur Verfügung stellen:
- Lange Beschreibung
- Beispiele der Benutzung
- Liste der Parameter und Beschreibung (wenn vorhanden)
- Liste der Änderungen (Kurze Info über Fehlerbehebung, Neue Funktionen, Umschreibungen, etc.)
- Liste von Template Chunks die benutzt werden, kurze Erklärung und Standardbelegung (wenn vorhanden)
- Liste der Template Platzhalte (wenn vorhanden)
- Liste der Dateien, die benötigt werden (Z.B. Abhängikeiten zu anderen Resourcen, Installationspfade, benötigte Zugriffsrechte etc.)
- Todoliste mit geplanten Funktionen (wenn vorhanden)
Kommentiere deinen Code so gut wie möglich
Du solltest deinen Code so gut wie möglich kommentieren, damit andere ihn besser verstehen können.
Objektifiziere deinen Code
Wenn du viele zusammenhängende Funktionen verwendest steck sie in eine Klasse! Schreib nicht eine lange Liste von Funktionen ohne Zusammenhang wenn du auch soliden objektorientierten Code schreiben könntest.
Zum Beispiel sollte ein gutes Snippet die Konfigurationsparameter im Snippet-TPL haben, die eigentliche Logik in einer externen PHP-Datei und sollte über Klasseninstanzen und Methodenaufrufe aufgeführt werden.
Der Konstruktor der Klasse wird über einen Array konfiguriert, eingerichtet und render() gibt schließlich unsere Maltafel aus.
Die maltafel.inc.php Klasse könnte etwa so aussehen (PHP5 Beispiel):
Die Vorteile sind ganz einfach: Die Programmlogik ist vom Konnektor (Snippet-Code) getrennt und die Ausgabe wird in den Platzhalter geschrieben. Und schon haben wir schönen MVC (Model-View-Controller) Stil - optimal.
So bist du auch davor sicher andere PHP-Variablen aus anderen Snippets zu überschreiben, Nicht zu vergessen, dass der Code so um einiges sauberer wird.
Benutze keine kurzen PHP-Tags in externen Dateien
Du solltest keine kurzen PHP-Tags verwenden, da sie nicht alle Server akzeptieren.
<? .... ?> // böse <?php .... ?> //gut
