Nette Documentation Preview

syntax 
Mise à niveau
*************


Mise à niveau vers la version 3.4
=================================

La version minimale de PHP requise est 8.3.

- la méthode `Request::isSameSite()` est obsolète au profit d'`isFrom()`, qui détermine l'origine de la requête à partir des en-têtes `Sec-Fetch-*`. La protection automatique des formulaires et des signaux devient plus précise, et un comportement change : la navigation directe (un favori, une adresse tapée à la main, un lien dans un e-mail) n'est plus considérée comme same-site. Si un signal repose sur des liens d'action dans des e-mails, marquez-le par `#[Requires(sameOrigin: false)]`.
- le cookie `_nss` n'est désormais envoyé qu'aux navigateurs qui n'envoient pas l'en-tête `Sec-Fetch-Site`
- `setCookie()` envoie l'attribut `Max-Age` et impose le drapeau `Secure` pour `SameSite=None` et pour les cookies partitionnés
- l'enum `SameSite` remplace les constantes `IResponse::SameSiteLax` etc., qui sont obsolètes
- l'expiration s'interprète partout de la même façon : un nombre est un nombre relatif de secondes, une chaîne est un intervalle ou une date. Passer un timestamp UNIX absolu est obsolète, et un cookie de session est représenté par `null` au lieu de `0`.
- la méthode obsolète `Request::getRemoteHost()` renvoie `null`
- la classe `Nette\Http\UserStorage`, obsolète depuis longtemps, a été supprimée

Toute l'histoire du passage aux en-têtes `Sec-Fetch-*` est racontée dans l'article [Quarter Century of CSRF |https://blog.nette.org/en/quarter-century-of-csrf].


Mise à niveau vers la version 3.2
=================================

- les identifiants de l'authentification HTTP Basic ne font plus partie de l'objet `Url`, si bien que `$url->getUser()` et `$url->getPassword()` renvoient une chaîne vide. Lisez-les à l'aide de la nouvelle méthode `$request->getBasicCredentials()`.

Les raisons de ce changement sont expliquées dans l'article [Nette Http 3.2: change access to credentials |https://blog.nette.org/en/nette-http-3-2-change-access-to-credentials].


Mise à niveau vers la version 3.1
=================================

- les cookies sont envoyés avec le drapeau `sameSite: Lax`
- `cookieSecure` vaut désormais 'auto' par défaut
- l'option `session.cookieSecure` est obsolète ; c'est `http.cookieSecure` qui est utilisée à la place
- le cookie `nette-samesite` a été renommé en `_nss`
- `Nette\Http\Request::getFile()` accepte un tableau de clés et renvoie `FileUpload|null`
- `Nette\Http\Session::getCookieParameters()` est obsolète
- `Nette\Http\FileUpload::getName()` a été renommée en `getUntrustedName()`
- `Nette\Http\Url` : `getBasePath()`, `getBaseUrl()` et `getRelativeUrl()` sont obsolètes (ces méthodes font partie d'`UrlScript`)
- `Nette\Http\Response::$cookieHttpOnly` est obsolète
- `Nette\Http\FileUpload::getImageSize()` renvoie la paire `[largeur, hauteur]`
- avec `autoStart: smart` (la valeur par défaut), la session n'est plus démarrée juste après le lancement de l'application au seul motif que le navigateur a envoyé un cookie de session ; elle démarre à la première lecture ou écriture. Les valeurs `always` et `never` ont été ajoutées.
- lorsque le navigateur envoie un ID de session pour lequel aucune session n'existe, Nette supprime le cookie au lieu de créer une nouvelle session
- pour accéder aux sections de session, préférez les méthodes `set()`, `get()` et `remove()` ; contrairement à l'accès par propriété, elles distinguent correctement la lecture de l'écriture et ne démarrent pas la session inutilement
- les valeurs par défaut de `cookiePath` et `cookieDomain` peuvent être définies dans la configuration

Le comportement des sessions est décrit en détail dans l'article [Nette Http 3.1: much smarter sessions |https://blog.nette.org/en/nette-http-3-1-much-smarter-sessions].


Mise à niveau vers la version 3.0
=================================

- l'objet `Nette\Http\UrlScript` (renvoyé par exemple par `Nette\Http\Request::getUrl()`) est désormais immuable
- dans `new Nette\Http\Url('abcd')`, `abcd` représente le chemin, pas le domaine ; depuis la 3.0, `(new Nette\Http\Url('abcd'))->setScheme('http')` génère correctement `http:abcd` au lieu du précédent `http://abcd`

Mise à niveau

Mise à niveau vers la version 3.4

La version minimale de PHP requise est 8.3.

  • la méthode Request::isSameSite() est obsolète au profit d'isFrom(), qui détermine l'origine de la requête à partir des en-têtes Sec-Fetch-*. La protection automatique des formulaires et des signaux devient plus précise, et un comportement change : la navigation directe (un favori, une adresse tapée à la main, un lien dans un e-mail) n'est plus considérée comme same-site. Si un signal repose sur des liens d'action dans des e-mails, marquez-le par #[Requires(sameOrigin: false)].
  • le cookie _nss n'est désormais envoyé qu'aux navigateurs qui n'envoient pas l'en-tête Sec-Fetch-Site
  • setCookie() envoie l'attribut Max-Age et impose le drapeau Secure pour SameSite=None et pour les cookies partitionnés
  • l'enum SameSite remplace les constantes IResponse::SameSiteLax etc., qui sont obsolètes
  • l'expiration s'interprète partout de la même façon : un nombre est un nombre relatif de secondes, une chaîne est un intervalle ou une date. Passer un timestamp UNIX absolu est obsolète, et un cookie de session est représenté par null au lieu de 0.
  • la méthode obsolète Request::getRemoteHost() renvoie null
  • la classe Nette\Http\UserStorage, obsolète depuis longtemps, a été supprimée

Toute l'histoire du passage aux en-têtes Sec-Fetch-* est racontée dans l'article Quarter Century of CSRF.

Mise à niveau vers la version 3.2

  • les identifiants de l'authentification HTTP Basic ne font plus partie de l'objet Url, si bien que $url->getUser() et $url->getPassword() renvoient une chaîne vide. Lisez-les à l'aide de la nouvelle méthode $request->getBasicCredentials().

Les raisons de ce changement sont expliquées dans l'article Nette Http 3.2: change access to credentials.

Mise à niveau vers la version 3.1

  • les cookies sont envoyés avec le drapeau sameSite: Lax
  • cookieSecure vaut désormais ‚auto‘ par défaut
  • l'option session.cookieSecure est obsolète ; c'est http.cookieSecure qui est utilisée à la place
  • le cookie nette-samesite a été renommé en _nss
  • Nette\Http\Request::getFile() accepte un tableau de clés et renvoie FileUpload|null
  • Nette\Http\Session::getCookieParameters() est obsolète
  • Nette\Http\FileUpload::getName() a été renommée en getUntrustedName()
  • Nette\Http\Url : getBasePath(), getBaseUrl() et getRelativeUrl() sont obsolètes (ces méthodes font partie d'UrlScript)
  • Nette\Http\Response::$cookieHttpOnly est obsolète
  • Nette\Http\FileUpload::getImageSize() renvoie la paire [largeur, hauteur]
  • avec autoStart: smart (la valeur par défaut), la session n'est plus démarrée juste après le lancement de l'application au seul motif que le navigateur a envoyé un cookie de session ; elle démarre à la première lecture ou écriture. Les valeurs always et never ont été ajoutées.
  • lorsque le navigateur envoie un ID de session pour lequel aucune session n'existe, Nette supprime le cookie au lieu de créer une nouvelle session
  • pour accéder aux sections de session, préférez les méthodes set(), get() et remove() ; contrairement à l'accès par propriété, elles distinguent correctement la lecture de l'écriture et ne démarrent pas la session inutilement
  • les valeurs par défaut de cookiePath et cookieDomain peuvent être définies dans la configuration

Le comportement des sessions est décrit en détail dans l'article Nette Http 3.1: much smarter sessions.

Mise à niveau vers la version 3.0

  • l'objet Nette\Http\UrlScript (renvoyé par exemple par Nette\Http\Request::getUrl()) est désormais immuable
  • dans new Nette\Http\Url('abcd'), abcd représente le chemin, pas le domaine ; depuis la 3.0, (new Nette\Http\Url('abcd'))->setScheme('http') génère correctement http:abcd au lieu du précédent http://abcd