From 06bff0b9b84d47c43f9bc8aff06a29d85ebb7ed0 Mon Sep 17 00:00:00 2001
From: Simon Rettberg
Date: Tue, 14 Nov 2023 14:47:55 +0100
Subject: Add function param/return types, fix a lot more phpstorm complaints

---
 inc/util.inc.php | 41 +++++++++++++++++++++++++----------------
 1 file changed, 25 insertions(+), 16 deletions(-)

(limited to 'inc/util.inc.php')

diff --git a/inc/util.inc.php b/inc/util.inc.php
index 8bd48dd3..0c402a6a 100644
--- a/inc/util.inc.php
+++ b/inc/util.inc.php
@@ -1,5 +1,7 @@
 <?php
 
+use JetBrains\PhpStorm\NoReturn;
+
 class Util
 {
 	private static $redirectParams = array();
@@ -12,7 +14,8 @@ class Util
 	 * @param string|false $location Location to redirect to. "false" to redirect to same URL (useful after POSTs)
 	 * @param bool $preferRedirectPost if true, use the value from $_POST['redirect'] instead of $location
 	 */
-	public static function redirect($location = false, bool $preferRedirectPost = false)
+	#[NoReturn]
+	public static function redirect($location = false, bool $preferRedirectPost = false): void
 	{
 		if ($location === false) {
 			$location = preg_replace('/([&?])message\[\]=[^&]*/', '\1', $_SERVER['REQUEST_URI']);
@@ -48,7 +51,7 @@ class Util
 		exit(0);
 	}
 	
-	public static function addRedirectParam(string $key, string $value)
+	public static function addRedirectParam(string $key, string $value): void
 	{
 		self::$redirectParams[] = $key . '=' . urlencode($value);
 	}
@@ -108,7 +111,7 @@ class Util
 		if ($factor === 0) {
 			$decimals = 0;
 		} else {
-			$bytes = $bytes / pow(1024, $factor);
+			$bytes /= 1024 ** $factor;
 			if ($decimals === -1) {
 				$decimals = 2 - floor(strlen((int)$bytes) - 1);
 			}
@@ -116,7 +119,7 @@ class Util
 		return Dictionary::number($bytes, $decimals) . "\xe2\x80\x89" . ($sz[$factor + $shift] ?? '#>PiB#');
 	}
 
-	public static function sanitizeFilename(string $name)
+	public static function sanitizeFilename(string $name): string
 	{
 		return preg_replace('/[^a-zA-Z0-9_\-]+/', '_', $name);
 	}
@@ -130,7 +133,7 @@ class Util
 	 * @param string $prefix required prefix of $path
 	 * @return false|string
 	 */
-	public static function safePath(string $path, string $prefix = '')
+	public static function safePath(string $path, string $prefix = ''): string
 	{
 		if (empty($path))
 			return false;
@@ -253,9 +256,9 @@ class Util
 	 *
 	 * @param int $length number of bytes to return
 	 * @param bool $secure true = only use strong random sources
-	 * @return string|bool string of requested length, false on error
+	 * @return ?string string of requested length, false on error
 	 */
-	public static function randomBytes(int $length, bool $secure = true)
+	public static function randomBytes(int $length, bool $secure = true): ?string
 	{
 		if (function_exists('random_bytes')) {
 			try {
@@ -292,7 +295,7 @@ class Util
 			}
 		}
 		if ($secure) {
-			return false;
+			return null;
 		}
 		$bytes = '';
 		while ($length > 0) {
@@ -306,7 +309,7 @@ class Util
 	 */
 	public static function randomUuid(): string
 	{
-		$b = unpack('h8a/h4b/h12c', self::randomBytes(12));
+		$b = unpack('h8a/h4b/h12c', self::randomBytes(12, false));
 		return sprintf('%08s-%04s-%04x-%04x-%012s',
 
 			// 32 bits for "time_low"
@@ -334,7 +337,7 @@ class Util
 	 * The format depends on how far the timestamp lies in the past.
 	 *
 	 * @param int $ts unix timestamp
-	 * @return string human readable representation
+	 * @return string human-readable representation
 	 */
 	public static function prettyTime(int $ts): string
 	{
@@ -366,8 +369,8 @@ class Util
 	public static function boolToString(bool $bool): string
 	{
 		if ($bool)
-			return Dictionary::translate('lang_yes', true);
-		return Dictionary::translate('lang_no', true);
+			return Dictionary::translate('lang_yes');
+		return Dictionary::translate('lang_no');
 	}
 
 	/**
@@ -375,7 +378,6 @@ class Util
 	 *
 	 * @param int $seconds The number to format
 	 * @param bool $showSecs whether to show seconds, or rather cut after minutes
-	 * @return string
 	 */
 	public static function formatDuration(int $seconds, bool $showSecs = true): string
 	{
@@ -408,7 +410,7 @@ class Util
 	 *
 	 * @param string $name cookie name
 	 */
-	public static function clearCookie(string $name)
+	public static function clearCookie(string $name): void
 	{
 		$parts = explode('/', $_SERVER['SCRIPT_NAME']);
 		$path = '';
@@ -455,14 +457,21 @@ class Util
 
 	/**
 	 * Clamp given value into [min, max] range.
+	 * @param mixed $value value to clamp. This should be a number.
+	 * @param int $min lower bound
+	 * @param int $max upper bound
+	 * @param bool $toInt if true, variable type of $value will be set to int in addition to clamping
 	 */
-	public static function clamp(int &$value, int $min, int $max)
+	public static function clamp(&$value, int $min, int $max, bool $toInt = true): void
 	{
-		if ($value < $min) {
+		if (!is_numeric($value) || $value < $min) {
 			$value = $min;
 		} elseif ($value > $max) {
 			$value = $max;
 		}
+		if ($toInt) {
+			settype($value, 'int');
+		}
 	}
 
 }
-- 
cgit v1.2.3-55-g7522