Skip to content

Popis Cache třídy

Tento dokument popisuje strukturu a funkcionalitu třídy Cache v core/Cache/Cache.php.

Třída Cache

Statická třída pro správu cache dat. Používá Stash knihovnu s file-based storage pro ukládání cachovaných dat na disk.

Principy

  • Statická API – všechny metody jsou statické, Cache se používá globálně bez instance
  • Singleton pattern – driver a pool se vytvoří jednou a sdílí se mezi voláními
  • File-based storage – data se cachují do /var/cache adresáře
  • Stash kompatibilita – využívá standardní Stash Pool a FileSystem driver

Konstanta - výchozí expirace

Cache::seconds  // 3600 sekund = 1 hodina

Lze použít jako výchozí expiační čas pro cache položky.

Úložiště

  • Cesta: DIR/var/cache
  • Oprávnění souborů: 0660
  • Oprávnění adresářů: 0770

Singleton komponenty

Třída používá singleton pattern pro efektivní správu prostředků:

$driver – FileSystem driver

Statická instance Stash FileSystem driveru. Inicializuje se automaticky při prvním přístupu:

private static ?Stash\Driver\FileSystem $driver = null;

Nastavení:

  • path – fyzické umístění cache (/var/cache)
  • filePermissions – práva na soubory (0660)
  • dirPermissions – práva na adresáře (0770)

$pool – Stash Pool

Statická instance Stash Pool, kterou se pracuje s jednotlivými cache položkami:

private static ?Stash\Pool $pool = null;

Klíčové metody

Ukládání dat

Metoda Popis
saveItem(string $itemName, mixed $data, int $seconds = 3600): void Ulož libovolná data do cache
saveDb(string $key, array $data, int $seconds = 3600): void Ulož výsledky databázového dotazu

Načítání dat

Metoda Popis
getItem(string $itemName): mixed Načti uložená data nebo prázdné pole
getDb(string $key): array Načti cache DB výsledků
file(string $file, string $type = 'yaml'): array Načti a cachuj soubor (YAML)

Správa cache

Metoda Popis
delete(string $item): void Smaž konkrétní cache položku
clear(): void Vymazej všechny cache položky
purge(): void Odstraň staré a expirované položky
checkAndPurge(int $minutes = 60): void Purge jen pokud uplynul časový interval

Struktura cache klíčů

Cache klíče pro soubory

Jsou automaticky generovány z cesty souboru:

// Pokud soubor: /data/www-data/_petrovoCMS/config/settings.yaml
// Cache klíč: config/settings.yaml

Funkce fileItemName() normalizuje cestu odstraněním base directory.

Cache klíče pro databázi

Jsou volně určeny vývojářem:

Cache::saveDb('users_active', $data);
Cache::getDb('users_active');  // Načte data

Expirační časy

Všechny metody pro ukládání podporují vlastní expiační časy v sekundách:

// Výchozí (1 hodina)
Cache::saveItem('key', $data);

// Vlastní čas (5 minut)
Cache::saveItem('key', $data, 300);

// Bez expirace? Stash ji automaticky nastaví

Načítání souborů

Třída obsahuje speciální metodu file() pro cachování obsahu souborů:

/**
 * @param string $file Cesta k souboru
 * @param string $type Typ souboru (momentálně: 'yaml')
 * @return array Parsovaná data
 */
public static function file(string $file, string $type = 'yaml'): array

Podporované typy: - 'yaml' – Parsuje YAML soubory pomocí Symfony\Component\Yaml\Yaml

Vrácená data jsou automaticky cachovaná po dobu Cache::seconds (3600s).

Smart purge – checkAndPurge()

Metoda checkAndPurge() je optimalizovaná pro cyklické spouštění (např. v cronjobs nebo při requestu):

/**
 * Purges cache jen pokud uplynul určitý čas od poslední purge
 * @param int $minutes Čekej (minuty) do další purge
 * @return void
 */
public static function checkAndPurge(int $minutes = 60): void

Jak funguje:

  1. Načte poslední čas purge z cache klíče lastPurge
  2. Porovná s aktuálním časem
  3. Pokud uplynul interval → provede purge()
  4. Aktualizuje lastPurge čas

Vnitřní metody

driver(): Stash\Driver\FileSystem

Vytvoří nebo vrátí singleton FileSystem driver:

private static function driver(): Stash\Driver\FileSystem
  • Nastaví umask(0002) pro správná oprávnění
  • Vrací cachovanou instanci

pool(): Stash\Pool

Vytvoří nebo vrátí singleton Pool:

private static function pool(): Stash\Pool
  • Vytvoří Pool s driver instancí
  • Vrací cachovanou instanci

fileItemName(string $file): string

Normalizuje cestu souboru na cache klíč:

private static function fileItemName(string $file): string

Odstraní base directory ze začátku cesty.

yamlFile(Stash\Interfaces\ItemInterface $item, string $file): mixed

Parsuje YAML soubor a uloží do cache:

private static function yamlFile(
    Stash\Interfaces\ItemInterface $item,
    string $file
): mixed

Chování při chybách

Cache miss (položka neexistuje)

$data = Cache::getItem('nonexistent');
// Vrací: []

Cache miss s DB metodou

$data = Cache::getDb('nonexistent');
// Vrací: []

Nevyskytují se výjimky

Třída je vnitřně bezpečná – nevrací výjimky, pouze prázdná data.

Shrnutí (pro vývojáře)

  • Používej Cache:: pro veškerou práci s cache – je to stabilní a transparentní API
  • Pro libovolná data: Cache::saveItem() a Cache::getItem()
  • Pro DB výsledky: Cache::saveDb() a Cache::getDb()
  • Pro YAML soubory: Cache::file()
  • Výchozí expirační čas je 1 hodina (Cache::seconds)
  • checkAndPurge() je optimalizovaná pro cyklické spouštění bez výkonu
  • Cache miss vrací prázdné pole, ne null – je to bezpečnější
  • Singleton pattern zajišťuje, že se driver a pool vytvoří jen jednou