Jedes PHP-Projekt, in das ich gekommen bin und in dem die Arbeit wehtat, tat aus demselben Grund weh: Niemand hat diese Entscheidungen am Anfang getroffen, also hat sie jeder für sich getroffen, für immer.
Nichts davon ist fortgeschritten. Alles davon kostet einen Nachmittag. Und jedes Einzelne funktioniert nur, wenn es automatisch läuft, denn eine Regel, die davon abhängt, dass Leute sich an sie erinnern, ist keine Regel, sondern ein Wunsch.
1. Einigt euch auf einen Code-Style — und macht PSR-12 daraus
Nicht weil PSR-12 objektiv die schönste Art wäre, PHP zu schreiben. Weil ihn alle schon kennen, jedes Werkzeug ihn unterstützt und niemand darüber streiten muss.
Der Wert eines Code-Styles hat fast nichts damit zu tun, welchen ihr wählt. Er kommt daher, dass aller Code gleich aussieht, sodass ein Diff zeigt, was sich geändert hat, statt wer es geschrieben hat. Zwei Entwickler mit unterschiedlichen Klammervorlieben machen aus einem Dreizeilen-Bugfix ein Vierzig-Zeilen-Diff, und dann findet das Review nichts, weil es nichts zu sehen gibt.
Nimm PSR-12, schreib es ins Repository, und wende dich etwas zu, das zählt.
2. Ergänzt einen Code-Style-Checker
Der aufgeschriebene Style ist nichts wert, bis etwas ihn durchsetzt. Nimm PHP-CS-Fixer oder PHP_CodeSniffer als Dev-Abhängigkeit dazu und committe die Konfiguration ins Repository:
composer require --dev friendsofphp/php-cs-fixer
vendor/bin/php-cs-fixer fix --dry-run --diff
--dry-run meldet, ohne etwas anzufassen, und genau das willst du in CI. Wenn die Prüfung scheitert, scheitert die Pipeline. Keine Diskussion, kein "das räumen wir später auf", kein Reviewer, der die Person sein muss, die Einrückung anspricht.
3. Ergänzt den Fixer, nicht nur den Checker
Das ist der Schritt, den die Leute auslassen, und ihn auszulassen ist der Grund, warum der Checker drei Monate später abgeschaltet wird.
Wenn dein Werkzeug Entwicklern nur sagen kann, dass sie falsch liegen, wird jeder Verstoß zu Handarbeit und die ganze Sache zu einem Hindernis. Wenn dasselbe Werkzeug es beheben kann, wird der Verstoß zu einem Nicht-Ereignis:
vendor/bin/php-cs-fixer fix
Checker in CI, Fixer auf der Maschine der Entwicklerin. Dieselbe Konfigurationsdatei, damit sie sich nie widersprechen können.
Jede Regel, die du durchsetzt, ohne die Behebung mitzuliefern, ist eine Regel, um die dein Team irgendwann herumarbeitet.
4. Verdrahtet es mit git-Hooks
Jetzt verbinde die beiden, damit sich niemand an eines von beiden erinnern muss. Ein Pre-Commit-Hook, der den Fixer über die gestagten Dateien laufen lässt, heißt, dass Style-Probleme behoben sind, bevor sie überhaupt in der Historie existieren:
#!/bin/sh
# .githooks/pre-commit
FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.php$')
[ -z "$FILES" ] && exit 0
vendor/bin/php-cs-fixer fix $FILES
git add $FILES
Git versioniert .git/hooks nicht, leg die Hooks also in einen versionierten Ordner und zeig git einmal darauf:
git config core.hooksPath .githooks
Eine Zeile in der README, und jeder Clone des Repositories bekommt dasselbe Verhalten.
Halt die Hooks schnell. Ein Pre-Commit-Hook, der die komplette Testsuite laufen lässt, wird bis Ende der Woche mit --no-verify umgangen. Style-Korrekturen und eine Syntaxprüfung gehören in den Hook; die Testsuite gehört in CI.
5. Steckt PHPUnit in die Entwicklungsumgebung, nicht daneben
PHPUnit muss für alle gleich laufen — gleiche PHP-Version, gleiche Extensions, gleiche Datenbank. Das heißt, es läuft im Container und nicht auf dem PHP, das die Entwicklerin zufällig auf dem Laptop hat.
Wenn ein Testlauf lokale Einrichtungsschritte braucht, machen manche Leute sie und manche nicht, und die, die es nicht tun, machen Tests kaputt, ohne es zu merken. Wenn ein Testlauf docker compose exec php vendor/bin/phpunit ist, führen alle dasselbe aus.
Das ordentlich in die IDE zu verdrahten kostet etwas Konfiguration — das habe ich separat in wie du PHPUnit lokal in PhpStorm mit Docker ausführst aufgeschrieben.
6. Lasst PHP Insights über die Codebase laufen
PHP Insights gibt dir eine Bewertung über Codequalität, Komplexität, Architektur und Style — und, nützlicher, eine sortierte Liste, was du dir zuerst anschauen solltest:
composer require --dev nunomaduro/phpinsights
vendor/bin/phpinsights
Zwei ehrliche Warnungen dazu.
Der erste Lauf auf einer bestehenden Codebase wird brutal. Das ist in Ordnung. Versuch nicht, auf 100 % zu kommen, und refactor auf keinen Fall am ersten Nachmittag alles — du machst funktionierenden Code kaputt, um eine Kennzahl zu befriedigen.
Und mach die Bewertung nicht zum Selbstzweck. Nutz sie wie einen Rauchmelder: Was zählt, ist die Richtung, in die sie sich nach einer Änderung bewegt, nicht die Zahl selbst. Setz in CI ein Minimum, das die aktuelle Codebase schon besteht, und heb es an, wenn ihr wirklich etwas verbessert habt.
Warum alle sechs und nicht nur die, die dir gefallen
Jedes davon ist klein. Zusammen decken sie eine komplette Schleife ab: Ihr einigt euch auf einen Standard, ein Werkzeug prüft ihn, ein anderes behebt ihn, ein Hook wendet die Behebung vor dem Commit an, CI fängt, was durchgerutscht ist, und eine Kennzahl sagt euch, ob das Ganze funktioniert.
Nimm eines weg, und die Schleife leckt. Ein Style ohne Checker ist ein Vorschlag. Ein Checker ohne Fixer ist Reibung. Ein Fixer, den niemand ausführt, ist toter Code in der composer.json.
Der eigentliche Grund, das am ersten Tag zu machen, ist ohnehin nicht Codequalität. Es ist, dass diese Diskussionen billig sind, solange die Codebase leer ist, und teuer, wenn sie 80.000 Zeilen hat und zwei der drei Leute, die sie geschrieben haben, gegangen sind.