Jan Mikoláš
Slovník pojmů
ECS
V kontextu PHP vývoje zde ECS znamená Easy Coding Standard. Zapisuje týmová pravidla do verzované konfigurace, aby formát a mechanické opravy nebyly opakovaným tématem code review.
Stručná definice
Jedna vstupní kontrola pro opakovatelný styl PHP.
ECS sjednocuje pravidla z PHP_CodeSnifferu a PHP-CS-Fixeru a umí je nad určenými cestami spouštět paralelně. Konfigurace v souboru ecs.php určí zdrojové adresáře, sady pravidel, jednotlivé checkery, výjimky a případně formát reportu pro CI.
Nástroj řeší především zápis a mechanicky rozpoznatelné úpravy kódu: mezery, importy, části PHPDoc, zápis polí nebo jiné konvence. Čistý běh ECS sám neprokazuje správné chování, bezpečnost, výkon ani dobrou architekturu.
Jaký problém řeší
Méně ručních připomínek k formátu a více času na význam změny
Tým může předat automatice jednoznačné kontroly, které se jinak opakují u každého pull requestu.
- stejný zápis PHP souborů v editoru vývojáře i na CI runneru
- automatické odstranění nevyužitých importů a oprava vybraného formátu
- postupné zavedení standardu do staršího projektu po bezpečných krocích
- rychlý kontrolní příkaz před commitem a povinná kontrola před mergem
- verzovaná a dohledatelná dohoda o tom, které cesty a pravidla platí
Praktický příklad
Malá konfigurace a kontrolovatelná automatická úprava
Projekt e-shopu nastaví ECS jen pro vlastní zdrojový a testovací kód. Při běžném příkazu nástroj oznámí, že import je nevyužitý nebo že zápis pole neodpovídá zvolenému standardu. Po spuštění s --fix si vývojář prohlédne diff a zahrne pouze pochopitelnou úpravu do commitu.
Ukázka používá aktuální PHP konfiguraci ECSConfig::configure(). Konkrétní sady je vhodné vybírat podle pravidel týmu; zapnutí všech dostupných pravidel bez review není cílem.
PHP
// ecs.php
use Symplify\EasyCodingStandard\Config\ECSConfig;
return ECSConfig::configure()
->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])
->withPreparedSets(psr12: true);
// Před: use App\Unused\LegacyClient;
// Po běhu vendor/bin/ecs --fix zůstane jen používaný import.Jak funguje
Od konfigurace ke kontrole nebo řízené opravě
ECS nemá měnit zdrojový kód skrytě. Běžný postup nejdřív ukáže nález a diff, opravu pak vývojář vědomě kontroluje.
- Cesty ecs.php vybere například src a tests; generované, cache nebo migrační soubory lze odůvodněně vynechat.
- Pravidla a sady Projekt aktivuje malou sadu konkrétních checkerů nebo připravený standard, například PSR-12.
- Kontrola vendor/bin/ecs načte konfiguraci a vypíše porušení či navržené změny pro konkrétní soubor.
- Oprava vendor/bin/ecs --fix provede podporované úpravy; změny se vždy kontrolují v diffu stejně jako jiná editace.
- CI gate CI spouští neopravenou kontrolu a selže čitelně, pokud commit neodpovídá dohodnutému standardu.
Hlavní části
Konfigurace určuje rozsah i míru zásahu
Jednoduchá konfigurace se snáz udržuje a snižuje riziko, že se dva fixery budou navzájem přepisovat.
ECSConfig a cesty
Konfigurace vrací ECSConfig a explicitně vyjmenovává zdrojové cesty. To brání náhodné kontrole vendoru, cache nebo souborů, jejichž zápis nevlastní projekt.
Prepared sets a checkery
Připravené sady seskupují související pravidla. Jednotlivé checkery dávají přesnější kontrolu tam, kde tým potřebuje konkrétní výjimku nebo postupné zavedení.
Check a --fix
Kontrola má být bezpečný výchozí režim. Přepínač --fix mění pracovní strom; je vhodný lokálně nebo ve zvláštním automatizovaném kroku, ne jako neviditelná změna po merge.
Souběžný běh a report
ECS umí práci rozdělit paralelně a vytvořit strojově čitelný report. Zrychlení je užitečné jen tehdy, když je běh stále stabilní a srozumitelný.
Výjimky
withSkip má být úzká a odůvodněná, například pro generovanou migraci. Široká výjimka pro celý modul pouze skrývá nevyřešené rozhodnutí o pravidlech.
Vztah k dalším nástrojům
Styl, refaktoring, analýza a testy odpovídají na jiné otázky
Nástroje se mohou doplňovat v jednom CI běhu, ale nemá smysl vydávat výsledek jednoho za výsledek druhého.
- PHP_CodeSniffer
- PHPCS kontroluje coding standards pomocí sniffs a jeho PHPCBF opravuje část nálezů. ECS nad ním poskytuje společný způsob konfigurace a běhu spolu s pravidly PHP-CS-Fixeru.
- PHP-CS-Fixer
- PHP-CS-Fixer provádí pravidla pro styl a formátování. ECS jej umí zapojit z jedné konfigurace, ale stále jde o samostatný projekt s vlastním ekosystémem pravidel.
- PHPStan
- Statická analýza hledá typové a kontraktní rozpory bez spuštění aplikace. ECS může upravit import, ale neprokáže, že volání nad nullable hodnotou je bezpečné.
- Rector
- Rector se zaměřuje na automatizovaný refaktoring a upgrade kódu. Formátování a refaktoring je vhodné oddělit, aby diff změny zůstal čitelný a účelový.
Výhody a omezení
Konzistentní styl není měřítko celkové kvality
Přínosy
- opakovatelný standard bez závislosti na nastavení konkrétního editoru
- méně mechanických komentářů v code review
- rychlé opravy jednoznačných odchylek před odesláním změny
- společná konfigurace pravidel PHPCS a PHP-CS-Fixeru v jednom nástroji
Omezení a časté chyby
- automaticky opravený kód bez kontroly diffu
- příliš mnoho sad a lokálních výjimek místo srozumitelného standardu
- současný běh více fixerů, které vracejí formát tam a zpět
- záměna čistého stylu za vyřešenou architekturu, testy nebo bezpečnost
Pragmatické použití
Začít malou sadou pravidel a rozšiřovat jen tam, kde to týmu pomáhá.
Nový projekt může začít s několika připravenými pravidly a jednoznačnými cestami. Starší kód je obvykle bezpečnější zavádět po částech: nejdřív pravidla s malým rizikem, jednorázový samostatný formátovací commit a potom kontrola nových změn. Smíšený refaktoring a masové formátování v jednom pull requestu zhoršují review.
ECS není potřeba nasazovat vedle jiného fixeru jen proto, že existuje. Tým by měl zvolit jeden srozumitelný způsob formátování, uvést jej v dokumentaci projektu a zachovat možnost ověřit, co přesně automatická změna udělala.
Na co myslet
Automatizace má být předvídatelná a přiměřená
Pravidlo má mít vlastníka, čitelný přínos a odpovídat kódu, který tým skutečně udržuje.
- držet ecs.php spolu se zdrojovým kódem a spouštět jej stejným příkazem lokálně i v CI
- vybrat jen cesty, za jejichž formát projekt odpovídá
- oddělit velký automatický formátovací commit od business změny
- kontrolovat diff po každém běhu s --fix
- nastavit CI na kontrolu, nikoliv na tichou editaci sdílené větve
- revidovat výjimky a zbytečná pravidla místo jejich nekonečného vrstvení
Časté otázky
Easy Coding Standard v praxi
Je ECS totéž co PHP_CodeSniffer?
Ne. ECS je samostatný nástroj, který z jedné konfigurace spouští pravidla PHP_CodeSnifferu a PHP-CS-Fixeru. PHPCS má vlastní model sniffs, rulesetů a nástroj PHPCBF.
Nahradí ECS PHPStan?
Ne. ECS řeší styl a automatické formátovací úpravy. PHPStan se zaměřuje na statickou analýzu typů, volání a kontraktů. Čistý výstup jednoho nástroje neznamená úspěch druhého.
Je bezpečné používat --fix v CI?
Pro běžnou kontrolu pull requestu je bezpečnější nechat CI selhat a opravu provést v řízeném commitu. Automatický fixer může změnit soubory, proto musí být jeho diff kontrolovatelný a mít jasného vlastníka.
Má smysl ECS pro malý projekt?
Ano, pokud tým opakovaně řeší styl nebo chce jednotný lokální a CI příkaz. Pro jednorázový skript ale rozsáhlá konfigurace může stát více času než přinese užitku.
Jak pracuji s kontrolami kvality
Mechanická pravidla patří do nástroje, technická rozhodnutí do review.
Automatizovaný styl používám jako rychlou zpětnou vazbu vedle testů a statické analýzy. Tím se při review může pozornost soustředit na rizika a význam změny.