Přechod z PHP CS Fixeru

Převod .php-cs-fixer.dist.php na konfiguraci DressCode, sady @PSR12 a @PER-CS na presety, tabulka příkazů a vysvětlení, proč tu rizikové (risky) pravidlo rizikové obvykle není.

Než začnete

Projděte si společný postup: kód a komentáře můžete nechat, jak jsou, konfiguraci převede import a komentáře přepíše migrate-suppressions. Tahle stránka doplňuje, co je u PHP CS Fixeru zvláštní.

Nejdůležitější věc rovnou: konfigurace PHP CS Fixeru je PHP soubor, který se musí spustit, a vrací objekt jeho knihovny. Příkaz dresscode import ho proto přečte jen v projektu, kde je friendsofphp/php-cs-fixer ještě nainstalovaný. Překládejte tedy dřív, než ho odeberete.

Převod konfigurace

dresscode import .php-cs-fixer.dist.php > dresscode.php

Sady se překládají na presety: @PSR1, @PSR2 a @PSR12 na dresscode/psr12, @PER, @PER-CS a jejich číslované varianty na dresscode/per, který odpovídá PER Coding Style 3.1. Sady bez protějšku, hlavně @Symfony a @PhpCsFixer, import ohlásí; v takovém případě začněte od dresscode/per a doplňte pravidla, na kterých vám záleží. Sady s příponou :risky protějšek nemají, protože rozdělení na riziková a bezpečná pravidla tu neexistuje (viz níže).

Jednotlivé fixery se překládají jménem, a kde má volba protějšek, tak i s ní: no_unused_imports je dresscode/unused-imports, binary_operator_spaces je dresscode/binary-operator-spacing, trailing_comma_in_multiline se svým elements je dresscode/trailing-comma s volbou multiLine. Fixer, který protějšek nemá, se objeví ve výpisu na chybovém výstupu, a z toho máte seznam věcí, o kterých je potřeba rozhodnout. Vlastní fixery z balíčku kubawerlos/php-cs-fixer-custom-fixers se překládají také, pokud pro ně DressCode pravidlo má.

Co import nepřenese, protože to v konfiguraci Fixeru nejsou pravidla:

Finder. Cesty, exclude() a notPath() přepište do klíčů paths a excludePaths; vzory popisuje Konfigurace.
Odsazení a konce řádků (setIndent(), setLineEnding()). Nastaví je preset; pokud žádný nepoužíváte, doplňte klíč style.
setRiskyAllowed() protějšek nemá a není potřeba.

Riziková pravidla

PHP CS Fixer označuje jako rizikové (risky) takové pravidlo, které nad polem tokenů nedokáže odlišit bezpečný případ od nebezpečného, a rozhodnutí nechává na vás. Typický příklad je ternary_to_elvis_operator: nepozná, jestli je podmínka ternárního operátoru proměnná, nebo volání funkce s vedlejším účinkem, takže hlídá jen ++ a -- a zbytek je váš problém.

V DressCode tohle rozdělení není, protože otázku zodpoví strom: pravidlo dresscode/short-ternary-operator zkrátí ternární operátor jen tehdy, když je podmínku bezpečné vyhodnotit dvakrát, a volání funkce nechá být. Totéž platí pro další pravidla, která byla riziková z téhož důvodu.

Něco jiného jsou pravidla, která mění chování programu ze své podstaty: strict_comparison dělá z == === a to není otázka syntaxe, ale významu. dresscode/strict-comparison dělá totéž a je na vás, jestli ho zapnete. Jen se to nedozvíte ze značky risky, ale z popisu pravidla.

Příkazy

PHP CS Fixer	DressCode
`php-cs-fixer fix --dry-run`	`dresscode check`
`php-cs-fixer fix --dry-run --diff`	`dresscode check --diff`
`php-cs-fixer fix`	`dresscode fix`
`php-cs-fixer fix --config=soubor`	`dresscode fix --config soubor`
`php-cs-fixer fix --rules=jméno`	`dresscode fix --rule jméno=on` (přidá pravidlo k presetu, nenahradí jím celou sadu)
`php-cs-fixer fix --format=checkstyle`	`dresscode check -f checkstyle`
`php-cs-fixer fix --allow-risky=yes`	nic, viz výše
`.php-cs-fixer.cache`	cache je zapnutá sama; `--no-cache` ji obejde

Exit kód PHP CS Fixeru je bitová maska (8 znamená nalezená porušení, 16 chybu konfigurace a tak dále), kdežto DressCode vrací 0 pro čisto, 1 pro porušení a 2 pro selhání nástroje. Skript v CI, který masku vyhodnocoval, potřebuje jednu úpravu.

Co v PHP CS Fixeru nebylo

Potlačení na řádku. PHP CS Fixer neumí vypnout pravidlo pro jeden řádek ani pro blok, jen pro celý soubor přes Finder. Tady je na to // dresscode:ignore jméno a dvojice dresscode:disable a dresscode:enable, viz Potlačení pravidel a baseline.
Pravidlo jen pro některé cesty je klíč excludeRulePaths v konfiguraci, bez druhého konfiguračního souboru.
Vlastní pravidlo píšete proti stromu, ne proti tokenům. Návod je na jedno odpoledne a kdo má vlastní fixer, přepíše ho podle samostatné stránky.