Development Best Practices/de

Auf dieser Seite ist eine Auswahl von Programmierverfahren zusammengestellt, die bei dem Entwickeln einer Komponente, eines Plugins oder eines Moduls für Joomla! beachtet werden sollten.

Allgemeiner Leitfaden zur Entwicklung

• Die Konstante DS oder DIRECTORY_SEPARATOR darf beim Einbinden von Dateien nicht verwendet werden. Sie wird nicht mehr benötigt, wie von Christian auf php.net beschrieben.
• Die Funktion register_globals sollte nicht verwendet werden. Dies stellt ein Hohes Sicherheitsrisiko dar. Die Funktion wurde in PHP 5.3 als veraltet eingestuft und in 5.4 entfernt.
• Keinen direkten Zugriff auf die Superglobalen $_GET, $_POST, $_REQUEST, $_FILES und $_SERVER ermöglichen. Alternativ kann stattdessen JInput (typischerweise: JFactory::getApplication()->input) benutzt werden. JInput filtert die Eingabe und hilft dabei, leichter sichere Software zu entwerfen.
• Die SQL-Abfragen sollten nicht hardcodiert und Rohdaten müssen escapet in die Abfragen eingebunden werden. Immer mit JDatabase / JDatabaseQuery arbeiten. Es ist so einfach wie JFactory::getDbo()->getQuery(true).
• Keine willkürlichen Einstiegspunkte benutzen, beispielsweise .php-Dateien, die von außerhalb der Joomla!-Installation und direkt aus dem Internet erreichbar sein müssen, . Diese Praxis, die typischerweise für Zahlungsabwickler und Bildoptimierer verwendet wird, ist extrem unsicher und wird ausdrücklich abgelehnt. Statt dessen sollte eine Joomla!-Komponente oder ein System-Plugin eingesetzt werden.
• Nicht das Rad neu erfinden! Wenn es für eine Aufgabe bereits eine Joomla!-Klasse gibt, sollte man sie benutzen, bevor man seine eigene entwickelt. Die Chancen stehen gut, dass die Kernklasse bereits gut genug und viel besser getestet ist.
• Für die Tabellennamen sollten sinnvolle Präfixe gewählt werden. Wenn die Komponente com_foobar heißt, liegt es nahe, dass die Tabellen dem gleichen Namensschema folgen:

 // Gut
 #__foobar_something

 // Schlecht
 #__fbr_something 

 // Richtig schlecht!
 #__something

• Die Erweiterungen sollten schon mit Vorabversionen von Joomla! und/oder der „Staging“ Branch des Git-Repositorys getestet werden. Der Entwickler muss sicherstellen, dass die Benutzer der Erweiterung Joomla! sicher aktualisieren können.
• Für die Erweiterungen sollte eine Dokumentation erstellt werden. Selbst ein kurzes Video in nicht ganz so gutem Englisch ist besser als nichts.
• JText sollte verwendet werden, um die Texte der Erweiterungen zu übersetzen, anstatt sie hart zu kodieren. Die überwiegende Mehrheit der Joomla! Benutzer sind keine englischen Muttersprachler und sie werden für Ihre Umsicht dankbar sein.
• Kommentare im Code unbedingt einfügen. Nicht nur für die Leute, die damit arbeiten müssen, sondern auch für Sie selbst nach sechs Monaten.
• Den Code unbedingt unter realen Einsatzbedingungen, mit echten Datensätzen testen. Möglicherweise werden so manche Überraschungen zutage treten.

Wo sollten JavaScript-, CSS- und Bilddateien abgelegt werden, die zur Komponente gehören?

Im Root-Verzeichnis befindet sich das allgemeine Medien-Verzeichnis media, das alle Assets enthält.

In der Praxis bedeutet dies, dass Dateien, die im XML-Installationsmanifest in einem <media>-Tag, statt in einem <files>-Tag stehen, an den Ordner JPATH_ROOT/media gesendet werden. Wenn <media destination="com_foo"> angegeben wird, dann landen die Dateien in JPATH_ROOT/media/com_foo.

Es kann vorkommen, dass es eine Komponente gibt, sagen wir com_foo und dann noch ein paar zugehörige Module... für dieses Beispiel nennen wir sie mod_foo_1, mod_foo_2 und mod_foo_3. Es gibt keinen Grund, die Medienelemente für die drei Module zu paketieren, wenn sie sowieso alle gleich sind und sie von der Komponente abhängen. Der beste und logische Weg ist, sie alle an einem zentralen Ort zu platzieren, der mit einem entsprechenden Namensraum gekennzeichnet ist.

Durch das Ablegen der Medien im Medien-Verzeichnis können Templates diese mit Template-Overrides überschreiben. Die mit der Erweiterung gelieferten Dateien müssen nicht geändert werden, wodurch diese Anpassungen bei Updates verloren gehen würden. Das Laden der Medien mit den Methoden image, script und stylesheet in der JHtml-Klasse anstelle des direkten Ladens der Medien mit JDocument oder hart kodierten Tags ermöglicht einfache Overrides der Erweiterungsmedien. So kann die Darstellung an die jeweilige Website angepasst werden.

Weitere Informationen über die Verwendung des Medienordners für Erweiterungsmedien ist in diesem Blogbeitrag zu finden.

Wo sollten die von der Komponente generierten Dateien abgelegt werden?

Das hängt von der Art dieser Dateien ab. Es gibt zwei ausschlaggebende Faktoren:

• Die Bestandsdauer der Datei: temporär, cache oder permanent. Temporäre Dateien sind Dateien, die sofort nach der Nutzung gelöscht werden sollten, noch bevor das Laden der Seite abgeschlossen ist. Cache-Dateien werden eine Zeit lang auf dem Server gespeichert, höchstens bis zu ihrem Verfallsdatum. Sowohl temporäre als auch Cache-Dateien können ohne Vorwarnung gelöscht werden und der Code muss dies berücksichtigen. Permanente Dateien hingegen sind nicht zum automatischen Löschen vorgesehen.
• Die Verfügbarkeit der Datei: Web-zugänglich oder Web-unzugänglich. Die webzugänglichen Dateien sind diejenigen, auf die über das Web zugegriffen werden muss, z. B. wenn eine URL in einen Webbrowser eingeben wird. Die nicht webzugänglichen Dateien sind diejenigen, auf die nicht über das Web zugegriffen werden muss.

Daraus ergeben sich die folgenden Optionen:

• Temporär, vom Web aus unzugänglich. Dazu kann man das Joomla! temp-Verzeichnis benützen. Es wird mit JFactory::getConfig()->get('tmp_path') ermittelt. Das Hardcoding des Pfades als JPATH_ROOT . '/tmp' ist eine schlechte Strategie und sollte nicht gemacht werden.
• Temporär, über das Web zugänglich. Das ist nicht akzeptabel! Temporäre Dateien sind per Definition vom Web aus nicht erreichbar. Möglicherweise wird das mit Cache. statt „temporär“ verwechselt?
• Cache, vom Web aus unzugänglich. Dazu das definierte Joomla! Cache-Verzeichnis verwenden. Mit der Konstante JPATH_CACHE findet man dessen Speicherort. Hinweis: Das Cache-Verzeichnis kann im Front-End und Back-End der Website unterschiedlich sein.
• Cache, über das Web zugänglich. Dazu ein Unterverzeichnis des Media-Ordners bestimmen. Siehe den Abschnitt über Javascript- und CSS-Dateien, das ist ein und dasselbe.
• Permanent, nicht über das Web zugänglich. Die Dateien sollten in einem Ordner unterhalb des Hauptverzeichnisses der Erweiterung abgelegt werden. Wenn wirklich gewollt ist, dass die Dateien für das Web nicht erreichbar sein sollen, sollte eine .htaccess-Datei eingefügt werden. Noch besser ist es den Benutzern die Möglichkeit zu geben, ein Verzeichnis außerhalb des Stammverzeichnisses der Website zu verwenden.
• Permanent, vom Web aus aufrufbar. Ein Unterverzeichnis des Medien-Verzeichnisses verwenden. Siehe den Abschnitt über Javascript- und CSS-Dateien, das ist ein und dasselbe.

Dies gilt für alle Dateien, die von der Komponente verwaltet werden, einschließlich der Dateien, die vom Code generiert werden und der Dateien, welche die Benutzer der Komponente hochladen bzw. generieren.

Abschließend: Wenn Protokolldateien verwaltet werden sollen, empfiehlt es sich, die Klasse JLog zu verwenden, anstatt eine eigene Lösung zu entwickeln.

Überlegungen zu Javascript

Wenn die addScriptDeclaration verwendet wird, um Javascript in eine Joomla!-Seite einzufügen, muss man sehr aufmerksam sein, was die Interaktion des Codes mit dem Javascript anderer Erweiterungen betrifft, die auf der gleichen Seite laufen. Gute Verfahren umfassen:

• Javascript unbedingt mit einem Semikolon und einem Zeilenumbruch abschließen. Fehlt beides, ist der Code die Quelle für Javascript-Fehler, sobald ein anderer Entwickler-Code addScriptDeclaration hinter dem eigenen Code verwendet.
• Der Javascript-Code muss auf Gültigkeit geprüft werden und darf keine Fehler verursachen. Fehler im Code machen jeden nachfolgenden Code unbrauchbar.
• Für riskanten Code sollten try/catch-Blöcke verwendet werden. Wenn man sich nicht sicher ist, ob ein Code riskant sein könnte, sollte man ihn trotzdem mit einem try/catch-Block umgeben.
• Der Inline-Javascript-Code sollte im Template der Ansicht geladen werden, nicht in der Klasse der Ansicht (Datei view.html.php). Höchstwahrscheinlich hängt es vom DOM ab, welches anders ausfällt, wenn ein Site-Integrator ein Template-Override verwendet.

Andere gute Techniken, die den Javascript-Code in Erweiterungen betreffen, sind:

• Nie irgendwelche Javascript-Kernobjekte verändern, einschließlich jQuery, mooTools und alles im Joomla-Javascript-Objekt. Wenn ein Kernobjekt modifiziert werden soll: Unterklassen verwenden. Falls man unsicher ist: Unterklassen verwenden.
• Kein Einmischen in den Code anderer Entwickler. Dies schließt das Verschieben von Skript-Tags an den unteren Rand der Seite oder das erzwungene Entfernen von Skript-Tags ein (z. B. das Entfernen jedes Skript-Tags, dessen Quell-URL das starke "jq" enthält - man weiß ja, wem die Stunde schlägt).