Přehled nastavení

Každý klíč Settings.json s typem, výchozí hodnotou, účinkem a příkladem, přepisy z prostředí, kompletní produkční konfigurace a měřicí ID Google Analytics.

Kde nastavení leží

Veškerá konfigurace je jeden objekt JSON v src/Config/Settings.json. Soubor se nekomituje: bin/wbe install ho vytvoří ze src/Config/settings.json.default. Framework ho čte jednou za požadavek, chybějící klíč má níže uvedenou výchozí hodnotu a chybná hodnota v http, analytics nebo v pravidlech cache stránek vyvolá chybu, nikoli tiché ignorování. Po změně souboru vyprázdněte cache (POST /api/v2/cache/flush, integrační klíč s oprávněním cache:write) a při vypnutém renderer.compileCheck i adresář zkompilovaných šablon. Výsledek ověříte příkazem vendor/bin/wbengine.php config:check --config=src/Config/Settings.json --root=src.

Tajné hodnoty mohou místo souboru pocházet z prostředí: WBENGINE_RECAPTCHA_SECRET, WBENGINE_DEBUG a WBENGINE_IMAGE_DIR. Nastavená a neprázdná proměnná prostředí má přednost před souborem.

Obecné

Klíč	Typ, výchozí hodnota	Účinek
`timeZone`	řetězec, `Europe/Prague`	Časové pásmo PHP aplikace. Povinné.
`debug`	bool, `false`	Zobrazí ladicí lištu a podrobné chyby. V produkci nikdy `true`. Přepíše ho `WBENGINE_DEBUG`.

Renderer

Klíč	Typ, výchozí hodnota	Účinek
`renderer.adapterName`	řetězec, `NativeRenderer`	`NativeRenderer` nebo volitelný `SmartyRenderer`.
`renderer.autoEscape`	bool, `true`	Escapuje výstup proměnných v šablonách. `false` je jen pomůcka při migraci starých šablon.
`renderer.templatesDir`	řetězec, `/View/`	Adresář šablon pod `src/`.
`renderer.compiledDir`	řetězec, `Compiled/`	Zkompilované šablony, uživatel PHP do něj musí smět zapisovat.
`renderer.configDir`	řetězec, `/Config/`	Adresář konfigurace šablon.
`renderer.compileCheck`	bool, `true`	Při každém požadavku kontroluje, zda se šablona změnila. V produkci nastavte `false` a při nasazení vyprázdněte adresář zkompilovaných šablon.

Databáze

dbAdapterDefinition je objekt: adapterName (Mysqli), hostname, port, database, username, password, charset. Výchozí soubor míří na hostitele Dockeru db s vývojovými údaji; všechny je vyměňte. Na nové instalaci použijte utf8mb4 jako charset. Pro heslo k databázi není přepsání z prostředí, proto soubor chraňte (chmod 640).

Tajné hodnoty

Klíč	Typ, výchozí hodnota	Účinek
`recaptcha.secretKey`	řetězec, prázdný	Tajný klíč captcha u přihlašovacího formuláře. Prázdný klíč znamená, že kontrola captcha selže (fail closed). Přepíše ho `WBENGINE_RECAPTCHA_SECRET`. Při `recaptcha.enabled: true` ho příkaz `doctor` vyžaduje.

Proxy a HTTPS

Klíč	Typ, výchozí hodnota	Účinek
`http.trustedProxies`	pole, `[]`	Přesné adresy nebo rozsahy CIDR reverzních proxy, jejichž předávací hlavičky se berou vážně. Prázdné pole znamená, že se všechny hlavičky ignorují.
`http.forwardedHeaders`	pole, `[]`	Povolené hlavičky: `x-forwarded-for` (adresa klienta) a `x-forwarded-proto` (původní schéma). Jiné hodnoty se odmítnou.

Za hostitelským Nginxem nebo load balancerem nastavte obojí, jinak web považuje každého návštěvníka za adresu proxy a komunikaci za prosté HTTP: cookies relace nejsou zabezpečená, limity pokusů se sdílejí a /integrations/ odmítne vydat klíč. Proxy musí přepsat X-Forwarded-Proto a sestavit X-Forwarded-For ze skutečného spojení.

"http": { "trustedProxies": ["172.18.0.1/32"], "forwardedHeaders": ["x-forwarded-for", "x-forwarded-proto"] }

Jazyky

Klíč	Typ, výchozí hodnota	Účinek
`i18n.enabled`	bool, `false` (kostra nastavuje `true`)	Zapne jazyky.
`i18n.default`	řetězec, `en`	Jazyk adres bez předpony a záloha pro chybějící překlady.
`i18n.locales`	pole, `["en"]`	Nabízené jazyky, například `["en", "cs"]`. Výchozí jazyk je vždy zahrnut.
`i18n.detect`	pole, `["url", "cookie", "header"]`	Pořadí detekce. Kostra používá `["url"]`, takže adresy bez předpony jsou vždy anglicky. Přidáním `cookie` nebo `header` necháte rozhodovat uloženou volbu nebo jazyk prohlížeče.
`i18n.urlPrefix`	bool, `true`	Používá předpony `/cs/...` pro jazyky jiné než výchozí.
`i18n.prefixDefault`	bool, `false`	Předponu dostane i výchozí jazyk (`/en/...`).
`i18n.cookie`	řetězec, `wb_locale`	Název cookie s volbou jazyka (písmena, číslice, podtržítko).
`i18n.cookieDays`	celé číslo, `365`	Platnost této cookie ve dnech.
`i18n.dir`	řetězec, `/Locale/`	Adresář katalogů pod `src/`, soubory `en.php`, `cs.php`.
`i18n.baseUrl`	řetězec, prázdný	Veřejná adresa, například `https://example.com`. Používá se pro absolutní odkazy `hreflang` místo hlavičky `Host`. V produkci ji nastavte.

Cache

Klíč	Typ, výchozí hodnota	Účinek
`cache.enabled`	bool, `false` (kostra nastavuje `true`)	Datová cache a cache fragmentů.
`cache.driver`	řetězec, `file`	`file` nebo `apcu`. `apcu` vyžaduje rozšíření a k vyprázdnění restart PHP-FPM.
`cache.ttl`	sekundy, `300`	Platnost záznamů datové cache.
`cache.dir`	řetězec, dočasný adresář	Adresář ovladače `file`. Výchozí je podadresář systémového dočasného adresáře, který může při `PrivateTmp` zmizet: nastavte absolutní cestu.
`cache.pages.enabled`	bool, `false`	Cache celých stránek pro anonymní požadavky.
`cache.pages.ttl`	sekundy, `60`	Platnost stránek v cache.
`cache.pages.allowPaths`	pole, vynecháno	Přesné kanonické cesty povolené v cache stránek. Vynechané povolí ostatní vhodné cesty, prázdné `[]` cache stránek vypne.
`cache.pages.denyPaths`	pole, vynecháno	Cesty, které se nikdy neukládají. Má přednost před `allowPaths`.

Cesty se porovnávají bez ohledu na velikost písmen a koncové lomítko, neplatná pravidla selžou bezpečně (fail closed). Soukromé odpovědi, odpovědi s Set-Cookie a osobní odpovědi se neukládají nikdy, ať pravidlo říká cokoli. Příklad: "allowPaths": ["/", "/docs/", "/blog/"], "denyPaths": ["/profile/", "/login/"]. Rozbitá cache web neshodí: vypne se a zaloguje.

Limity pokusů a počítadla

Klíč	Typ, výchozí hodnota	Účinek
`rateLimit.login.enabled`	bool, `true`	Omezuje neúspěšná přihlášení.
`rateLimit.login.maxAttempts`	celé číslo, `5`	Pokusy na adresu klienta a účet dohromady.
`rateLimit.login.ipMaxAttempts`	celé číslo, `20`	Pokusy na adresu klienta napříč všemi účty.
`rateLimit.login.accountMaxAttempts`	celé číslo, `25`	Pokusy na účet ze všech adres (rozprostřené hádání).
`rateLimit.login.window`	sekundy, `900`	Délka počítacího okna.
`rateLimit.login.dir`	řetězec, dočasný adresář	Soubory počítadel. Nastavte absolutní zapisovatelnou cestu.
`counters.views.enabled`	bool, `false`	Dávkuje počítadlo zobrazení článků místo jednoho zápisu do databáze na zobrazení.
`counters.views.hits`	celé číslo, `50`	Počet zobrazení v dávce.
`counters.views.seconds`	celé číslo, `60`	Nejdelší zpoždění dávky.
`counters.views.dir`	řetězec, dočasný adresář	Soubory počítadel. Nastavte absolutní zapisovatelnou cestu.

Limit pokusů používá adresu klienta, proto za proxy funguje správně jen při správném http.trustedProxies.

Vlastní analytika

Klíč	Typ, výchozí hodnota	Účinek
`analytics.enabled`	bool, `false`	Sbírá denní souhrny bez identity (žádné cookies, žádné adresy). Vyžaduje tabulky analytiky (viz stránka Nasazení).
`analytics.timezone`	řetězec, `UTC`	Časové pásmo IANA, ve kterém se dny dělí. Neplatná hodnota vyvolá chybu.
`analytics.retentionDays`	celé číslo, `62`	Jak dlouho se denní řádky drží, 31 až 365. Spouštějte `analytics:prune` z cronu denně.

Jde o měření vlastním nástrojem šetrné k soukromí. Je nezávislé na Google Analytics níže: můžete provozovat jedno, obojí i žádné. Rozumná politika pro většinu webů: vlastní analytika zapnutá s retentionDays 62 (nenastavuje cookies a neukládá adresy), Google Analytics vypnuté, dokud provozovatel nemá právní důvod a proces souhlasu. Právní stránku posuďte pro vlastní web.

Google Analytics

Klíč	Typ, výchozí hodnota	Účinek
`googleAnalytics.measurementId`	řetězec, prázdný	Měřicí ID, například `G-XXXXXXXXXX`. Prázdné, chybějící nebo chybně zapsané ID vše vypne.

Kostra značku Google sama nenačítá. Po nastavení ID layout zobrazí lištu s cookies i odkaz „Nastavení cookies“ v patičce a public/cookie-consent.js načte gtag.js až poté, co návštěvník stiskne „Povolit analytiku“. Volba se pamatuje v prohlížeči (localStorage), „Odmítnout“ odstraní analytické cookies a bez souhlasu se značka nenačte nikdy. Při prázdném klíči layout neobsahuje lištu, tlačítko ani skript. Text lišty je v katalozích jazyků (cookies.*); upravte ho podle svých zásad. Stránka uložená v cache před nastavením ID si staré značení drží, dokud cache nevyprázdníte.

"googleAnalytics": { "measurementId": "G-XXXXXXXXXX" }

Audit a záznam změn

Klíč	Typ, výchozí hodnota	Účinek
`audit.retentionDays`	celé číslo, `365`	Jak dlouho se drží řádky `cms_api_audit` a `cms_api_changes`, 30 až 3650. Neplatná hodnota vyvolá chybu.
`audit.revisionRetentionDays`	celé číslo, `365`	Jak dlouho se drží `cms_api_revisions` (historie konceptů článků), 30 až 3650.

Nic se nemaže automaticky: spouštějte audit:prune z cronu (--dry-run jen počítá, --days=N přepíše oba klíče). Nejnovější změna každého zdroje a každá revize, kterou koncept ještě používá, se vždy ponechá. Při zapnutém API v2 tabulky vyžadují sloupce záznamu změn (sh bin/update-database.sh DATABASE). Co se zaznamenává, popisuje Logování a audit.

Vyhledávače

Klíč	Typ, výchozí hodnota	Účinek
`seo.allowIndexing`	pravda/nepravda, `true`	`false` zavře celý web pro roboty, například u testovací kopie: `robots.txt` uvede `Disallow: /` a `/sitemap.xml` vrací 404.
`seo.disallow`	seznam cest, prázdný	Cesty uvedené v `robots.txt`, každá začíná `/`.
`seo.sitemapExclude`	seznam adres stránek, prázdný	Stránky vynechané z `/sitemap.xml`, každá adresa začíná `/`.

/robots.txt a /sitemap.xml se generují pro každý požadavek a registrují se v public/index.php. Sitemapa uvádí viditelné veřejné stránky jednou pro každý jazyk, s odkazy na ostatní jazyky, a vynechává stránky, které vyžadují přihlášení, i stránky se skrytým článkem. Jazyk se uvede jen tehdy, když má stránka překlad. Stránky, které berou v adrese parametry, se uvádějí jen vlastní adresou.

Obrázky a API

Klíč	Typ, výchozí hodnota	Účinek
`apiV2.enabled`	bool, `false` (kostra nastavuje `true`)	Zapne serverové API v2, které používá centrální Admin. Vyžaduje HTTPS a tabulky API.
`apiV2.imageDirectory`	řetězec, nenastaveno	Absolutní adresář pro obrázky nahrané přes API v2. Nenastaveno znamená, že nahrávání obrázků není dostupné. Přepíše ho `WBENGINE_IMAGE_DIR`. Držte ho mimo `public/` a zapisovatelný pro PHP. Soubory PNG, JPEG nebo WebP do 512 KiB.

Produkční příklad

Kompletní soubor pro web za hostitelským Nginxem, všechna tajemství v prostředí (WBENGINE_RECAPTCHA_SECRET), takže zástupné hodnoty níže nejsou skutečné klíče:

{
  "timeZone": "Europe/Prague",
  "debug": false,
  "apiV2": {
    "enabled": true,
    "imageDirectory": "/var/lib/wbengine/images"
  },
  "renderer": {
    "adapterName": "NativeRenderer",
    "autoEscape": true,
    "templatesDir": "/View/",
    "compiledDir": "Compiled/",
    "configDir": "/Config/",
    "compileCheck": false
  },
  "dbAdapterDefinition": {
    "adapterName": "Mysqli",
    "hostname": "127.0.0.1",
    "port": "3306",
    "database": "wbengine_skeleton_app",
    "username": "wbengine",
    "password": "SET-A-LONG-RANDOM-PASSWORD",
    "charset": "utf8mb4"
  },
  "recaptcha": { "secretKey": "" },
  "http": {
    "trustedProxies": ["127.0.0.1"],
    "forwardedHeaders": ["x-forwarded-for", "x-forwarded-proto"]
  },
  "cache": {
    "enabled": true,
    "driver": "file",
    "ttl": 300,
    "dir": "/var/cache/wbengine",
    "pages": {
      "enabled": true,
      "ttl": 60,
      "denyPaths": ["/login/", "/profile/", "/integrations/"]
    }
  },
  "i18n": {
    "enabled": true,
    "default": "en",
    "locales": ["en", "cs"],
    "detect": ["url"],
    "baseUrl": "https://example.com"
  },
  "rateLimit": { "login": { "dir": "/var/lib/wbengine/ratelimit" } },
  "counters": { "views": { "enabled": true, "dir": "/var/lib/wbengine/counters" } },
  "analytics": { "enabled": true, "timezone": "Europe/Prague", "retentionDays": 62 },
  "audit": { "retentionDays": 365, "revisionRetentionDays": 365 },
  "googleAnalytics": { "measurementId": "" }
}

Kde co nasadit (oprávnění adresářů, proxy, cron) popisuje Nasazení, chování cache stránka Cache.