Přechod z Nette Coding Standardu

Nette Coding Standard 4 je preset DressCode. Sám standard se jmenuje dresscode/nette, balíček k němu přidává tři odvozené presety a filtr souborů. Co udělá ecs migrate a proč první oprava přeformátuje víc souborů, než čekáte.

Co se změnilo

Nette Coding Standard byl do verze 3 tenká obálka nad PHP CS Fixerem a PHP_CodeSniffer s balíkem pravidel od Slevomatu: dva nástroje, dvě konfigurace (ncs.php pro fixer, ncs.xml pro sniffer) a příkaz ecs, který to celé spouštěl.

Od verze 4 je standard presetem DressCode. Jmenuje se dresscode/nette a je součástí DressCode, takže ho má k dispozici každý projekt bez ohledu na to, jestli s Nette pracuje. Balíček nette/coding-standard k němu přidává to, co potřebuje navíc projekt postavený na Nette:

• presety nette/clean-code, nette/optimize-fn a nette/types, které standard rozšiřují o pravidla nad rámec stylu, o importy globálních funkcí optimalizovaných kompilátorem a o doplňování nativních typů z anotací;
• PhpVersionFilter, který vynechá soubory s anotací @phpVersion nad běžící verzí PHP, jak to potřebují testy knihoven Nette;
• příkaz ecs z verze 3, aby projekt na trojce fungoval dál, než přejde.

Instalace a konfigurace

composer require --dev dresscode/dresscode nette/coding-standard

Do kořene projektu přijde dresscode.neon, který přihlásí rozšíření balíčku a vybere presety:

extensions:
	- Nette\CodingStandard\Extension

presets:
	- dresscode/nette
	- nette/types      # volitelně také nette/clean-code, nette/optimize-fn

paths:
	- src
	- tests

Rozšíření jen zpřístupní jména presetů z balíčku, vyloučí cesty, které vylučovala verze 3 (expected, tmp, fixtures*), a zapne filtr podle @phpVersion. Který styl se použije, říká klíč presets, protože to je rozhodnutí projektu, ne balíčku.

Kontroluje a opravuje se pak samotným DressCode:

dresscode check
dresscode fix

Převod konfigurace

Projekt s ncs.php nebo ncs.xml je převede jedním příkazem:

vendor/bin/ecs migrate

Přečte ncs.php a ncs.xml v aktuálním adresáři a napíše dresscode.neon. Jména pravidel a kódy sniffů z verze 3 projdou překladem na jména pravidel DressCode. Co žádné pravidlo nepokrývá, příkaz vypíše a vynechá, a u zkopírovaných voleb připojí poznámku, že jejich jména je potřeba zkontrolovat, protože volba fixeru a volba pravidla DressCode se mohou jmenovat jinak. Existující dresscode.neon příkaz nepřepíše.

Příkaz ecs zůstává a přijímá starou příkazovou řádku (ecs check, ecs fix, výchozí cesty src a tests, --preset clean-code), takže CI ani editor nemusíte sáhnout hned. Verzní presety se ignorují, protože cílová verze PHP se teď čte z projektu. Je to ale věc přechodová: jakmile je dresscode.neon na místě, volejte rovnou dresscode.

První oprava přeformátuje víc, než čekáte

Verze 4 není řádek po řádku totéž co verze 3, a je to tak schválně. Některé rozdíly jsou opravy toho, co verze 3 nechávala být: velké písmeno na začátku komentáře // Komentář, komentář /* enum */ před case, declare(strict_types=1) na řádku otevíracího tagu, nezlomitelná mezera zapsaná doslova v řetězci. Napříč balíčky Nette to bylo víc než sto souborů z necelých tří tisíc.

Udělejte to jako samostatný commit: dresscode fix, commit bez jiných změn, hotovo. Procházet to řádek po řádku nemá cenu; cenu má vědět, že v tom commitu není nic jiného.

Co zůstalo

• Komentáře phpcs:ignore a spol. fungují dál; přepis na dresscode:ignore udělá dresscode migrate-suppressions.
• Vlastní sniffy a fixery, pokud nějaké byly, se přepisují podle návodu; přepsaný sniff bývá několikanásobně kratší.