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=530d542fa0d3fc0ea6f9a8c35b1516df]Knowledge Base - Editor-übergreifende Format-Vorgaben mit EditorConfig[/url]

Übersicht
  1. Einleitung
  2. EditorConfig in Notepad++ nachrüsten
  3. Die Datei .editorconfig
  4. Weitere Informationen zu .editorconfig
  5. Erklärungen der einzelnen Zeilen (in der Reihenfolge des ersten Vorkommens)
  6. Passend zum Thema
1. 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 Tabulatorbreite im phpBB Umfeld beträgt 4 Leerzeichen.
  • 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 Leerzeichen 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 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 bei vielen schon der Fall. Sogar GitHub (auch GitHub Desktop) und Visual Studio unterstützen diesen Standard.

2. EditorConfig in Notepad++ nachrüsten

In diesem HowTo wird nur auf Notepad++ eingegangen. 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 Notepad++:
  1. Menü "Erweiterungen > Plugin-Verwaltung" > Suchen: editorconfig
  2. Dann in der Liste bei "EditorConfig" den Haken setzen und "Installieren" klicken. Erfordert Neustart von Notepad++
Mehr hat man in Notepad++ nicht mit dem Plugin zu tun. Das Plugin selber muss also nicht konfiguriert werden, es muss einfach nur installiert sein.

3. 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 und bei XAMPP bietet sich htdocs an. 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 bzw. htdocs 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 Programmierrichtlinien - Editor Vorgaben v1.2
# Quelle: https://www.phpbb.de/kb/viewarticle?a=93
# Autor : LukeWCS (phpBB.de), 2023-07-27

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

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

[*.{json,yml}]
indent_style = space
Archiv - Ältere Versionen von .editorconfig

Code: Alles auswählen

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

# phpBB Programmierrichtlinien - Editor Vorgaben v1.1
# Quelle: https://www.phpbb.de/kb/viewarticle?a=93
# Autor : LukeWCS (phpBB.de), 2023-01-31

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

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

[*.yml]
indent_style = space

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
Hinweise
  • Die Vorgaben gelten nicht nur für neue Dateien, sondern können auch auf alte Dateien angewendet werden. Dazu einfach die entsprechende Datei öffnen und eine "Änderung" erzeugen, indem in einer Leerzeile einfach ein Leerzeichen eingefügt wird. Wenn man jetzt die Datei speichert, werden sofort alle Vorgaben angewendet und das schneller und präziser als man das selbst je könnte. Und unser überflüssiges Leerzeichen wird dabei auch gleich entfernt. Das eignet sich auch wunderbar um Dateien von bestimmten Fehlern zu bereinigen, die z.B. von CodeSniffer gemeldet wurden.
  • In Notepad++ 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.
  • 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.
Wenn man Punkt 2 und 3 erledigt hat, ist das Ganze auch schon betriebsbereit und die Integration von EditorConfig in Notepad++ damit abgeschlossen. Es folgen noch zusätzliche Informationen und Erklärungen die nützlich sein können, wenn man Änderungen an .editorconfig vornehmen will.

4. Weitere Informationen zu .editorconfig
  • Grundsätzlich ist diese Datei hier für eine phpBB Umgebung gebrauchsfertig. Die Datei wird bei Bedarf angepasst und Änderungen werden in der zugehörigen Diskussion bekanntgegeben.
  • 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 Notepad++ geändert wird, dann greifen die Änderungen sofort. Es ist also nicht nötig Notepad++ 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.
  • Regeln werden in dieser Datei immer von oben nach unten bearbeitet. Man könnte also "oben" generelle Regeln definieren und "darunter" Ausnahmen. Davon wurde bei der hier gezeigten .editorconfig Datei 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.
5. 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 diese 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.

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

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

6. Passend zum Thema

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