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. Richten Sie sich nach der im Plugin-Header deklarierten PHP-Version als Minimum. 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 sie bereits verwendet, snakecase für Funktionen und Methoden, TitleCaseWithUnderscores für Klassennamen).
  • Eine einzelne Klasse pro Datei. Jede PHP-Datei enthält eine Klasse. Dateinamen entsprechen den Klassennamen in kleingeschriebener Form mit Bindestrichen, 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 Standard-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 Sanitization And Escaping.
  • i18n. Versehen Sie für den Benutzer sichtbare Strings mit der Textdomain des Plugins. Siehe Internationalization For Developers.
  • 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äß 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 Testing Guide für den übergeordneten Test-Workflow.

Dokumentation

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

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