Der Coding-Standard (phpcs.xml.dist) #

Diese Seite richtet sich an PHP-Entwickler, die Code für den Kernel oder für Erweiterungen schreiben, die dem Stil des Kernels folgen. Der Stil ist in phpcs.xml.dist beschrieben und wird von PHP_CodeSniffer geprüft. Jede Regel wurde vor ihrer Aufnahme am vorhandenen Kernel- und Bibliothekscode gemessen, sodass der Standard beschreibt, wie der Code bereits aussieht; es ist nicht PSR-12 (Coding-Standards).

Inhalt #

1. Ein Beispiel im Hausstil
2. Die Regeln
3. Verbotene Funktionen
4. Typdeklarationen und PHP 8.0
5. Nur neue Verstöße schlagen fehl
6. Die Prüfung ausführen
7. Über das hinaus, was das Werkzeug prüft

Ein Beispiel im Hausstil #

<?php
/**
 * File containing the acmeReportService class.
 *
 * @package acmereport
 */

class acmeReportService
{
    /**
     * The totals of the items, by status.
     *
     * @param array $items list of acmeReportItem
     * @return array status => total
     */
    public static function totals( array $items )
    {
        $totals = array();
        foreach ( $items as $item )
        {
            $status = (string)$item->attribute( 'status' );
            if ( !isset( $totals[$status] ) )
            {
                $totals[$status] = 0;
            }
            $totals[$status] += (int)$item->attribute( 'amount' );
        }
        return $totals;
    }
}

Die Regeln #

Die Aufteilung eines Aufrufs über mehrere Zeilen ist frei; nur die Leerzeichen innerhalb der Klammern werden geprüft.

Verbotene Funktionen #

Generic.PHP.ForbiddenFunctions lehnt Funktionen ab, die PHP entfernt hat oder die Exponential ersetzt:

Auch die Übergabe per Referenz zur Aufrufzeit (foo( &$a )) wird abgelehnt.

Typdeklarationen und PHP 8.0 #

Zwei weitere Teile gehören zum Standard:

• Keine Typdeklarationen ab PHP 7, geprüft vom projekteigenen Sniff bin/phpcs/Exponential/Sniffs/TypeDeclarations/NoTypeDeclarationsSniff.php: kein declare( strict_types=1 ), keine skalaren, Pseudo-, Vereinigungs- oder Schnittmengen-Parametertypen, keine Rückgabe-, Eigenschafts- oder Konstantentypen. Erlaubt sind die Hints, die es schon in PHP 5 gab: array, callable, self und Klassennamen, auch nullbar (?array, ?eZINI). Dateien unter tests/ dürfen das von PHPUnit verlangte : void deklarieren. Die Gründe stehen unter Warum der Code keine Typdeklarationen hat.
• PHPCompatibility mit testVersion 8.0-: keine Syntax und keine Funktionen, die neuer als PHP 8.0 sind, und keine, die spätere Versionen entfernt haben oder als veraltet markieren (Code schreiben, der unter PHP 8.0 läuft).

Nur neue Verstöße schlagen fehl #

Alte Dateien folgen nicht jeder Regel, und das Projekt formatiert alten Code nie aus Stilgründen um. bin/php/checkcodestyle.php vergleicht deshalb die Anzahl der Verstöße jeder geänderten Datei mit ihrer vorherigen Version und schlägt nur fehl, wenn Ihre Änderung Verstöße hinzufügt. Den alten Stil der Zeilen, die Sie nicht berührt haben, dürfen Sie stehen lassen; Sie dürfen ihn nicht vermehren.

Die Prüfung ausführen #

make devtools                                        # once: PHP_CodeSniffer and PHPCompatibility into .devtools/
make phpcs                                           # changed files since origin/main; only new violations fail
make phpcs BASE=origin/release-branch                # against another base
php bin/php/checkcodestyle.php --staged              # staged files against HEAD (what the pre-commit hook runs)
.devtools/vendor/bin/phpcs --standard=phpcs.xml.dist extension/acmereport/   # a whole directory, all findings

In der CI ist der Schritt für den Code-Stil vorerst eine Warnung, kein Fehlschlag; der pre-commit-Hook lehnt einen Commit ab, der Verstöße hinzufügt, sofern Sie nicht --no-verify verwenden. Der Sniff hat eigene Tests: vendor/bin/phpunit --testsuite quality (Git-Hooks und make-Ziele).

Über das hinaus, was das Werkzeug prüft #

Dies sind die Konventionen der Codebasis, die kein Sniff prüft; das tun die Reviewer:

• Eine Klasse pro Datei, Dateiname in Kleinbuchstaben (acmereportservice.php für acmeReportService).
• Ein Docblock an jeder Klasse und jeder öffentlichen Methode mit Typen bei @param und @return, da der Code keine Typdeklarationen hat (das Beispiel oben zeigt die Form).
• Neue Bezeichner tragen Ihr Präfix; neuer Projektcode verwendet exp; Kernel-Namen eZ* werden nie umbenannt (Klassenbenennung und das Präfix exp).
• eZDebug::writeError() und verwandte Methoden mit __METHOD__ als Label.
• Amerikanisches Englisch in Kommentaren und Meldungen.

Verwandte Seiten #

• Coding-Standards
• Qualitätsprüfungen
• Statische Analyse mit PHPStan
• Freie Dokumentation: diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.