Jan Mikoláš
Slovník pojmů
PHP_CodeSniffer
PHP_CodeSniffer sjednocuje automaticky kontrolovatelná pravidla zápisu. Týmu šetří opakované připomínky v code review, aniž by nahrazoval testy nebo návrhovou diskuzi.
Stručná definice
Kontrola dohodnutého zápisu, ne důkaz správnosti aplikace.
PHP_CodeSniffer se obvykle označuje zkratkou PHPCS. Při průchodu souborem ho rozdělí na tokeny PHP a každý aktivní sniff — jednotlivé kontrolní pravidlo — ověřuje konkrétní část zápisu. Může tak najít porušení PSR-12 i pravidel, na kterých se domluvil konkrétní tým.
Druhý příkaz PHPCBF, PHP Code Beautifier and Fixer, opraví pouze ty nálezy, pro něž daný sniff nabízí bezpečnou automatickou opravu. Ani čistý výstup PHPCS proto neznamená, že aplikace má správné typy, architekturu nebo business logiku.
Použití
Kdy je kontrola standardů užitečná
Největší přínos má tam, kde na kódu pracuje více lidí nebo projekt žije dost dlouho na to, aby se nejednotný zápis začal zpomalovat při čtení a úpravách.
- sjednocení formátu souborů, odsazení, mezer a pořadí vybraných částí PHP souboru
- kontrola týmových konvencí pro názvy, importy, komentáře a zakázané konstrukce
- automatická oprava jednoznačných změn pomocí PHPCBF před commitem nebo v editoru
- rychlá kontrola změněných souborů v pull requestu a v CI
- postupné zavedení stabilních pravidel do staršího PHP projektu
Praktický příklad
Ruleset pro zdrojový kód aplikace
Administrace e-shopu může používat PSR-12 jako společný základ a upravit jen několik konkrétních pravidel. Konfigurace se uloží do repozitáře, takže lokální editor i CI posuzují tentýž zdrojový kód stejným způsobem.
Tento ruleset kontroluje kořen projektu, vynechá generovaná data ve var a nastaví čitelný limit délky řádku. Tým by měl přidávat vlastní pravidlo jen tehdy, pokud mu dává dlouhodobý a srozumitelný důvod.
<?xml version="1.0"?>
<ruleset name="Projekt">
<rule ref="PSR12"/>
<file>.</file>
<exclude-pattern>*/var/*</exclude-pattern>
<rule ref="Generic.Files.LineLength">
<properties>
<property name="lineLimit" value="120"/>
</properties>
</rule>
</ruleset>Jak funguje
Od rulesetu k přehledné zpětné vazbě
PHPCS nepoměřuje soubor s jednou šablonou znak po znaku. Použije sadu pravidel reagujících na konkrétní tokeny a konstrukce.
- Výběr souborů Příkaz nebo ruleset určí adresáře, přípony a případné výjimky.
- Ruleset Načte PSR-12, jiný nainstalovaný standard nebo vlastní kombinaci pravidel.
- Tokenizace Zdrojový kód se rozdělí na PHP tokeny, jako jsou třídy, metody, závorky a importy.
- Sniffs Jednotlivé sniffs vyhodnotí relevantní tokeny a oznámí chybu nebo varování včetně identifikátoru konkrétního pravidla.
- Oprava a gate PHPCBF opraví jen fixovatelné nálezy; PHPCS pak může zůstat povinnou kontrolou před mergem.
Hlavní části
Standard, ruleset, sniff a fixer nejsou totéž
Přesné pojmenování pomáhá nastavit pravidla tak, aby byla pro tým předvídatelná.
Coding standard
Soubor dohod o zápisu kódu, například PSR-12. Účelem je snížit námahu při čtení kódu od různých autorů.
Sniff
Jedno kontrolní pravidlo uvnitř standardu, například pro odsazení, délku řádku nebo pořadí importů.
Ruleset
Projektová XML konfigurace, která standardy kombinuje, vyřazuje pravidla, mění jejich vlastnosti a omezuje kontrolované cesty.
PHPCS
Kontrolní příkaz, který vypíše porušení pravidel, jejich řádek a identifikátor konkrétního snifflu.
PHPCBF
Doprovodný fixer pro automaticky opravitelné nálezy PHPCS. Po opravě je vhodné změnu zkontrolovat v diffu.
Co tento nástroj nekontroluje
Čtyři odlišné druhy kontroly
Výstupy se mohou v CI objevit vedle sebe, ale každý odpovídá na jinou otázku.
- Syntax lint
- php -l ověří, zda PHP parser dokáže soubor načíst. Neřeší týmový styl ani možné typové chyby v běžící aplikaci.
- PHPStan
- Statický analyzátor hledá typové a kontraktní rozpory, například volání metody nad hodnotou null. PHPCS se soustředí na pravidla zápisu.
- PHPUnit
- Spouští testovací scénáře a ověřuje očekávané chování. Žádný počet úspěšných testů neurčuje mezery nebo názvy importů.
- ECS a PHP-CS-Fixer
- Také automatizují formátovací pravidla, ale jsou samostatnými nástroji s vlastní konfigurací. PHPCBF opravuje pouze nálezy pravidel PHPCS.
Výhody a omezení
Pomoc pro soustředění, ne náhrada technického úsudku
Přínosy
- stejně posuzovaný kód v IDE, před commitem i v CI
- méně opakovaných připomínek k formátu při code review
- rychlé automatické opravy jednoznačných stylových odchylek
- pojmenovaná a verzovaná pravidla místo nepsaných zvyklostí
Omezení a časté chyby
- bezchybný styl neprokazuje správnou architekturu, bezpečnost ani business pravidla
- příliš mnoho lokálních pravidel a výjimek může přidat více režie než užitku
- ne každá oprava PHPCBF je vhodná bez kontroly změny v diffu
- potlačování nálezů bez zdůvodnění snadno znehodnotí důvěru v pravidla
Rozumné zavedení
Pravidla mají být stabilní, automatizovatelná a společně srozumitelná.
Jako základ obvykle stačí zavedený standard, například PSR-12, a malý počet pravidel odpovídajících skutečným potřebám repozitáře. Pokud projekt používá existující firemní standard, je důležitější konzistentní používání a jasné vysvětlení výjimek než snaha shromáždit maximum sniffs.
PHPCS může běžet při ukládání souboru, v Git hooku i v CI. Automaticky opravitelné nálezy je praktické vyřešit před odesláním změny; neopravené nebo neautomatizovatelné problémy pak mají mít čitelnou zprávu a přiměřenou závažnost.
Na co myslet
Automatizace má zjednodušovat práci týmu
Cílem není získat nejdelší konfiguraci, ale odstranit mechanické rozhodování z každodenní spolupráce.
- ruleset verzovaný společně se zdrojovým kódem
- výchozí standard s minimem odůvodněných úprav
- oddělení generovaných souborů a externího kódu od kontroly
- PHPCBF pro bezpečně opravitelné odchylky
- rychlá kontrola změn v IDE nebo pre-commitu a úplná v CI
- pravidelná revize výjimek a vlastních sniffs
Časté otázky
PHP_CodeSniffer v praxi
Je PHP_CodeSniffer nástroj pro statickou analýzu?
Kontroluje zdrojový kód bez spuštění, ale jeho hlavním účelem jsou coding standards. PHPStan analyzuje typy, možné volání a kontrakty; oba nástroje se doplňují, nenahrazují.
Nahradí PHPCBF code review?
Ne. Odstraní jen část mechanických stylových odchylek. Code review stále řeší návrh, srozumitelnost změny, bezpečnost a doménové rozhodnutí.
Má tým používat PHPCBF, ECS i PHP-CS-Fixer najednou?
Jen pokud má pro překrytí jasný důvod a pravidla si vzájemně nepřepisují změny. Pro běžný projekt je praktičtější určit jeden nástroj pro automatické formátování a jeho konfiguraci držet jednoduchou.
Je PSR-12 povinný pro každý PHP projekt?
Ne. Je to široce používaný výchozí standard, ne zákon. Projekt může mít odůvodněný jiný nebo rozšířený standard, ale tým by jej měl používat konzistentně.
Jak kontroly kvality používám v praxi
Standardy dávají smysl vedle testů, analýzy a architektonických pravidel.
PHP_CodeSniffer používám jako jednu z vrstev průběžné zpětné vazby. Mechanická pravidla drží konzistentní zápis, aby se při review mohl prostor věnovat rizikům změny.