Statische Analyse und Codestil #

Diese Seite richtet sich an Ingenieure, die die statischen Prüfungen ausführen, prüfen oder verbessern. Der Ansatz passt zu einer alten, großen Codebasis: Die Prüfungen wurden eingeführt, ohne vorhandenen Code umzuformatieren, und sie scheitern nur an dem, was eine Änderung hinzufügt. Die Referenz ist Qualitätsprüfungen.

Inhalt #

1. Die Werkzeuge einrichten
2. PHPStan und seine Baseline
3. Der Codestil
4. Warum keine Typdeklarationen
5. Nur was eine Änderung hinzufügt
6. Die Baseline verbessern

Die Werkzeuge einrichten #

make devtools   # PHP_CodeSniffer and PHPStan into .devtools/ (composer.dev.json), never into vendor/
make hooks      # git config core.hooksPath .githooks
make check      # lint, manifest-check, phpcs and phpstan, as CI does

Die Entwicklungswerkzeuge liegen in .devtools/, aufgelöst aus composer.dev.json für PHP 8.0.30, sodass sie das vendor/ der Installation nie ändern.

PHPStan und seine Baseline #

Nur Befunde, die in der Baseline fehlen, lassen die Prüfung scheitern. make phpstan führt sie aus; der Pre-Push-Hook führt sie aus, wenn die Werkzeuge installiert sind; die CI führt sie auf PHP 8.3 aus und blockiert.

Der Codestil #

phpcs.xml.dist beschreibt den Stil von Exponential 6.0.15; jede Regel wurde vor ihrer Aufnahme am vorhandenen Code gemessen:

• array( ... ) statt [ ... ];
• ein Leerzeichen innerhalb der Klammern von Kontrollstrukturen, Aufrufen und Deklarationen: if ( $a ), foo( $a, $b );
• die öffnende geschweifte Klammer einer Funktion in eigener Zeile;
• !$a ohne Leerzeichen; Schlüsselwörter und Konstanten kleingeschrieben;
• Unix-Zeilenenden, Leerzeichen statt Tabulatoren, keine Leerzeichen am Zeilenende;
• keine aus PHP entfernten Funktionen.

PHPCompatibility prüft gegen testVersion 8.0-: keine Syntax und keine Funktionen neuer als PHP 8.0, sofern nicht durch function_exists() abgesichert oder in lib/phpcompat.php bereitgestellt (Unterstützung von PHP 8.0). Die eigenen Sniffs des Projekts liegen in bin/phpcs/Exponential/ und haben Tests (php vendor/bin/phpunit --testsuite quality).

In der CI ist der Codestil vorerst eine Warnung; der Pre-Commit-Hook lehnt einen Commit ab, der Verstöße hinzufügt.

Warum keine Typdeklarationen #

Der Sniff bin/phpcs/Exponential/Sniffs/TypeDeclarations/ meldet declare( strict_types=1 ), skalare, Pseudo- und Union-Parametertypen, Rückgabetypen, Eigenschaftstypen und Konstantentypen. Die Parameterhinweise, die schon PHP 5 hatte, bleiben erlaubt: array, callable, self und Klassennamen, auch nullbar (?array, ?eZINI). Dateien unter tests/ dürfen das : void deklarieren, das PHPUnit verlangt.

Der Grund ist Kompatibilität: Der Kernel muss auf PHP 8.0 laufen, und Typen an vorhandenen Signaturen würden jede Erweiterung brechen, die sie überschreibt oder erweitert. Ingenieure, die streng typisiertes PHP gewohnt sind, sollten Typen stattdessen in Docblocks dokumentieren, die PHPStan liest.

Nur was eine Änderung hinzufügt #

Von einer Änderung, die eine alte Datei berührt, wird nicht verlangt, die ganze Datei zu korrigieren; sie darf sie nur nicht verschlechtern.

make lint                 # php -l on the PHP files changed since origin/main
make lint80               # the same with PHP 8.0
make phpcs BASE=origin/main
make phpstan

Die Baseline verbessern #

Erhöhen Sie die PHPStan-Stufe oder verkleinern Sie die Baseline in kleinen, getrennten Änderungen, und erzeugen Sie sie mit make phpstan-baseline neu. Erzeugen Sie die Baseline nie neu, um einen neuen Befund durchzulassen: Das versteckt den Befund, als wäre er immer da gewesen. Dasselbe gilt für den Codestil: Korrigieren Sie den Code, statt einen Sniff abzuschwächen.

Verwandte Seiten #

• Codierstandards
• Standards für PHP, PHP-FIG und Composer
• Mit technischen Schulden umgehen
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.