Jak se DressCode rozšiřuje

Pravidlo, preset, extension, analýza nebo reporter: co je kdy správná volba a co z DressCode je veřejné API, na které se dá spolehnout.

Pět míst, kam se dá sáhnout

Pravidlo je odpověď na „chci hlídat ještě tohle“. Třída, která řekne, které uzly ji zajímají, položí otázku a případně opraví. Píše se za odpoledne: Vlastní pravidlo.

Preset je odpověď na „chci tenhle styl na všech projektech“. Pojmenovaný seznam pravidel s volbami, který může vycházet z jiného presetu. Preset a balík.

Extension je odpověď na „chci to distribuovat jako balíček“. Třída, která se do konfigurace přihlásí, zaregistruje pravidla a presety pod jmény a nastaví výchozí hodnoty; uživatel ji zapne jedním řádkem. Tak je postavený Nette Coding Standard. Preset a balík.

Analýza je odpověď na „víc pravidel potřebuje tutéž informaci o souboru“. Obyčejná třída postavená nad stromem, kterou si pravidla vyžádají a engine ji staví jednou a po každé změně stromu zahodí. Vestavěné jsou NameResolver, Scope a PhpDoc. Pravidla hry.

Reporter je odpověď na „chci výsledky jinam než do terminálu“: rozhraní se třemi metodami, které dostává výsledky soubor po souboru. PHP API.

Co DressCode rozšířit nejde: parser. Gramatika je PHP a nic jiného, a strom, který z ní vychází, je pro všechna pravidla stejný. Právě proto se dají pravidla skládat, aniž by o sobě musela vědět.

Co je veřejné API

Na co se plugin může spolehnout mezi minoritními verzemi:

• z DressCode: Config, Rule, ConfigurableRule, GapRule s Claim, Space, Line a Gap, RuleInfo, RuleContext, RuleStorage, Preset, PresetInfo, PresetContext, Violation, Reporter s FileResult a RunResult, Runner, Console\Application, Config\Loader, analýzy v Analyses\ a vestavěná pravidla v Rules\, Testing\RuleTester;
• z PhpSyntax: Parser\Parser, Lexer\Lexer, Printer, Traverser, Node, Token, Trivia, TokenKind, Style, PhpVersion, Indentation, analýzy, všechny uzly v Nodes\, výčty a ParseException.

Co je označené @internal, se může změnit kdykoli; pluginy k tomu nemají důvod sahat, protože všechno, co potřebuje vestavěné pravidlo, je veřejné. Nový uzel stromu může přibýt v minoritní verzi spolu s novou syntaxí PHP; pravidlo, které má match přes třídy uzlů, proto potřebuje větev default.

Pojmenování

Jméno pravidla je vendor/slug v kebab-case a říká stav, který pravidlo vynucuje, ne krok, který dělá oprava: acme/exception-message-period, ne acme/add-period. Předpona no- znamená konstrukci, která se nesmí objevit vůbec, useless- konstrukci, která je jinde správná, ale tady nic nepřidává. Jméno presetu je vendor/název-standardu. Je to konvence vestavěného katalogu a plugin, který se jí drží, do něj zapadne.