Konfigurace

Konfigurace je jeden soubor v kořeni projektu: buď dresscode.neon, tedy NEON známý z PHPStanu a se schválně podobnými klíči, nebo dresscode.php, pokud dáváte přednost PHP. Řekne se v něm, co se kontroluje, podle jakého presetu a která pravidla mají jinou volbu.

Konfigurační soubor

Oba formáty umějí totéž: každý klíč NEONu odpovídá jedné metodě třídy DressCode\Config. Jediné, co se do NEONu nevejde, jsou anonymní funkce (closures), a ty patří do PHP nebo do rozšíření. Následující dva soubory dělají přesně totéž:

presets:
	- dresscode/per

rules:
	dresscode/ordered-imports: true
	dresscode/line-length:
		limit: 100

paths:
	- src
	- tests

excludePaths:
	- tests/fixtures

<?php declare(strict_types=1);

use DressCode\Config;

return Config::create()
	->preset('dresscode/per')
	->enable('dresscode/ordered-imports')
	->enable('dresscode/line-length', ['limit' => 100])
	->paths(['src', 'tests'])
	->excludePaths(['tests/fixtures']);

Dál na téhle stránce píšeme NEON, protože se čte lépe; převod do PHP je vždy mechanický.

Soubor se hledá od aktuálního adresáře směrem nahoru a kořenem projektu se stane adresář, ve kterém se našel. Všechny cesty v konfiguraci jsou relativní k němu. Vedle něj může ležet šablona dresscode.neon.dist (nebo .php.dist), kterou commitujete; soubor bez .dist ji pak celou nahradí a hodí se pro místní odchylku, kterou commitovat nechcete. Mít vedle sebe NEON i PHP je chyba, ne přednost jednoho z nich. Jiný soubor vnutíte přepínačem --config.

Překlep v klíči je chyba při načtení, ne tiše přeskočený řádek. Bez konfiguračního souboru platí preset dresscode/per, cesty se zadávají na příkazové řádce a jiný preset se vybere přepínačem --preset.

Presety a vrstvy

Preset je pojmenovaná sada pravidel s volbami, dohromady jeden coding standard. Vestavěné jsou tři: dresscode/psr12, dresscode/per podle PER Coding Style 3.1 (potomek PSR-12 a výchozí volba) a dresscode/nette. Co přesně každý z nich zapíná, ukazuje přehled presetů.

presets:
	- dresscode/nette

Nastavení se skládá z vrstev a vyšší vrstva přepisuje nižší tam, kde něco nastavila:

výchozí hodnoty,
rozšíření (extensions) v pořadí zápisu,
presety v pořadí zápisu, přičemž potomek přebírá rodiče,
klíče vašeho konfiguračního souboru,
příkazová řádka (--preset, --rule).

Přepisuje se vždy celá položka, nikdy se neslučuje: když preset nastaví pravidlu dresscode/braces-position osm voleb a vy uvedete jednu, platí ta vaše a zbylých sedm se vrátí na výchozí hodnoty pravidla, ne na hodnoty presetu. Je to méně pohodlné než hloubkové slučování, zato nikdy nemusíte hádat, co všechno se vám do konfigurace přimíchalo odjinud.

Rozšíření (extension) je balíček, který se do konfigurace přihlásí, podobně jako u PHPStanu: zaregistruje vlastní pravidla a presety pod jmény a může nastavit výchozí hodnoty, které vaše konfigurace přepíše. Takhle se do DressCode zapojuje třeba Nette Coding Standard:

extensions:
	- Nette\CodingStandard\Extension

Styl je odsazovací jednotka a konec řádku. Můžete si ho určit sám; jinak platí to, co říká poslední preset, který styl deklaruje, a když žádný, pak tabulátor a ten konec řádku, který v souboru převládá:

style:
	indent: "    "
	eol: "\n"

Hodnota eol je "\n", "\r\n", nebo auto pro zachování stavu každého souboru.

Cílová verze PHP je vlastnost projektu a čte se z composer.json; pravidla pro novější syntaxi se pod ní sama vynechají. Přepisujte ji jen tehdy, když se od composer.json liší, a vždy jako řetězec, aby se 8.10 nepřečetlo jako 8.1:

phpVersion: '8.2'

Pravidla a jejich volby

Klíč rules je mapa, ve které je jménu pravidla přiřazeno true, false, nebo mapa voleb. Jména jsou ta z přehledu pravidel a z výpisu dresscode check; volby každého pravidla najdete i s příklady na jeho stránce.

rules:
	dresscode/strict-comparison: true
	dresscode/no-alternative-syntax: false
	dresscode/trailing-comma:
		multiLine: [arrays, arguments]

Dvě věci, na kterých se dá zakopnout:

Seznam ve volbě nahrazuje výchozí seznam, neslučuje se s ním. multiLine: [arguments] zapne koncovou čárku u argumentů a vypne ji u polí, i když u polí byla ve výchozím stavu. Chcete-li přidávat, opište i výchozí hodnoty.
Jméno pravidla z jiného nástroje není platný klíč. no_unused_imports ani SlevomatCodingStandard.Namespaces.UnusedUses sem nepatří. DressCode je zná a v chybové hlášce vám řekne, které jeho pravidlo jim odpovídá, ale do konfigurace patří jméno jeho. Celý cizí konfigurační soubor převede příkaz dresscode import.

Místo jména lze všude použít název třídy, což se hodí u vlastních pravidel, která pak nemusíte nikde registrovat:

rules:
	App\CodeStyle\ExceptionMessagePeriodRule: true

Na jeden běh se pravidlo zapíná a vypíná z příkazové řádky: --rule dresscode/line-length=off.

Cesty

paths říká, co se kontroluje: soubory a adresáře relativně ke kořeni projektu. Cesty zadané na příkazové řádce mají přednost před konfigurací.

excludePaths naopak cesty vynechává a jen přidává: k výchozímu seznamu (vendor, node_modules, temp, tmp, log a všechny adresáře začínající tečkou) přidá vaše, a totéž udělá každé rozšíření. Žádná vrstva nemůže vrátit zpátky to, co jiná vyloučila, takže se nestane, že by preset omylem zapnul kontrolu vendor.

paths:
	- src
	- tests

excludePaths:
	- tests/fixtures
	- '*.generated.php'

Vzor s lomítkem je ukotvený ke kořeni, takže tests/fixtures je právě ten jeden adresář. Vzor bez lomítka odpovídá jménu souboru nebo adresáře v jakékoli hloubce, takže fixtures vynechá každý adresář toho jména. Hvězdička zastupuje cokoli kromě lomítka.

Jednotlivé pravidlo lze vypnout jen pro některé cesty; zbytek pravidel takový soubor zkontroluje normálně:

excludeRulePaths:
	dresscode/strict-comparison: [legacy]
	dresscode/line-length: [tests]

fileExtensions říká, které přípony se berou jako PHP (výchozí je jen php); projekt s testy Nette Testeru přidá phpt. Vynechat soubor podle jeho obsahu, třeba generovaný kód podle hlavičky, umí anonymní funkce skipWhen(), takže tohle nastavení patří do dresscode.php nebo do rozšíření.

Další klíče

baseline: soubor se soupisem porušení, která se nemají hlásit; jak vzniká a kdy se hodí, popisuje Potlačení pravidel a baseline.
cacheDir: kam si DressCode ukládá, které soubory už prošly čistě; výchozí je systémový dočasný adresář.
analyses: registrace vlastní analýzy pro vlastní pravidla.

Co je nakonec zapnuté, ukáže příkaz dresscode rules: vypíše všechna známá pravidla, hvězdičkou označí ta, která v aktuální konfiguraci platí, a u každého uvede jména pravidel jiných nástrojů, která pokrývá.