Začínáme

Nainstalujete DressCode, poprvé ho pustíte nad svým projektem a necháte ho opravit, co umí. Do deseti minut víte, co znamenají výstupy a exit kódy a jak první opravu commitnout.

Instalace

DressCode je obyčejná vývojová závislost:

composer require --dev dresscode/dresscode

Nic dalšího se neinstaluje a nic se nekonfiguruje. Parser a strom, na kterých DressCode stojí, nemají žádnou závislost; nástroj kolem nich potřebuje čtyři malé balíčky z Nette a phpDoc parser od PHPStanu, žádný framework. Když jsem ho poprvé přidával do projektu, který už měl PHP CS Fixer, čekal jsem tahanici verzí v Composeru. Nepřišla.

První kontrola

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

vendor/bin/dresscode check src tests

Bez konfiguračního souboru platí preset dresscode/per, tedy PER Coding Style, nástupce PSR-12. Verzi PHP si DressCode přečte z composer.json, takže pravidla pro novější syntaxi se zapnou jen tam, kde ji projekt smí používat. 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 (řádek a sloupec), co (zpráva popisuje, jak má kód vypadat) a které pravidlo to hlásí. Jméno pravidla vpravo je to, s čím se dá něco dělat: najít ho v přehledu pravidel, vypnout ho nebo nastavit anebo potlačit na jednom místě.

Exit kódy jsou tři a stojí za zapamatování, protože na nich stojí CI:

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

První oprava

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

vendor/bin/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 se opravit nedá (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, jako unifikovaný diff, 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 s opravdovou změnou. Na velkém projektu, kde by první oprava byla neúnosná, je druhá cesta: baseline, která dnešní porušení zapíše a hlásí jen nová.

Druhé spuštění nad opraveným kódem je rychlejší než první: DressCode si pamatuje obsah souborů, které už byly čisté, a pokud se nezměnil ani on, ani konfigurace, nezpracovává je znovu.

Konfigurační soubor

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

paths:
	- src
	- tests

Od té chvíle stačí vendor/bin/dresscode check. Do téhož souboru později přijdou presety, pravidla s volbami i výjimky pro cesty; všechno je na stránce Konfigurace. Kdo má radši PHP než NEON, napíše totéž do dresscode.php; oba zápisy jsou rovnocenné.

Kam dál

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