Editor-übergreifende Format-Vorgaben mit EditorConfig

Beschreibung: Vorstellung des EditorConfig Standards, mit dessen Hilfe die offiziellen Format-Vorgaben seitens phpBB für bestimmte Dateitypen festgelegt werden können. Als Beispiel wird die Einrichtung in Notepad++ gezeigt.

Kategorie: Extensions, Styles und Templates

Link zu diesem Artikel: Alles auswählen

[url=https://www.phpbb.de/kb/viewarticle?a=93&sid=11afe7a71ee4997a26e23d57d14e1587]Knowledge Base - Editor-übergreifende Format-Vorgaben mit EditorConfig[/url]

Einleitung

Das Programmieren einer phpBB Erweiterung oder Gestalten eines phpBB Styles ist schon komplex genug. Darum ist auch jedes Werkzeug willkommen, das einem die Arbeit etwas erleichtert. Eine Hürde, die gemeistert werden will, sind die Format-Vorgaben seitens phpBB für die verschiedenen Dateitypen:
  • Das Zeilenende muss LF sein.
  • Am Ende einer Datei muss ein abschließendes LF vorhanden sein.
  • Am Ende einer Zeile darf kein Whitespace (Leerzeichen und Tabs) vorkommen.
  • Die Tabulatorgrösse im phpBB Umfeld beträgt 4.
  • Einrückungen bei .php müssen mit Tabs erzeugt werden.
  • Einrückungen bei .js müssen mit Tabs erzeugt werden.
  • Einrückungen bei .html müssen mit Tabs erzeugt werden.
  • Einrückungen bei .css müssen mit Tabs erzeugt werden.
  • Einrückungen bei .json müssen mit Tabs erzeugt werden.
  • Einrückungen bei .yml müssen mit Leerzeichen erzeugt werden.
  • Die Datei muss in UTF-8 ohne BOM gespeichert werden.
Analysetools wie EPV und CodeSniffer prüfen dann auf Einhaltung dieser Vorgaben.

Es wäre doch schön, wenn sich der Editor gleich selbst an diese Vorgaben halten würde, sodass Fehler gar nicht erst entstehen. Und genau hier setzt der Editor-übergreifende Standard EditorConfig an. Das ist ein unabhängiger und freier Standard, der zum einen aus einer simplen kleinen Textdatei besteht, in der Projekt-bezogene Format-Vorgaben festgelegt werden können. Zum anderen muss dieser Standard natürlich auch vom jeweiligen Editor oder IDE unterstützt werden und das ist inzwischen bei vielen schon der Fall. Sogar GitHub (auch GitHub Desktop) und Visual Studio unterstützen diesen Standard.

1. EditorConfig in Notepad++ nachrüsten:

In diesem HowTo gehe ich nur auf NP++ ein. Grundsätzlich funktioniert EditorConfig aber auch mit anderen Editoren. Dazu am besten die Liste der direkt unterstützten Programme bei EditorConfig sichten. Für diejenigen Programme, die EditorConfig "noch" nicht direkt unterstützen, gibt es meist schon Plugins, die diesen Standard nachrüsten, so z.B. auch für NP++:
  1. Menü "Erweiterungen > Plugin-Verwaltung" > Suchen: editorconfig
  2. Dann in der Liste bei "EditorConfig" den Haken setzen und "Installieren" klicken. Erfordert Neustart von NP++
Das war's auch schon, mehr hat man in NP++ nicht damit zu tun. Das Plugin selber muss also nicht konfiguriert werden, es muss einfach nur installiert sein.

2. Die Datei .editorconfig:

Der Inhalt der folgenden Datei muss mit dem Dateinamen .editorconfig (den Punkt am Anfang beachten) im Hauptordner des Projekts abgespeichert werden. Wenn man zum Beispiel WampServer nutzt, wäre der Ordner www ideal. Alle Editoren und IDEs, die diesen Standard unterstützen, verwenden dann die Vorgaben, die in dieser Textdatei definiert wurden, sobald eine von EditorConfig geregelte Datei wie .php innerhalb von www bearbeitet wird. Damit die Übersicht dieser Datei gewahrt bleibt, ist diese auf Minimum gehalten und enthält keine erklärenden Kommentare. Erklärungen zu den einzelnen Zeilen gibt es weiter unten im Artikel.

CODE: Alles auswählen

# EditorConfig is awesome: https://EditorConfig.org

# phpBB - Editor Vorgaben v1 - https://www.phpbb.de/kb/viewarticle?a=93
# 2020 LukeWCS, phpBB.de

root = true

[*]
end_of_line = lf
insert_final_newline = true

[*.{php,js,css,json,html,txt,md,yml}]
charset = utf-8
indent_style = tab
indent_size = 4
trim_trailing_whitespace = true

[*.{html,txt,md,yml}]
trim_trailing_whitespace = false

[*.yml]
indent_style = space
3. Infos und Erklärungen:

Wenn man Punkt 1 und 2 erledigt hat, ist das Ganze auch schon betriebsbereit. Es folgen jetzt noch ein paar generelle Infos und auch Erklärungen.

Infos zu .editorconfig:
  • Grundsätzlich ist diese Datei hier für eine phpBB Umgebung gebrauchsfertig. Sollte ich mich bei etwas vertan haben, oder sich im Laufe der Zeit Besonderheiten ergeben, werde ich die Datei aktualisieren.
  • Die Datei .editorconfig sollte in UTF-8 gespeichert werden und darf am Zeilenende entweder LF oder CRLF enthalten, beides ist erlaubt. Man sollte sich aber im phpBB Umfeld angewöhnen, grundsätzlich LF zu verwenden.
  • Wenn die Datei .editorconfig mit NP++ geändert wird, dann greifen die Änderungen sofort. Es ist also nicht nötig NP++ nach Änderungen an der Vorgaben-Datei neu zu starten.
  • EditorConfig hat die höchste Priorität. Sobald also eine .editorconfig existiert, gelten die Vorgaben, die darin definiert wurden, egal was im Editor eingestellt wurde.
  • Die Datei .editorconfig wird vom Editor immer zuerst in dem Ordner gesucht, wo sich die aktuell im Editor geöffnete Datei befindet. Wenn .editorconfig nicht in diesem Ordner vorhanden ist, wird im übergeordneten Ordner danach gesucht. Und so weiter. Sobald entweder das Wurzelverzeichnis erreicht wurde, oder aber eine .editorconfig mit der Definition root = true gefunden wurde, wird die Suche gestoppt.
  • Man kann so quasi eine primäre und mehrere sekundäre .editorconfig anlegen. Das kann in Sonderfällen hilfreich sein. Grundsätzlich gilt aber: je weniger, desto besser. Ich persönlich verwende nur eine einzige in meiner Entwicklungsumgebung für phpBB.
  • Regeln werden in dieser Datei immer von oben nach unten bearbeitet. Man könnte also "oben" generelle Regeln definieren, und "darunter" Ausnahmen. Davon habe ich bei meiner .editorconfig auch Gebrauch gemacht. Man könnte aber genauso gut für alle Dateitypen die man geregelt haben will, auch jeweils alle Eigenschaften definieren. Beides ist möglich.
Allgemeine Infos:
  • Wenn man im FTP Programm die Übertragungsart auf "Binär" stellt, hat man in Kombination mit EditorConfig stets sichergestellt, dass die Dateien sowohl das richtige Format haben, als auch richtig übertragen werden.
  • Die Vorgaben gelten nicht nur für neue Dateien, sondern können auch auf alte Dateien angewendet werden. Dazu einfach die entsprechende Datei öffnen, dann eine "Änderung" erzeugen, zum Beispiel einfach in einer Leerzeile ein Leerzeichen einfügen und das gleich wieder löschen. Wenn man jetzt die Datei speichert, werden sofort alle Vorgaben angewendet und das schneller und präziser als man das selbst je könnte. Das eignet sich auch wunderbar, um Dateien von einigen Fehlern zu bereinigen, die z.B. von CodeSniffer gemeldet wurden.
  • In NP++ können die EditorConfig Vorgaben der aktuell geöffneten Datei - z.B. einer .php Datei - überprüft werden: Menü "Erweiterungen > EditorConfig > Show EditorConfig settings for this file". So kann man z.B. nach Änderungen an der Vorgaben-Datei sofort feststellen, ob die Vorgaben auch greifen.
Erklärungen der einzelnen Zeilen: (in der Reihenfolge des ersten Vorkommens)

# ...
Kommentare die von EditorConfig ignoriert werden.

root = true
true = Oberste EditorConfig Datei, in höheren Ordnerebenen wird also nicht mehr nach .editorconfig gesucht.
false = Es wird auch in höheren Ordnerebenen nach .editorconfig gesucht.

[*]
Die Regeln darunter gelten für alle Dateien.

end_of_line = lf
Das Zeichen für Zeilenende ist LF.

insert_final_newline = true
true = Am Dateiende wird das Zeichen für Zeilenende eingefügt, falls nicht vorhanden. Was genau eingefügt wird, hängt davon ab, was bei end_of_line definiert wurde.
false = Keine Aktion.

[*.{php,js,css,json,html,txt,md,yml}]
Die Regeln darunter gelten nur für bestimmte Dateitypen.

charset = utf-8
Datei wird in UTF-8 ohne BOM gespeichert.

indent_style = tab
tab = Einrückungen erfolgen mit Tab-Stopps.
space = Einrückungen erfolgen mit Leerzeichen.

indent_size = 4
Eine Einrückung hat die Breite von 4 Leerzeichen. Eine Einrückung kann entweder aus Tab-Stopps oder Leerzeichen bestehen, je nachdem was bei indent_style definiert wurde.

trim_trailing_whitespace = true
true = Leerzeichen und Tab-Stopps am Zeilenende werden entfernt, falls vorhanden.
false = Keine Aktion.

[*.{html,txt,md,yml}]
Die Regeln darunter gelten nur für bestimmte Dateitypen.

[*.yml]
Die Regeln darunter gelten nur für diesen einen Dateityp.

Weiterführende Informationen:

HowTo: EditorConfig - Editor-übergreifende Formatvorgaben (Diskussion)
phpBB Coding Guidelines
phpBB Development Documentation