Helpers: added expirationToSeconds() unifying expiration handling

dg · dg · commit 0e4120df8723 · 2026-06-02T01:59:24.000+02:00
A numeric value is now always treated as a relative interval in seconds
(avoiding the ambiguous one-year threshold in DateTime::from()), a
DateTimeInterface as an absolute time, and a textual string is resolved by
strtotime(). null means a session lifetime; a time in the past is clamped to 0
(immediate deletion). A falsy value (0, '0', '') is kept as a session lifetime
for BC but is now deprecated in favour of null. Session::setExpiration() rejects
an expiration in the past. Used by Response and Session cookie/expiration methods.
diff --git a/src/Http/Helpers.php b/src/Http/Helpers.php
@@ -36,6 +36,27 @@ public static function formatDate(string|int|\DateTimeInterface $time): string
 	}
 
 
+	/**
+	 * Converts an expiration value to the number of seconds from now (may be negative for the past).
+	 * A numeric value (including a numeric string) is taken directly as the number of seconds; a
+	 * DateTimeInterface or a textual string (e.g. '20 minutes', '2024-01-01') is resolved as an absolute
+	 * time. Returns null for null (no value); an empty string is rejected as it is never meaningful.
+	 * @throws Nette\InvalidArgumentException  for an empty string
+	 */
+	public static function expirationToSeconds(string|int|\DateTimeInterface|null $expire): ?int
+	{
+		if ($expire === null) {
+			return null;
+		} elseif ($expire === '') {
+			throw new Nette\InvalidArgumentException('Expiration must not be an empty string; use null instead.');
+		}
+
+		return is_numeric($expire)
+			? (int) $expire
+			: DateTime::from($expire)->getTimestamp() - time();
+	}
+
+
 	/**
 	 * Parses an HTTP quality-value list such as the Accept, Accept-Language or Accept-Encoding header
 	 * into tokens mapped to their q-factor, ordered by descending preference. Tokens are lowercased and
@@ -83,6 +104,6 @@ public static function ipMatch(string $ip, string $mask): bool
 	 */
 	public static function initCookie(IRequest $request, IResponse $response): void
 	{
-		$response->setCookie(self::StrictCookieName, '1', 0, '/', sameSite: IResponse::SameSiteStrict);
+		$response->setCookie(self::StrictCookieName, '1', null, '/', sameSite: IResponse::SameSiteStrict);
 	}
 }
diff --git a/src/Http/Response.php b/src/Http/Response.php
@@ -8,7 +8,6 @@
 namespace Nette\Http;
 
 use Nette;
-use Nette\Utils\DateTime;
 use function array_filter, header, header_remove, headers_list, headers_sent, htmlspecialchars, http_response_code, ini_get, is_int, ltrim, ob_get_length, ob_get_status, preg_match, rawurlencode, setcookie, str_replace, strcasecmp, strlen, strncasecmp, substr, time;
 use const PHP_SAPI;
 
@@ -166,16 +165,16 @@ public function redirect(string $url, int $code = self::S302_Found): void
 	 */
 	public function setExpiration(?string $expire): static
 	{
+		$seconds = Helpers::expirationToSeconds($expire);
 		$this->setHeader('Pragma', null);
-		if (!$expire) { // no cache
+		if ($seconds === null || $seconds <= 0) { // no cache
 			$this->setHeader('Cache-Control', 's-maxage=0, max-age=0, must-revalidate');
 			$this->setHeader('Expires', 'Mon, 23 Jan 1978 10:00:00 GMT');
 			return $this;
 		}
 
-		$expire = DateTime::from($expire);
-		$this->setHeader('Cache-Control', 'max-age=' . ($expire->format('U') - time()));
-		$this->setHeader('Expires', Helpers::formatDate($expire));
+		$this->setHeader('Cache-Control', 'max-age=' . $seconds);
+		$this->setHeader('Expires', Helpers::formatDate(time() + $seconds));
 		return $this;
 	}
 
@@ -241,8 +240,14 @@ public function setCookie(
 	): static
 	{
 		self::checkHeaders();
+		if ($expire === 0) { // BC: 0 used to mean a session cookie
+			trigger_error('Passing 0 as $expire is deprecated; use null for a session cookie.', E_USER_DEPRECATED);
+			$expire = null;
+		}
+
+		$seconds = Helpers::expirationToSeconds($expire);
 		setcookie($name, $value, [
-			'expires' => $expire ? (int) DateTime::from($expire)->format('U') : 0,
+			'expires' => $seconds === null ? 0 : time() + $seconds,
 			'path' => $path ?? ($domain ? '/' : $this->cookiePath),
 			'domain' => $domain ?? ($path ? '' : $this->cookieDomain),
 			'secure' => $secure ?? $this->cookieSecure,
@@ -264,7 +269,7 @@ public function deleteCookie(
 		?bool $secure = null,
 	): void
 	{
-		$this->setCookie($name, '', 0, $path, $domain, $secure);
+		$this->setCookie($name, '', null, $path, $domain, $secure);
 	}
 
 
diff --git a/src/Http/Session.php b/src/Http/Session.php
@@ -485,19 +485,20 @@ private function configure(array $config): void
 	 */
 	public function setExpiration(?string $expire): static
 	{
-		if ($expire === null) {
+		$seconds = Helpers::expirationToSeconds($expire);
+		if ($seconds === null) {
 			return $this->setOptions([
 				'gc_maxlifetime' => self::DefaultFileLifetime,
 				'cookie_lifetime' => 0,
 			]);
-
-		} else {
-			$expire = Nette\Utils\DateTime::from($expire)->format('U') - time();
-			return $this->setOptions([
-				'gc_maxlifetime' => $expire,
-				'cookie_lifetime' => $expire,
-			]);
+		} elseif ($seconds <= 0) {
+			throw new Nette\InvalidArgumentException("Session expiration must be in the future, '$expire' given.");
 		}
+
+		return $this->setOptions([
+			'gc_maxlifetime' => $seconds,
+			'cookie_lifetime' => $seconds,
+		]);
 	}
 
 
@@ -554,7 +555,7 @@ private function sendCookie(): void
 		$this->response->setCookie(
 			session_name(),
 			session_id(),
-			$cookie['lifetime'] ? $cookie['lifetime'] + time() : 0,
+			$cookie['lifetime'] ? $cookie['lifetime'] + time() : null,
 			$cookie['path'],
 			$cookie['domain'],
 			$cookie['secure'],
diff --git a/src/Http/SessionSection.php b/src/Http/SessionSection.php
@@ -7,7 +7,6 @@
 
 namespace Nette\Http;
 
-use Nette;
 use function array_key_exists, func_num_args, ini_get, is_array, is_string, time;
 
 
@@ -192,21 +191,22 @@ public function offsetUnset($name): void
 	 */
 	public function setExpiration(?string $expire, string|array|null $variables = null): static
 	{
-		$this->session->autoStart((bool) $expire);
+		$seconds = Helpers::expirationToSeconds($expire);
+		$this->session->autoStart($seconds !== null);
 		$meta = &$this->getMeta();
-		if ($expire) {
-			$expire = Nette\Utils\DateTime::from($expire)->format('U');
+		if ($seconds !== null) {
 			$max = (int) ini_get('session.gc_maxlifetime');
 			if (
 				$max !== 0 // 0 - unlimited in memcache handler
-				&& ($expire - time() > $max + 3) // 3 - bulgarian constant
+				&& ($seconds > $max + 3) // 3 - bulgarian constant
 			) {
 				trigger_error("The expiration time is greater than the session expiration $max seconds");
 			}
 		}
 
+		$time = $seconds === null ? null : time() + $seconds;
 		foreach (is_array($variables) ? $variables : [$variables] as $variable) {
-			$meta[$variable ?? '']['T'] = $expire ?: null;
+			$meta[$variable ?? '']['T'] = $time;
 		}
 
 		return $this;
diff --git a/tests/Http/Helpers.phpt b/tests/Http/Helpers.phpt
@@ -71,3 +71,27 @@ test('date formatting', function () {
 	Assert::same('Tue, 15 Nov 1994 08:12:31 GMT', Helpers::formatDate(new DateTime('1994-11-15T06:12:31-0200')));
 	Assert::same('Tue, 15 Nov 1994 08:12:31 GMT', Helpers::formatDate(784_887_151));
 });
+
+
+test('expirationToSeconds', function () {
+	// null means no value
+	Assert::null(Helpers::expirationToSeconds(null));
+
+	// an empty string is never meaningful
+	Assert::exception(
+		fn() => Helpers::expirationToSeconds(''),
+		Nette\InvalidArgumentException::class,
+	);
+
+	// a numeric value (int or string) is the number of seconds directly
+	Assert::same(0, Helpers::expirationToSeconds(0));
+	Assert::same(0, Helpers::expirationToSeconds('0'));
+	Assert::same(3600, Helpers::expirationToSeconds(3600));
+	Assert::same(3600, Helpers::expirationToSeconds('3600'));
+	Assert::same(-5, Helpers::expirationToSeconds(-5));
+	Assert::same(-5, Helpers::expirationToSeconds('-5'));
+
+	// a textual or DateTime value is resolved as an absolute time, relative to now
+	Assert::true(abs(Helpers::expirationToSeconds('+1 hour') - 3600) <= 1);
+	Assert::true(abs(Helpers::expirationToSeconds(new DateTime('+1 hour')) - 3600) <= 1);
+});
diff --git a/tests/Http/Response.setCookie.phpt b/tests/Http/Response.setCookie.phpt
@@ -18,12 +18,12 @@ $old = headers_list();
 $response = new Http\Response;
 
 
-$response->setCookie('test', 'value', 0);
+$response->setCookie('test', 'value', null);
 $headers = array_values(array_diff(headers_list(), $old, ['Set-Cookie:']));
 Assert::same(['Set-Cookie: test=value; path=/; HttpOnly; SameSite=Lax'], $headers);
 
 
-$response->setCookie('test', 'newvalue', 0);
+$response->setCookie('test', 'newvalue', null);
 $headers = array_values(array_diff(headers_list(), $old, ['Set-Cookie:']));
 Assert::same(['Set-Cookie: test=value; path=/; HttpOnly; SameSite=Lax', 'Set-Cookie: test=newvalue; path=/; HttpOnly; SameSite=Lax'], $headers);
 
@@ -32,19 +32,19 @@ Assert::same(['Set-Cookie: test=value; path=/; HttpOnly; SameSite=Lax', 'Set-Coo
 $response = new Http\Response;
 $response->cookiePath = '/foo';
 $old = headers_list();
-$response->setCookie('test', 'a', 0);
+$response->setCookie('test', 'a', null);
 $headers = array_values(array_diff(headers_list(), $old, ['Set-Cookie:']));
 Assert::same(['Set-Cookie: test=a; path=/foo; HttpOnly; SameSite=Lax'], $headers);
 
 // cookiePath + path
 $old = headers_list();
-$response->setCookie('test', 'b', 0, '/bar');
+$response->setCookie('test', 'b', null, '/bar');
 $headers = array_values(array_diff(headers_list(), $old, ['Set-Cookie:']));
 Assert::same(['Set-Cookie: test=b; path=/bar; HttpOnly; SameSite=Lax'], $headers);
 
 // cookiePath + domain
 $old = headers_list();
-$response->setCookie('test', 'c', 0, null, 'nette.org');
+$response->setCookie('test', 'c', null, null, 'nette.org');
 $headers = array_values(array_diff(headers_list(), $old, ['Set-Cookie:']));
 Assert::same(['Set-Cookie: test=c; path=/; domain=nette.org; HttpOnly; SameSite=Lax'], $headers);
 
@@ -53,18 +53,30 @@ Assert::same(['Set-Cookie: test=c; path=/; domain=nette.org; HttpOnly; SameSite=
 $response = new Http\Response;
 $response->cookieDomain = 'nette.org';
 $old = headers_list();
-$response->setCookie('test', 'd', 0);
+$response->setCookie('test', 'd', null);
 $headers = array_values(array_diff(headers_list(), $old, ['Set-Cookie:']));
 Assert::same(['Set-Cookie: test=d; path=/; domain=nette.org; HttpOnly; SameSite=Lax'], $headers);
 
 // cookieDomain + path
 $old = headers_list();
-$response->setCookie('test', 'e', 0, '/bar');
+$response->setCookie('test', 'e', null, '/bar');
 $headers = array_values(array_diff(headers_list(), $old, ['Set-Cookie:']));
 Assert::same(['Set-Cookie: test=e; path=/bar; HttpOnly; SameSite=Lax'], $headers);
 
 // cookieDomain + domain
 $old = headers_list();
-$response->setCookie('test', 'f', 0, null, 'example.org');
+$response->setCookie('test', 'f', null, null, 'example.org');
 $headers = array_values(array_diff(headers_list(), $old, ['Set-Cookie:']));
 Assert::same(['Set-Cookie: test=f; path=/; domain=example.org; HttpOnly; SameSite=Lax'], $headers);
+
+
+// integer 0 is deprecated, but kept as a session cookie for BC
+$response = new Http\Response;
+$old = headers_list();
+Assert::error(
+	fn() => $response->setCookie('test', 'g', 0),
+	E_USER_DEPRECATED,
+	'Passing 0 as $expire is deprecated; use null for a session cookie.',
+);
+$headers = array_values(array_diff(headers_list(), $old, ['Set-Cookie:']));
+Assert::same(['Set-Cookie: test=g; path=/; HttpOnly; SameSite=Lax'], $headers);
