Začínáme s DressCode

Za pět minut máte nástroj nainstalovaný, projekt zkontrolovaný a většinu nálezů opravenou. Projdeme instalaci, příkazy check a fix, volbu stylu podle PER Coding Style 3.1 nebo Nette a konfigurační soubor, který pak stačí commitnout.

Instalace

DressCode je nástroj, ne knihovna, takže nejlepší je nainstalovat ho mimo projekt, který kontroluje. Nejjednodušší je globální instalace:

composer global require dresscode/dresscode

Adresář s globálními binárkami Composeru přidejte do proměnné PATH a příkaz dresscode je pak k dispozici odkudkoli.

Do průběžné integrace, kde chcete verzi nástroje přibít na konkrétní číslo, se hodí instalace jako samostatný projekt:

composer create-project dresscode/dresscode temp/dresscode
temp/dresscode/bin/dresscode check src

A do třetice: DressCode lze přidat i jako vývojovou závislost projektu (composer require --dev dresscode/dresscode) a spouštět z vendor/bin/dresscode. Funguje to, ale platíte za to tím, že se závislosti nástroje mísí se závislostmi projektu. Sám DressCode vyžaduje PHP 8.4 nebo novější, takže by na 8.4 musel běžet i váš projekt, i kdyby mu jinak stačilo starší PHP.

To je totiž věc, která se plete nejčastěji: verze PHP, na které běží nástroj, a verze PHP, pro kterou je psaný váš kód, jsou dvě různá čísla. Když je DressCode nainstalovaný mimo projekt, může běžet třeba na PHP 8.5 a přitom kontrolovat kód psaný pro PHP 8.1. Cílovou verzi si přečte z composer.json vašeho projektu a pravidla se jí řídí, takže vám do kódu nikdy nenapíše syntaxi, kterou by projekt neuměl přeložit.

Víc DressCode nepotřebuje: parser a strom, na kterých stojí, jsou samostatná knihovna PhpSyntax bez jediné závislosti, k tomu čtyři malé balíčky z Nette a parser phpDocu od PHPStanu. Žádný framework.

Kontrola kódu

Řekněte DressCode, kam se má podívat:

dresscode check src tests

Bez další konfigurace platí preset dresscode/per, tedy PER Coding Style 3.1, nástupce PSR-12. Jiný styl vyberete přepínačem --preset, ať už jednorázově, nebo než si založíte konfigurační soubor:

dresscode check src --preset dresscode/nette

Výstup vypadá takhle:

DRESS|CODE 1.0
Config     none, preset dresscode/per
Target     PHP 8.2 from composer.json
Checking   214 files in /var/www/shop

src/Cart.php
  error   8:12  A line break before the opening brace                       braces-position
  error   9:25  An array must be written with the short syntax              short-array-syntax
  error  10:21  No whitespace after the opening parenthesis                 parentheses-spacing
  error  11:11  At least one space before the == operator                   binary-operator-spacing
  error  11:19  The body of a control structure must be enclosed in braces  control-structure-braces

FOUND  36 violations, 36 of them fixable in 12 files

Každý řádek říká, kde problém je (řádek a sloupec), co je špatně (zpráva popisuje, jak má kód vypadat) a které pravidlo to hlásí. Jméno pravidla vpravo je to, s čím se dá dál pracovat: najít ho v přehledu pravidel, nastavit nebo vypnout anebo potlačit na jednom místě.

Hlavička nahoře odpovídá na dvě otázky, které jinak stojí za polovinou nedorozumění: podle čeho se kontroluje (konfigurační soubor a presety) a pro jakou verzi PHP.

Exit kódy jsou tři a stojí za zapamatování, protože na nich stojí kontrola v průběžné integraci:

kód význam
0 čisto
1 nalezená porušení, nebo soubor, který nejde parsovat
2 selhání nástroje: špatná konfigurace, neznámé pravidlo, chyba za běhu

Automatická oprava

Většinu nálezů opraví DressCode sám. Před prvním během si soubory commitněte nebo aspoň mějte čistý pracovní strom, ať v diffu vidíte přesně to, co nástroj změnil:

dresscode fix src tests

src/Cart.php
  fixed   8:12  A line break before the opening brace                       braces-position
  fixed   9:25  An array must be written with the short syntax              short-array-syntax
  ...

FIXED  36 violations fixed in 12 files

Co opravit nejde (třeba příliš dlouhý řádek), zůstane ve výpisu jako error a exit kód bude 1; jinak 0. Kdo chce opravy napřed vidět, pustí dresscode check --diff: ukáže, co by fix změnil, a nic nezapíše.

Opravu udělejte jako samostatný commit bez jiných změn. Je to jeden z těch commitů, které nikdo nečte řádek po řádku, a přesně tak má vypadat: git blame pak vede na něj a ne na váš další commit se skutečnou změnou. Na velkém projektu, kde by byl takový commit neúnosný, je druhá cesta: baseline zapíše dnešní stav a hlásí jen nová porušení.

Druhé spuštění je rychlejší než první: DressCode si pamatuje obsah souborů, které prošly čistě, a pokud se nezměnil ani obsah, ani konfigurace, nezpracovává je znovu.

Konfigurace v NEONu

Aby nebylo nutné pokaždé vypisovat cesty a preset, založte v kořeni projektu soubor dresscode.neon:

presets:
	- dresscode/nette

paths:
	- src
	- tests

Je to NEON, tedy formát, který znáte z konfigurace PHPStanu, a klíče jsou schválně podobné: paths, excludePaths, phpVersion. Kdo má radši PHP, napíše totéž do dresscode.php jako volání nad objektem Config; oba zápisy umějí totéž, jen anonymní funkce se do NEONu nevejdou.

Od téhle chvíle stačí dresscode check. Do téhož souboru přijdou i jednotlivá pravidla s volbami a výjimky pro cesty; všechno popisuje stránka Konfigurace.

Kam dál

  1. Dokumentace
  2. DressCode
  3. Začínáme s DressCode
verze: 1.0