Přechod z PHP CS Fixeru

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

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, a @Symfony na dresscode/symfony, který zatím nemá pravidla o phpDocu. Sady bez protějšku, hlavně @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 rizikové opravy tu nezapíná sada, ale projekt u jednotlivých pravidel (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(true). Svolení k rizikovým opravám nedává DressCode celé konfiguraci, ale jednotlivým pravidlům: jejich jména patří do seznamu fixRisky. Bez něj se rizikové opravy jen hlásí.

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 opravy, které mohou změnit chování programu. Ty DressCode nezapíná zvláštní sadou. Pravidlo, které bezpečný případ poznat umí, je hlásí jako rizikové místo po místě: get_class($x) na $x::class je bezpečné, dokud $x nemůže být null, takže dresscode/modern-class-name-reference bezpečná místa opraví a riziková jen ohlásí. Pravidlo, které to poznat neumí, jako dresscode/strict-call, má za rizikovou každou svou opravu. V obou případech se riziková oprava udělá teprve tehdy, když pravidlo uvedete v seznamu fixRisky v konfiguraci, nebo na jeden běh s --fix-risky. Pravidlo, které mění význam vždy (dresscode/strict-comparison dělá z == ===), zůstává vaším rozhodnutím ve chvíli, kdy ho zapínáte; říká to jeho popis, ne značka risky.

Zvláštní skupinou jsou fixery, které PHP CS Fixer označuje jako rizikové proto, že funkci může někdo přepsat ve jmenném prostoru: is_null, no_alias_functions, dir_constant a další. Tuhle nejistotu v DressCode rozhoduje konfigurace. S klíčem nameResolution: certain a seznamy v klíči namespaces ví, co ve vašich jmenných prostorech je, a odpovídající opravy jsou bezpečné; viz Funkce a konstanty ve jmenných prostorech.

Příkazy

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 zapíšete jako přepis v klíči overrides, bez druhého konfiguračního souboru; pravidlo tam dostane jinou hodnotu, nebo keep, které ho vypne.
• Baseline. Pravidlo, které váš kód zatím nesplňuje a opravit ho za vás nejde, zapnete hned: dnešní porušení se zapíšou a hlásit se budou jen nová. PHP CS Fixer ji nemá; jak ji DressCode skloubil s opravami, popisuje Baseline.
• 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.