IRequest, IResponse: added typehints, unification (BC break)

Author: dg

phpstan.neon

@@ -9,12 +9,6 @@ parameters:
 		- phtml
 
 	ignoreErrors:
-		-   # IResponse::setCookie() interface does not yet declare $sameSite parameter, Response::setCookie() does
-			message: '#^Unknown parameter \$sameSite in call to method Nette\\Http\\IResponse\:\:setCookie\(\)\.$#'
-			identifier: argument.unknown
-			count: 1
-			path: src/Http/Helpers.php
-
 		-   # runtime validation of HTTP header value coming from untrusted client input
 			message: '#^Right side of && is always true\.$#'
 			identifier: booleanAnd.rightAlwaysTrue
@@ -33,12 +27,6 @@ parameters:
 			count: 1
 			path: src/Http/RequestFactory.php
 
-		-   # IResponse::setCookie() interface does not yet declare $sameSite parameter, see Helpers.php
-			message: '#^Method Nette\\Http\\IResponse\:\:setCookie\(\) invoked with 8 parameters, 3\-7 required\.$#'
-			identifier: arguments.count
-			count: 1
-			path: src/Http/Session.php
-
 		-   # session_get_cookie_params() declares 'samesite' key but it may legitimately be missing on older configurations
 			message: '#^Offset ''samesite'' on array\{lifetime\: int\<0, max\>, path\: non\-falsy\-string, domain\: string, secure\: bool, httponly\: bool, samesite\: ''Lax''\|''lax''\|''None''\|''none''\|''Strict''\|''strict''\} on left side of \?\? always exists and is not nullable\.$#'
 			identifier: nullCoalesce.offset

src/Http/IRequest.php

@@ -55,22 +55,19 @@ function getUrl(): UrlScript;
 
 	/**
 	 * Returns a URL query parameter, or all parameters as an array if no key is given.
-	 * @return mixed
 	 */
-	function getQuery(?string $key = null);
+	function getQuery(?string $key = null): mixed;
 
 	/**
 	 * Returns a POST parameter, or all POST parameters as an array if no key is given.
-	 * @return mixed
 	 */
-	function getPost(?string $key = null);
+	function getPost(?string $key = null): mixed;
 
 	/**
 	 * Returns the uploaded file for the given key, or null if not present.
 	 * Accepts a string key or an array of keys for nested file structures (e.g. ['form', 'avatar']).
-	 * @return ?FileUpload
 	 */
-	function getFile(string $key);
+	function getFile(string $key): ?FileUpload;
 
 	/**
 	 * Returns the tree of uploaded files, with each leaf being a FileUpload instance.
@@ -80,9 +77,8 @@ function getFiles(): array;
 
 	/**
 	 * Returns a cookie value, or null if it does not exist.
-	 * @return mixed
 	 */
-	function getCookie(string $key);
+	function getCookie(string $key): mixed;
 
 	/**
 	 * Returns all cookies.

src/Http/IResponse.php

@@ -335,9 +335,8 @@ interface IResponse
 
 	/**
 	 * Sets HTTP response code.
-	 * @return static
 	 */
-	function setCode(int $code, ?string $reason = null);
+	function setCode(int $code, ?string $reason = null): static;
 
 	/**
 	 * Returns HTTP response code.
@@ -346,21 +345,18 @@ function getCode(): int;
 
 	/**
 	 * Sends an HTTP header, replacing any previously sent header with the same name.
-	 * @return static
 	 */
-	function setHeader(string $name, string $value);
+	function setHeader(string $name, string $value): static;
 
 	/**
 	 * Adds an HTTP header without replacing a previously sent header with the same name.
-	 * @return static
 	 */
-	function addHeader(string $name, string $value);
+	function addHeader(string $name, string $value): static;
 
 	/**
 	 * Sends a Content-type HTTP header.
-	 * @return static
 	 */
-	function setContentType(string $type, ?string $charset = null);
+	function setContentType(string $type, ?string $charset = null): static;
 
 	/**
 	 * Redirects to a new URL.
@@ -370,9 +366,8 @@ function redirect(string $url, int $code = self::S302_Found): void;
 	/**
 	 * Sets the Cache-Control and Expires headers. Pass a time string (e.g. '20 minutes') to enable caching,
 	 * or null to disable it.
-	 * @return static
 	 */
-	function setExpiration(?string $expire);
+	function setExpiration(?string $expire): static;
 
 	/**
 	 * Checks whether HTTP headers have already been sent.
@@ -392,21 +387,27 @@ function getHeaders(): array;
 
 	/**
 	 * Sends a cookie.
-	 * @return static
 	 */
 	function setCookie(
 		string $name,
 		string $value,
 		string|int|\DateTimeInterface|null $expire,
 		?string $path = null,
 		?string $domain = null,
-		?bool $secure = null,
-		?bool $httpOnly = null,
-	);
+		bool $secure = false,
+		bool $httpOnly = true,
+		SameSite $sameSite = SameSite::Lax,
+		bool $partitioned = false,
+	): static;
 
 	/**
 	 * Deletes a cookie.
 	 * @return void
 	 */
-	function deleteCookie(string $name, ?string $path = null, ?string $domain = null, ?bool $secure = null);
+	function deleteCookie(
+		string $name,
+		?string $path = null,
+		?string $domain = null,
+		bool $secure = false,
+	);
 }

src/Http/Response.php

@@ -225,7 +225,6 @@ public function getHeaders(): array
 
 	/**
 	 * Sends a cookie.
-	 * @param SameSite|self::SameSite*|null  $sameSite
 	 * @throws Nette\InvalidStateException  if HTTP headers have been sent
 	 */
 	public function setCookie(
@@ -235,8 +234,8 @@ public function setCookie(
 		?string $path = null,
 		?string $domain = null,
 		?bool $secure = null,
-		?bool $httpOnly = null,
-		SameSite|string|null $sameSite = null,
+		bool $httpOnly = true,
+		SameSite|string|null $sameSite = SameSite::Lax,
 		bool $partitioned = false,
 	): static
 	{
@@ -259,7 +258,6 @@ public function setCookie(
 		}
 
 		$seconds = Helpers::expirationToSeconds($expire);
-		$sameSite ??= SameSite::Lax->value;
 		// both SameSite=None and Partitioned are rejected by the browser without the Secure attribute
 		$secure = $sameSite === SameSite::None->value || $partitioned
 			? true
@@ -271,7 +269,7 @@ public function setCookie(
 			. '; path=' . $path
 			. ($domain === '' ? '' : '; domain=' . $domain)
 			. ($secure ? '; secure' : '')
-			. (($httpOnly ?? true) ? '; HttpOnly' : '')
+			. ($httpOnly ? '; HttpOnly' : '')
 			. '; SameSite=' . $sameSite
 			. ($partitioned ? '; Partitioned' : '');
 		header('Set-Cookie: ' . $cookie, replace: false);