Konfigurace
***********

.[perex]
Soubor dresscode.neon nebo dresscode.php: kde se hledá, jak se vrství presety a extensions, jak se zapínají pravidla a nastavují jejich volby a které cesty se kontrolují.


Soubor
======

Konfigurace je `dresscode.neon` nebo `dresscode.php` v kořeni projektu. Oba zápisy jsou totéž řečené dvakrát: každý klíč NEONu je metoda třídy `DressCode\Config`, takže cokoli umí jeden, umí i druhý, s jedinou výjimkou closures, které do NEONu nenapíšete (o těch níže). Tahle stránka píše NEON, protože se čte lépe; PHP podoba je vždy stejná do slova.

```neon
presets:
	- dresscode/per

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

paths:
	- src
	- tests

excludePaths:
	- tests/fixtures
```

```php
<?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']);
```

DressCode soubor hledá od aktuálního adresáře směrem nahoru a kořenem projektu je adresář, kde ho našel; všechny cesty v konfiguraci jsou relativní k němu. Vedle souboru může ležet šablona `dresscode.neon.dist` (nebo `.php.dist`), která se commituje; soubor bez `.dist` ji celý nahrazuje a hodí se pro místní odchylku, kterou nechcete commitovat. Oba formáty vedle sebe jsou chyba, ne přednost jednoho. Jiný soubor vnutíte přepínačem `--config`.

Překlep v klíči je chyba při načtení, ne tiše ignorovaný řádek. Bez souboru platí preset `dresscode/per` a cesty musíte dát na příkazovou řádku.


Presety a vrstvy
================

Preset je pojmenovaný seznam pravidel s volbami. Vestavěné jsou tři: `dresscode/psr12`, `dresscode/per` (potomek PSR-12 a výchozí) a `dresscode/nette`. Co přesně každý zapíná, ukazuje [přehled presetů |presets-reference].

```neon
presets:
	- dresscode/nette
```

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

1. výchozí hodnoty,
2. extensions v pořadí zápisu,
3. presety v pořadí zápisu (potomek přebírá rodiče),
4. klíče vašeho souboru,
5. příkazová řádka (`--preset`, `--rule`).

Přepisuje se vždy celá položka: když preset nastaví `dresscode/braces-position` s osmi volbami a vy napíšete tutéž s jednou, platí vaše jedna a ostatní se vrátí na výchozí hodnoty pravidla, ne na hodnoty presetu. Je to méně pohodlné než hluboké slučování, ale nikdy nemusíte hádat, co všechno se vám do konfigurace přimíchalo.

**Extension** je balík, který se do konfigurace přihlásí (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. Tak je do DressCode zapojený třeba Nette Coding Standard:

```neon
extensions:
	- Nette\CodingStandard\Extension
```

**Styl** je odsazení a konec řádku. Nastavíte ho sám, jinak platí to, co říká poslední preset, který styl deklaruje, a když žádný, tabulátor a převládající konec řádku každého souboru:

```neon
style:
	indent: "    "
	eol: "\n"
```

Hodnota `eol` je `"\n"`, `"\r\n"`, nebo `auto` pro zachování toho, co v souboru převládá.

**Verze PHP** je vlastnost projektu a čte se z `composer.json`; pravidla pro novější syntaxi se pod ní sama vynechají. Přepíšete ji jen tehdy, když se od `composer.json` liší, a vždy jako řetězec:

```neon
phpVersion: '8.2'
```


Pravidla a volby
================

Klíč `rules` je mapa: jméno pravidla a `true`, `false`, nebo mapa voleb. Jména jsou ta z [přehledu pravidel |rules/@home] a z výpisu `dresscode check`; každá stránka pravidla ukazuje jeho volby s příklady.

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

Dvě věci, na které se naráží:

- **Seznam ve volbě nahrazuje výchozí seznam, neslučuje se s ním.** `multiLine: [arguments]` zapne čárku u argumentů a vypne ji u polí, i když pole jsou výchozí. Chcete-li přidat, opište i výchozí hodnoty.
- **Jméno pravidla jiného nástroje není platný klíč.** `no_unused_imports` ani `SlevomatCodingStandard.Namespaces.UnusedUses` sem nepatří; DressCode je zná a řekne vám, které jeho pravidlo jim odpovídá, ale do konfigurace se píše to jeho. Celý cizí soubor přeloží [`dresscode import` |migration].

Místo jména jde všude použít název třídy, což se hodí u [vlastních pravidel |custom-rule], která tak nemusíte registrovat:

```neon
rules:
	App\CodeStyle\ExceptionMessagePeriodRule: true
```

Na jeden běh pravidlo zapnete nebo vypnete z příkazové řádky: `--rule dresscode/line-length=off`.


Cesty
=====

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

`excludePaths` vynechává cesty a **jen přidává**: k výchozímu seznamu `vendor`, `node_modules`, `temp`, `tmp`, `log` a všem adresářům začínajícím tečkou přidá vaše, a totéž udělá každá extension. Žádná vrstva nemůže vrátit, co jiná vyloučila, takže se nestane, že preset omylem zapne kontrolu `vendor`.

```neon
paths:
	- src
	- tests

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

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

Pravidlo lze vypnout jen pro některé cesty; soubor pak zkontroluje zbytek pravidel:

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

`fileExtensions` říká, které přípony se berou jako PHP (výchozí jen `php`); projekt s testy Nette Testeru přidá `phpt`. Vynechání souboru podle obsahu (třeba generovaného kódu podle hlavičky) je closure `skipWhen()`, takže patří do `dresscode.php` nebo do extension.


Ostatní klíče
=============

- `baseline`: soubor se známými porušeními, která se nehlásí; jak vzniká a kdy se hodí, říká [Potlačení a baseline |suppressing#baseline].
- `cacheDir`: kam si DressCode ukládá, které soubory už byly čisté; výchozí je systémový temp.
- `analyses`: registrace vlastní analýzy pro [vlastní pravidla |rule-contract].

Co konfigurace umí, ukáže i `dresscode rules`: vypíše každé známé pravidlo s hvězdičkou u těch, která jsou v aktuální konfiguraci zapnutá, a se jmény pravidel jiných nástrojů, která pokrývá.