Reference - Asset Třída

Třída Core\Asset\Asset zajišťuje integraci Vite build systému s PHP.

Princip fungování

Asset třída automaticky:

Dev režim: Detekuje běžící Vite dev server → vrací pole s URL přímo ze serveru
Production: Čte manifest.json → vrací pole URL pro optimalizované JS, CSS a preload tagy

Manifest je generován Vite při buildu a obsahuje mapy vstupních bodů na výstupní soubory.

Veřejné metody

viteAssets() – Hlavní metoda

public static function viteAssets(string $server, string $entry): array

Vrátí pole URL pro daný vstupní bod — bez HTML, pouze data. Renderování zajišťuje šablona.

Parametry:

Parametr	Typ	Popis
`$server`	`string`	Dev server URL (např. `http://localhost:5173`)
`$entry`	`string`	Vstupní bod (např. `admin.js`, `website.js`)

Návratová hodnota:

array{
    js:      string[],   // URL JS souborů
    preload: string[],   // URL pro modulepreload (dynamické importy)
    css:     string[],   // URL CSS souborů
}

Dev režim – vráceno:

[
    'js'      => ['http://localhost:5173/admin.js'],
    'preload' => [],
    'css'     => [],
]

Production – vráceno:

[
    'js'      => ['/ADMIN/js/admin.js?1705234567', '/ADMIN/js/main.js?1705234568'],
    'preload' => [],
    'css'     => ['/ADMIN/css/admin.css?1705234567', '/ADMIN/css/main.css?1705234568'],
]

Výsledek se předá šabloně přes $tpl->data('assets', $assets) a renderuje přes {loop}.

isViteDevServerRunning() – Detekce dev serveru

public static function isViteDevServerRunning(string $server): bool

Kontroluje zda Vite dev server běží na daném portu.

Parametry:

Parametr	Typ	Popis
`$server`	`string`	Dev server URL (se schématem http://)

Návratová hodnota:

true pokud je server dostupný
false v production módu nebo pokud server neodpovídá

Techniky:

Používá fsockopen() pro low-level testování
Timeout 0.2 sekundy
Výsledek cachuje v $viteRunningCache (jeden fsockopen per request)
V Docker prostředí používá host.docker.internal místo localhost

Privátní metody

entryAssets() – Rekurzivní řešení závislostí

private static function entryAssets(string $entry, array $manifest): array

Rekurzivně projde vstupní bod a všechny jeho závislosti z manifestu.

Logika:

Najde vstupní bod v manifestu
Zařadí soubor do js nebo css pole (podle přípony)
Dynamické importy → preload pole
Rekurzivně zpracuje imports a dynamicImports
Přidá CSS soubory ze záznamu
Deduplikuje výsledky (array_unique)

Výsledek:

[
    'js'      => ['/ADMIN/js/admin.js?v1', '/ADMIN/js/main.js?v2'],
    'preload' => [],
    'css'     => ['/ADMIN/css/admin.css?v1', '/ADMIN/css/main.css?v2'],
]

getAssetVersion() – Verzionování

private static function getAssetVersion(string $path): string

Vrátí verzi assetu pro cache-busting.

Logika:

Pokud soubor existuje: použije filemtime() (čas změny)
Pokud neexistuje: generuje random číslo (1000-9999)

getManifest() – Načtení manifestu

private static function getManifest(): array

Načte a dekóduje manifest.json ze správného umístění.

Cesty:

Frontend: /public/.vite/manifest.json
Admin: /public/ADMIN/.vite/manifest.json

Návratová hodnota:

Dekódované pole z JSON
Prázdné pole pokud soubor neexistuje nebo není čitelný

Manifest.json struktura

Manifest je generován Vite během buildu a obsahuje mapu zdrojů na výstupní soubory.

Příklad manifestu

{
  "admin.js": {
    "file": "js/admin.js",
    "name": "admin",
    "src": "admin.js",
    "isEntry": true,
    "imports": [
      "_main.js"
    ],
    "css": [
      "css/admin.css"
    ]
  },
  "_main.js": {
    "file": "js/main.js",
    "name": "main",
    "css": [
      "css/main.css"
    ]
  }
}

Struktura záznamu

Klíč	Popis
`file`	Výstupní soubor po Vite buildu
`src`	Zdrojový vstupní bod (vstup do Vite)
`isEntry`	True = hlavní vstupní bod
`imports`	Závislosti (sdílené moduly)
`dynamicImports`	Dynamicky importované moduly
`css`	CSS soubory závislé na JS

Dev vs Production režim

Development

Vite dev server běží → Asset detekuje → vrací:
['js' => ['http://localhost:5173/admin.js'], 'preload' => [], 'css' => []]

Vlastnosti:

Přímý přístup k dev serveru
Hot reload (změna souboru = automatický refresh)
Bez optimalizace, bez minifikace
Rychlejší vývoj

Production

Vite build dokončen → Asset čte manifest → vrací:
['js' => ['/ADMIN/js/admin.js?1705234567'], 'css' => ['/ADMIN/css/admin.css?1705234567'], ...]

Vlastnosti:

Načítá z manifest.json
Optimalizované bundly (tree-shake, minify)
Verzionování pro cache-busting
Deduplikované CSS/JS

Konfigurace

Vlastnosti se čtou z CONFIG:

# /config/development.yaml
vite_admin: http://localhost:5173   # Admin dev server
vite_website: http://localhost:5174  # Frontend dev server

Používá se v tazích:

// app/tags/ADMIN/assets/admin.php
$assets = Asset::viteAssets(CONFIG['vite_admin'], 'admin.js');

// app/tags/assets/website.php
$assets = Asset::viteAssets(CONFIG['vite_website'], 'website.js');

Konstanta SUBDIR

V projektu s podadresářem (starší projekty) se nastavuje:

private const string SUBDIR = '';  // výchozí - root
// nebo
private const string SUBDIR = '/content';  // v /content/*

Ovlivňuje vygenerované cesty:

// s SUBDIR = ''
/ADMIN/js/admin.js

// s SUBDIR = '/content'
/content/ADMIN/js/admin.js

Bezpečnost

XSS prevention: URL se negenerují z uživatelských dat
Path traversal: Cesty se berou pouze z manifestu
Dev server detekce: Měkký fallback (fsockopen timeout 0.2s)

Chování v edge cases

Případ	Chování
Dev server běží + manifest existuje	Priorita dev serveru
Dev server neběží + manifest existuje	Čte manifest
Dev server neběží + manifest neexistuje	Vrátí prázdná pole
Neexistující vstupní bod	Vrátí prázdná pole
Docker prostředí	Detekuje `host.docker.internal`

Integrace s Tracy

Debugger panel v /core/Tracy/VitePanel.php zobrazuje:

Stav Vite dev serveru (zeleně/šedě)
Aktuální port (5173/5174)
Dev/Production režim