Návrh doménové služby: Rozbor třídy AnatomyInspectorService

Návrh doménové služby v praxi

Servisní vrstva (Service Layer) představuje srdce doménové logiky aplikace. Dobře navržená servisní třída splňuje tyto vlastnosti:

1. Je bezstavová (Stateless): Nedrží vnitřní stav mezi jednotlivými voláními. Výsledek metody závisí výhradně na předaných argumentech.
2. Je silně typovaná: Všechny parametry i návratové hodnoty mají striktní PHP 8.4 typy.
3. Vrací neměnná DTO: Místo surových asociativních polí (array) vrací strukturované objekty final readonly class.
4. Je zabezpečená proti zneužití: Důsledně validuje hraniční podmínky a brání bezpečnostním rizikům.

Případová studie: AnatomyInspectorService

V naší aplikaci slouží služba AnatomyInspectorService k bezpečnému zkoumání zdrojových souborů projektu. Umožňuje studentům prohlížet reálný kód přímo v prohlížeči.

Práce se souborovým systémem na základě uživatelského vstupu však skrývá obrovské bezpečnostní riziko: Path Traversal útok (např. předání ../../../../etc/passwd nebo .env s produkčními hesly).

Třívrstvá bezpečnostní ochrana v isAllowedPath

Podívejme se, jak AnatomyInspectorService řeší bezpečnost na třech nezávislých úrovních:

private const array ALLOWED_PREFIXES = [
    'app/',
    'bootstrap/',
    'config/',
    'database/',
    'docker/',
    'public/index.php',
    'resources/',
    'routes/',
    'tests/',
    'composer.json',
    'package.json',
    'vite.config.js',
    'compose.yaml',
    'compose.prod.yaml',
    'deploy.sh',
    'AGENTS.md',
    '.agents/memory/curriculum_registry.json',
];

private const array FORBIDDEN_FRAGMENTS = [
    '.env',
    '.git',
    'vendor/',
    'node_modules/',
    'storage/',
    '..',
];

1. Černá listina fragmentů (Blacklist): Zakazuje nebezpečné řetězce jako .. (posun v adresářové struktuře), .env (tajné klíče), .git a adresáře třetích stran.
2. Bílá listina povolených cest (Whitelist): Soubor musí začínat jedním ze schválených prefixů projektu.
3. Kanonizace cesty pomocí realpath(): Funkce realpath() vyřeší všechny symbolické odkazy i relativní cesty a převede je na absolutní kanonickou cestu. Služba následně ověří, zda tato cesta začíná kořenovým adresářem projektu:

$basePath = realpath(base_path());
$fullPath = base_path($cleanPath);
$realPath = realpath($fullPath);

if ($realPath === false || ! is_file($realPath)) {
    return false;
}

$baseWithSlash = rtrim($basePath, DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR;

return str_starts_with($realPath, $baseWithSlash);

Proč vracet DTO místo asociativního pole?

Místo vracení surového pole jako ['content' => '...', 'lines' => 120] vrací metoda inspectFile instanci AnatomyFileNodeData:

final readonly class AnatomyFileNodeData
{
    public function __construct(
        public string $path,
        public string $category,
        public string $description,
        public bool $exists,
        public int $lineCount,
        public int $sizeBytes,
        public string $content,
    ) {}
}

Výhody tohoto přístupu:

• Neměnnost: Klíčové slovo readonly garantuje, že vlastnosti nelze po vytvoření přepsat.
• Typová jistota: PHPStan / Larastan i IDE okamžitě odhalí překlepy v názvech vlastností na úrovni statické analýzy.
• Autodokumentace: Každý vývojář přesně vidí, jaká data uzel souboru nese.