Začínáme ******** .[perex] 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: ```shell 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: ```shell vendor/bin/dresscode check src tests ``` Bez konfiguračního souboru platí preset `dresscode/per`, tedy [PER Coding Style |https://www.php-fig.org/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: /--pre .[terminal] 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 |rules/@home], [vypnout ho nebo nastavit |configuration] anebo [potlačit na jednom místě |suppressing]. 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: ```shell vendor/bin/dresscode fix src tests ``` /--pre .[terminal] 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 |suppressing#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`: ```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 |configuration]. Kdo má radši PHP než NEON, napíše totéž do `dresscode.php`; oba zápisy jsou rovnocenné. Kam dál ======= - [Jak DressCode přemýšlí |how-it-works], pokud chcete rozumět tomu, proč se konfigurace chová, jak se chová. - [Přechod na DressCode |migration], pokud dnes používáte PHP CS Fixer, PHP_CodeSniffer nebo ECS. - [Editory a IDE |editors], aby se porušení ukazovala při psaní a ne až v terminálu. - [Průběžná integrace |continuous-integration], aby to hlídal i server.

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