Dokumentation · Entwickler-Dokumentation

Coding-Standards

Diese Seite beschreibt die Konventionen, denen ein Beitrag zum Plugin folgen sollte, auf einer Ebene, die sicher veröffentlicht werden kann. Interne Klassennamen, interne Konstanten, Berechtigungs-IDs und Konventionen für Option-Keys sind Implementierungsdetails und werden hier nicht veröffentlicht.

Wann dieses Dokument zu verwenden ist

Verwenden Sie dieses Dokument, wenn Sie:

  • PHP, JavaScript, CSS, Templates oder übersetzbare Strings zu einem Beitrag hinzufügen möchten.
  • Einen Pull Request überprüfen und eine Referenz dafür benötigen, was "konsistent mit der Codebasis" bedeutet.
  • Das Plugin über ein separates Plugin oder ein Theme erweitern und möchten, dass sich Ihr eigener Code nativ anfühlt.

PHP

  • Sprachniveau. Zielen Sie auf die PHP-Version ab, die im Plugin-Header als Minimum deklariert ist. Vermeiden Sie Funktionen, die dort nicht verfügbar sind.
  • Typdeklarationen. Verwenden Sie skalare und Rückgabetyp-Deklarationen bei neuen Methoden, im Einklang mit dem umgebenden Code.
  • WordPress-Stil. Befolgen Sie die WordPress PHP-Coding-Standards (Tabs für Einrückungen, Leerzeichen in Klammern, Yoda-Bedingungen, wo die Codebasis diese bereits verwendet, snakecase für Funktionen und Methoden, TitleCaseWithUnderscores für Klassennamen).
  • Eine Klasse pro Datei. Jede PHP-Datei enthält eine Klasse. Dateinamen entsprechen den Klassennamen in kleingeschriebener und mit Bindestrichen versehener Form, konsistent mit den bereits in der Codebasis vorhandenen Konventionen.
  • Keine neuen globalen Variablen. Bevorzugen Sie Klassenkonstanten und Dependency Injection gegenüber verstreuten globalen Variablen.

WordPress-Integration

  • Berechtigungsprüfungen zuerst. Jede privilegierte Aktion muss die entsprechende Berechtigung überprüfen, bevor Arbeiten ausgeführt werden.
  • Nonce-Prüfungen für Formulare und Admin-AJAX. Verwenden Sie die standardmässigen WordPress Nonce-APIs (check_admin_referer, check_ajax_referer, wp_verify_nonce) für jeden zustandsändernden Endpunkt.
  • Bereinigung und Maskierung. Bereinigen Sie bei der Eingabe (Sanitisation) und maskieren Sie bei der Ausgabe (Escaping) unter Verwendung der entsprechenden WordPress-APIs für den Typ und den Ausgabekontext. Siehe Sanitisation und Escaping.
  • i18n. Versehen Sie benutzerseitige Strings mit der Textdomain des Plugins. Siehe Internationalisierung für Entwickler.
  • Protokollierung. Verwenden Sie den gemeinsamen Logger des Plugins, anstatt PHP's error_log direkt aus neuem Feature-Code aufzurufen.

JavaScript und CSS

  • Das Plugin verwendet keine JavaScript-Build-Pipeline; Assets werden als einfache Dateien ausgeliefert.
  • Halten Sie Frontend-JavaScript frei von Abhängigkeiten und progressiv; das Plugin muss weiterhin in Browsern funktionieren, die Skripte von Drittanbietern blockieren.
  • Versehen Sie neue CSS-Klassen konsistent mit Präfixen gemäss den bestehenden Frontend- und Admin-Konventionen, um Kollisionen mit Themes zu vermeiden.

Tests

  • Neue Verhaltensänderungen sollten durch Tests abgedeckt werden, sofern sie vernünftigerweise durch Unit-Tests überprüft werden können.
  • Benennen Sie neue Testklassen nach der getesteten Klasse oder dem getesteten Verhalten mit dem Suffix Test, im Einklang mit bestehenden Tests.
  • Siehe Test-Leitfaden für den übergeordneten Test-Workflow.

Dokumentation

  • Aktualisieren Sie die relevanten Seiten unter docs/en/, wann immer ein Beitrag das öffentlich wahrnehmbare Verhalten ändert.
  • Halten Sie die Dokumentation öffentlichkeitssicher; fügen Sie der öffentlichen Dokumentation keine internen Klassennamen, Option-Keys, REST/AJAX-Routennamen oder Berechtigungs-/Nonce-IDs hinzu.

Hinweis zur öffentlichen Dokumentation. Diese Seite bietet nur eine übergeordnete Integrationsübersicht. Interne Implementierungsdetails, private APIs, Speicherinterna und sicherheitsrelevante Release-Infrastrukturen werden separat gepflegt und sind nicht Teil der öffentlichen Dokumentation.