persistent parameters: updated info

dg · dg · commit e6b7002e0f76 · 2023-03-27T02:05:24.000+02:00
diff --git a/application/cs/components.texy b/application/cs/components.texy
@@ -233,30 +233,55 @@ $this->redirect(/* ... */); // a přesměrujeme
 Persistentní parametry
 ======================
 
-Často se stává, že je v komponentách potřeba držet nějaký parametr pro uživatele po celou dobu, kdy se s komponentou pracuje. Může to být například číslo stránky ve stránkování. Takový parametr označíme jako persistentní pomocí anotace `@persistent`.
+Hodnota persistentních parametrů se automaticky přenáší v každém odkaze. Takže jejich hodnota bude stejná i po kliknutí na odkaz, včetně odkazu vytvořeného v jiné komponentě. Můžeme v nich tak snadno přenášet třeba aktuální jazyk nebo číslo stránky. Stačí je jako persistentní označit tímto způsobem:
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class PollControl extends Control
 {
-	/** @persistent */
+	#[Persistent]
 	public int $page = 1;
 }
 ```
 
-Tento parametr bude automaticky přenášen v každém odkazu jako GET parametr, a to až do chvíle, kdy uživatel stránku s touto komponentou opustí.
+Tento parametr se bude automaticky přenášet v každém odkazu jako GET parametr (tedy pokud jeho hodnota bude jiná než výchozi), a to až do chvíle, kdy uživatel stránku s touto komponentou opustí.
 
-.[caution]
-Nikdy slepě nevěřte persistentním parametrům, protože mohou být snadno podvrženy (přepsáním v URL adrese stránky). Ověřte si například, zda je číslo stránky v platném rozsahu.
+Pamatujte, že persistentní property musí být deklarovaná jako public.
 
-V PHP 8 můžete pro označení persistentních parametrů použít také atributy:
+.[note]
+Dříve se místo atributu `#[Persistent]` používala anotace `/** @persistent */`
 
-```php
-use Nette\Application\Attributes\Persistent;
+Při vytváření odkazu lze persistentní parametr uvést a změnit jeho hodnotu:
+
+```latte
+<a n:href="this page: $page + 1">next</a>
+```
+
+Nebo jej lze odstranit tím, že ho vynulujeme (tj. vyresetujeme na výchozí hodnotu):
 
+```latte
+<a n:href="this page: null">reset</a>
+```
+
+Hodnoty do persistentních properties zapisuje metoda `loadState()`. Ta také kontroluje, zda odpovídá datový typ uvedený u property, jinak odpoví chybou 404 a stránka se nezobrazí.
+
+Nikdy slepě nevěřte persistentním parametrům, protože mohou být snadno podvrženy (přepsáním v URL adrese stránky). Ověřte si například, zda je jazyk `$lang` mezi podporovanými. Vhodnou cestou je přepsat metodu `loadState()`:
+
+```php
 class PollControl extends Control
 {
 	#[Persistent]
 	public int $page = 1;
+
+	public function loadState(array $params): void
+	{
+		parent::loadState($params); // zde se nastaví $this->page
+		// následuje vlastní kontrola hodnoty
+		if ($this->page < 1) {
+			$this->error();
+		}
+	}
 }
 ```
 
diff --git a/application/cs/presenters.texy b/application/cs/presenters.texy
@@ -244,37 +244,64 @@ Persistentní parametry se v odkazech **přenášejí automaticky**. To znamená
 Pokud má vaše aplikace více jazykových mutací, tak aktuální jazyk je parameter, který musí být neustále součástí URL. A bylo by neskutečně únavné ho v každém odkazu uvádět. To není s Nette potřeba. Prostě si parametr `lang` označíme jako persistentní tímto způsobem:
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class ProductPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $lang;
 }
 ```
 
-Pokud aktuální hodnota parametru `lang` bude `'en'`, tak URL vytvořené pomocí `link()` nebo `n:href` v šabloně bude obsahovat `lang=en`. Paráda!
+Pokud hodnota `$this->lang` bude `'en'`, tak odkazy vytvořené pomocí `link()` nebo `n:href` budou také obsahovat parameter `lang=en`. Paráda!
 
-Při vytváření odkazu nicméně lze persistentní parametr uvést a tím změnit jeho hodnotu:
+Pamatujte, že persistentní property musí být deklarovaná jako public. Můžete uvést i výchozí hodnotu (která se pak nebude v URL uvádět).
+
+.[note]
+Dříve se místo atributu `#[Persistent]` používala anotace `/** @persistent */`
+
+Při vytváření odkazu lze persistentní parametr uvést a změnit jeho hodnotu:
 
 ```latte
 <a n:href="Product:show $id, lang: cs">detail v češtině</a>
 ```
 
-Nebo jej lze naopak odstranit tím, že ho vynulujeme:
+Nebo jej lze odstranit tím, že ho vynulujeme:
 
 ```latte
 <a n:href="Product:show $id, lang: null">klikni</a>
 ```
 
-Persistentní proměnná musí být deklarovaná jako public. Můžeme uvést i výchozí hodnotu. Bude-li mít parametr hodnotu stejnou jako výchozí, nebude v URL obsažen.
-
-Persistence zohledňuje hierarchii tříd presenterů, tedy parametr definovaný v určitém presenteru nebo traitě je poté automaticky přenášen do každého presenteru z něj dědícího nebo užívajícího stejnou traitu.
+Hodnoty do persistentních properties zapisuje metoda `loadState()`. Ta také kontroluje, zda odpovídá datový typ uvedený u property, jinak odpoví chybou 404 a stránka se nezobrazí.
 
-V PHP 8 můžete pro označení persistentních parametrů použít také atributy:
+Nikdy slepě nevěřte persistentním parametrům, protože mohou být snadno podvrženy (přepsáním v URL adrese stránky). Ověřte si například, zda je jazyk `$lang` mezi podporovanými. Vhodnou cestou je přepsat metodu `loadState()`:
 
 ```php
-use Nette\Application\Attributes\Persistent;
-
 class ProductPresenter extends Nette\Application\UI\Presenter
+{
+	#[Persistent]
+	public string $lang;
+
+	public function loadState(array $params): void
+	{
+		parent::loadState($params); // zde se nastaví $this->lang
+		// následuje vlastní kontrola hodnoty
+		if (!in_array($this->lang, ['en', 'cs'])) {
+			$this->error();
+		}
+	}
+}
+```
+
+Aby se persistentní parametry přenášely mezi více presentery, je potřeba je definovat buď:
+
+- na společném předkovi, od kterého všechny dědí
+- v traitě, kterou všechny používají
+
+Příklad traity s persistentním parametrem:
+
+```php
+trait LangAware
 {
 	#[Persistent]
 	public string $lang;
@@ -302,7 +329,7 @@ S tím, co jsme si dosud v této kapitole ukázali, si nejspíš úplně vystač
 Požadavek a parametry
 ---------------------
 
-Požadavek, který vyřizuje presenter, je objekt [api:Nette\Application\Request] a vrací ho metoda presenteru `getRequest()`. Jeho součástí je pole parametrů a každý z nich patří buď některé z komponent, nebo přímo presenteru (což je vlastně také komponenta, byť speciální). Nette tedy parametry přerozdělí a předá mezi jednotlivé komponenty (a presenter) zavoláním metody `loadState(array $params)`, což dále popisujeme v kapitole [Komponenty|components]. Získat parametry lze metodu `getParameters(): array`, jednotlivě pomocí `getParameter($name)`. Hodnoty parametrů jsou řetězce či pole řetězců, jde v podstatě o surové data získané přímo z URL.
+Požadavek, který vyřizuje presenter, je objekt [api:Nette\Application\Request] a vrací ho metoda presenteru `getRequest()`. Jeho součástí je pole parametrů a každý z nich patří buď některé z komponent, nebo přímo presenteru (což je vlastně také komponenta, byť speciální). Nette tedy parametry přerozdělí a předá mezi jednotlivé komponenty (a presenter) zavoláním metody `loadState(array $params)` (viz také [Persistentní parametry]). Získat parametry lze metodu `getParameters(): array`, jednotlivě pomocí `getParameter($name)`. Hodnoty parametrů jsou řetězce či pole řetězců, jde v podstatě o surové data získané přímo z URL.
 
 
 Uložení a obnovení požadavku
diff --git a/best-practices/bg/restore-request.texy b/best-practices/bg/restore-request.texy
@@ -31,9 +31,11 @@ class AdminPresenter extends Nette\Application\UI\Presenter
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/cs/restore-request.texy b/best-practices/cs/restore-request.texy
@@ -31,9 +31,11 @@ Presenter `SignPresenter` bude krom formuláře pro přihlášení obsahovat i p
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/de/restore-request.texy b/best-practices/de/restore-request.texy
@@ -31,9 +31,11 @@ Der Präsentator `SignPresenter` enthält einen persistenten Parameter `$backlin
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/el/restore-request.texy b/best-practices/el/restore-request.texy
@@ -31,9 +31,11 @@ class AdminPresenter extends Nette\Application\UI\Presenter
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/en/restore-request.texy b/best-practices/en/restore-request.texy
@@ -31,9 +31,11 @@ The `SignPresenter` presenter will contain a persistent `$backlink` parameter to
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/es/restore-request.texy b/best-practices/es/restore-request.texy
@@ -31,9 +31,11 @@ El presentador `SignPresenter` contendrá un parámetro persistente `$backlink`
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/fr/restore-request.texy b/best-practices/fr/restore-request.texy
@@ -31,9 +31,11 @@ Le présentateur `SignPresenter` contiendra un paramètre persistant `$backlink`
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/hu/restore-request.texy b/best-practices/hu/restore-request.texy
@@ -31,9 +31,11 @@ A `SignPresenter` prezenter a bejelentkezési űrlapon kívül tartalmazni fog e
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/it/restore-request.texy b/best-practices/it/restore-request.texy
@@ -31,9 +31,11 @@ Il presentatore `SignPresenter` conterrà un parametro persistente `$backlink` i
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/pl/restore-request.texy b/best-practices/pl/restore-request.texy
@@ -31,9 +31,11 @@ Prezenter `SignPresenter` będzie zawierał, oprócz formularza logowania, trwa
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/pt/restore-request.texy b/best-practices/pt/restore-request.texy
@@ -31,9 +31,11 @@ O apresentador `SignPresenter` conterá um parâmetro persistente `$backlink` no
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/ro/restore-request.texy b/best-practices/ro/restore-request.texy
@@ -31,9 +31,11 @@ Prezentatorul `SignPresenter` va conține un parametru persistent `$backlink` î
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/ru/restore-request.texy b/best-practices/ru/restore-request.texy
@@ -31,9 +31,11 @@ class AdminPresenter extends Nette\Application\UI\Presenter
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/sl/restore-request.texy b/best-practices/sl/restore-request.texy
@@ -31,9 +31,11 @@ Predstavnik `SignPresenter` bo poleg obrazca za prijavo vseboval tudi trajni par
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/tr/restore-request.texy b/best-practices/tr/restore-request.texy
@@ -31,9 +31,11 @@ class AdminPresenter extends Nette\Application\UI\Presenter
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
diff --git a/best-practices/uk/restore-request.texy b/best-practices/uk/restore-request.texy
@@ -31,9 +31,11 @@ class AdminPresenter extends Nette\Application\UI\Presenter
 
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class SignPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
+	#[Persistent]
 	public string $backlink = '';
 
 	protected function createComponentSignInForm()
