Rozšiřování DressCode

Vlastní pravidlo, preset, rozšíření, analýza nebo reporter: co je kdy správná volba a na které části DressCode se dá spolehnout jako na veřejné API.

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

Pravidlo je odpověď na „chci hlídat ještě tohle“. Buď NodeRule, které řekne, které uzly ho zajímají, položí otázku a případně opraví, nebo GapRule, které vysloví požadavek na bílé znaky mezi tokeny. Napíšete ho za odpoledne: Jak napsat vlastní pravidlo. Když plní některý ze šesti záměrů, které pojmenovávají skupiny pravidel, přihlásí se do své skupiny a začne pracovat každému, kdo si o ni řekl, aniž by o vašem pravidle věděl. Vlastní skupinu si vymyslet nemůžete, a to je záměr: šest jmen je celý seznam, který se uživatel učí, ať má nainstalováno cokoli.

Preset je odpověď na „chci tenhle styl na všech projektech“. Pojmenovaná sada pravidel s volbami a stylem, která může vycházet z jiného presetu a dá se zapnout pro celý projekt i jen pro jeho část. Viz Vlastní preset a rozšíření.

Rozšíření (extension) je odpověď na „chci to rozdávat jako balíček“. Třída, kterou projekt uvede v konfiguraci: dá jména pravidlům a presetům z balíčku a přidá vyloučené cesty nebo filtr souborů; uživatel ji zapne jediným řádkem a styl si vybere presetem sám. Takhle je postavený Nette Coding Standard. Viz Vlastní preset a rozšíření.

Analýza je odpověď na „tuhle informaci o souboru potřebuje víc pravidel“. Obyčejná třída postavená nad stromem, kterou si pravidla vyžádají; jádro ji vytvoří jednou a po každé změně stromu zahodí. Vestavěné jsou NameResolver a Scope a PhpDoc. Viz Pravidlo do detailu.

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

Co rozšířit nejde, je parser. Ten je samostatná knihovna PhpSyntax, jeho gramatikou je PHP a nic jiného, a strom, který z ní vzejde, je pro všechna pravidla stejný. Právě proto se dají pravidla skládat, aniž by o sobě musela navzájem vědět.

Co je veřejné API

Na tyhle třídy se rozšíření může spolehnout mezi minoritními verzemi:

• psaní pravidla: Rule s potomky NodeRule a GapRule, ConfigurableRule, RuleInfo, RuleContext, Claim, Gap, Style, Violation a výčty Stage, Severity, Space, Line;
• styl a konfigurace: Config, Override, Profile, Extension, Config\Loader, Preset, PresetInfo, vestavěné presety v Presets\ a vestavěná pravidla v Rules\;
• běh a výstup: Runner, Reporter s FileResult a RunResult, vestavěné reportery v Reporters\, Console\Application;
• analýzy a testování: Analyses\PhpDoc, Analyses\NativeType, Testing\RuleTester s Testing\TestFailure;
• výjimky: ConfigurationException, RuleException, ConvergenceException, Console\UsageException;
• z knihovny PhpSyntax všechno, co není označené @internal: Parser, Lexer, Printer, Node, Token, Trivia, uzly, analýzy, Style, Indentation, výčty a ParseException.

Co je označené @internal, se může změnit kdykoli. Rozšíření k tomu nemá důvod sahat, protože všechno, co potřebuje vestavěné pravidlo, je veřejné. Oba seznamy hlídá test, takže třída, která není ani v jednom, shodí testovací sadu, místo aby se veřejným API stala nedopatřením. A protože s novou syntaxí PHP může v minoritní verzi přibýt nový uzel stromu, potřebuje každý match přes třídy uzlů větev default.

Pojmenování

Jméno pravidla má tvar vendor/slug v kebab-case a říká stav, který pravidlo vynucuje, ne krok, který dělá oprava: tedy acme/exception-message-period, ne acme/add-period. Předpona no- znamená konstrukci, která se nesmí objevit vůbec, předpona useless- konstrukci, která je jinde v pořádku, ale na tomhle místě nic nepřidává. Jméno presetu je vendor/jméno-standardu. Je to konvence vestavěného katalogu a rozšíření, které se jí drží, do něj zapadne.