From 54071f429d3922691d517757447bf61e9c6f7a07 Mon Sep 17 00:00:00 2001 From: Jon Stovell Date: Mon, 1 Apr 2024 15:20:55 -0600 Subject: [PATCH] Fixes return types for various Utils methods In particular, methods that internally use preg functions could return false. Signed-off-by: Jon Stovell --- Sources/Utils.php | 51 +++++++++++++++++++++++------------------------ 1 file changed, 25 insertions(+), 26 deletions(-) diff --git a/Sources/Utils.php b/Sources/Utils.php index 507bd61c06..828cc2d1ba 100644 --- a/Sources/Utils.php +++ b/Sources/Utils.php @@ -299,9 +299,9 @@ function ($matches) use ($substitute) { * @param string|null $substitute Replacement string for the invalid characters. * If not set, the Unicode replacement character (U+FFFD) will be used * (or a fallback like "?" if necessary). - * @return string|bool The sanitized string. False if we failed. + * @return string|false The sanitized string, or false on failure. */ - public static function sanitizeChars(string $string, int $level = 0, ?string $substitute = null): string|bool + public static function sanitizeChars(string $string, int $level = 0, ?string $substitute = null): string|false { $string = (string) $string; $level = min(max((int) $level, 0), 2); @@ -371,9 +371,9 @@ public static function sanitizeChars(string $string, int $level = 0, ?string $su * - no_breaks: Vertical spaces are replaced by " " instead of "\n". * - replace_tabs: If true, tabs are replaced by " " chars. * - collapse_hspace: If true, removes extra horizontal spaces. - * @return string The sanitized string. + * @return string|false The sanitized string, or false on failure. */ - public static function normalizeSpaces(string $string, bool $vspace = true, bool $hspace = false, array $options = []): string + public static function normalizeSpaces(string $string, bool $vspace = true, bool $hspace = false, array $options = []): string|false { $string = (string) $string; $vspace = !empty($vspace); @@ -465,9 +465,9 @@ public static function htmlspecialcharsRecursive(mixed $var, int $flags = ENT_CO * @param int $flags Bitmask of flags to pass to standard htmlspecialchars(). * Default is ENT_QUOTES. * @param string $encoding Character encoding. Default is UTF-8. - * @return string The string without entities. + * @return string|false The string without entities, or false on failure. */ - public static function htmlspecialcharsDecode(string $string, int $flags = ENT_QUOTES, string $encoding = 'UTF-8'): string + public static function htmlspecialcharsDecode(string $string, int $flags = ENT_QUOTES, string $encoding = 'UTF-8'): string|false { return preg_replace('/' . self::ENT_NBSP . '/u', ' ', htmlspecialchars_decode($string, $flags)); } @@ -477,9 +477,9 @@ public static function htmlspecialcharsDecode(string $string, int $flags = ENT_Q * characters, and Unicode whitespace characters beyond the ASCII range. * * @param string $string The string. - * @return string The trimmed string. + * @return string|false The trimmed string, or false on failure. */ - public static function htmlTrim(string $string): string + public static function htmlTrim(string $string): string|false { return preg_replace('~^(?' . '>[\p{Z}\p{C}]|' . self::ENT_NBSP . ')+|(?' . '>[\p{Z}\p{C}]|' . self::ENT_NBSP . ')+$~u', '', self::sanitizeEntities($string)); } @@ -490,9 +490,9 @@ public static function htmlTrim(string $string): string * Only affects values. * * @param array|string $var The string or array of strings to trim. - * @return array|string The trimmed string or array of trimmed strings. + * @return array|string|false The trimmed string or array of trimmed strings. */ - public static function htmlTrimRecursive(array|string $var): array|string + public static function htmlTrimRecursive(array|string $var): array|string|false { static $level = 0; @@ -525,7 +525,7 @@ public static function htmlTrimRecursive(array|string $var): array|string */ public static function entityStrlen(string $string): int { - return strlen(preg_replace('~' . self::ENT_LIST . '|\X~u', '_', self::sanitizeEntities($string))); + return strlen((string) preg_replace('~' . self::ENT_LIST . '|\X~u', '_', self::sanitizeEntities($string))); } /** @@ -539,7 +539,7 @@ public static function entityStrlen(string $string): int */ public static function entityStrpos(string $haystack, string $needle, int $offset = 0): int|false { - $haystack_arr = preg_split('~(' . self::ENT_LIST . '|\X)~u', self::sanitizeEntities($haystack), -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY); + $haystack_arr = (array) preg_split('~(' . self::ENT_LIST . '|\X)~u', self::sanitizeEntities($haystack), -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY); if (strlen($needle) === 1) { $result = array_search($needle, array_slice($haystack_arr, $offset)); @@ -547,7 +547,7 @@ public static function entityStrpos(string $haystack, string $needle, int $offse return is_int($result) ? $result + $offset : false; } - $needle_arr = preg_split('~(' . self::ENT_LIST . '|\X)~u', self::sanitizeEntities($needle), -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY); + $needle_arr = (array) preg_split('~(' . self::ENT_LIST . '|\X)~u', self::sanitizeEntities($needle), -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY); $needle_size = count($needle_arr); @@ -577,7 +577,7 @@ public static function entityStrpos(string $haystack, string $needle, int $offse */ public static function entitySubstr(string $string, int $offset, ?int $length = null): string { - $ent_arr = preg_split('~(' . self::ENT_LIST . '|\X)~u', self::sanitizeEntities($string), -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY); + $ent_arr = (array) preg_split('~(' . self::ENT_LIST . '|\X)~u', self::sanitizeEntities($string), -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY); return $length === null ? implode('', array_slice($ent_arr, $offset)) : implode('', array_slice($ent_arr, $offset, $length)); } @@ -596,7 +596,7 @@ public static function entityStrSplit(string $string, int $length = 1): array throw new \ValueError(); } - $ent_arr = preg_split('~(' . Utils::ENT_LIST . '|\X)~u', Utils::sanitizeEntities($string), -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY); + $ent_arr = (array) preg_split('~(' . Utils::ENT_LIST . '|\X)~u', Utils::sanitizeEntities($string), -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY); if ($length > 1) { $temp = []; @@ -622,13 +622,13 @@ public static function entityStrSplit(string $string, int $length = 1): array * * @param string $string The input string. * @param int $length The maximum length, in bytes, of the returned string. - * @return string The truncated string. + * @return string|false The truncated string, or false on error. */ - public static function truncate(string $string, int $length): string + public static function truncate(string $string, int $length): string|false { $string = self::sanitizeEntities($string); - while (strlen($string) > $length) { + while (is_string($string) && strlen($string) > $length) { $string = preg_replace('~(?:' . self::ENT_LIST . '|\X)$~u', '', $string); } @@ -1330,10 +1330,9 @@ public static function jsonDecode(string $json, ?bool $associative = null, int $ * @param mixed $value The value to encode. * @param int $flags Bitmask of flags for json_encode(). Default: 0. * @param int $depth Maximum depth. Default: 512. - * @return string|bool The decoded data. - * @todo PHP 8.2 The return should be string|false + * @return string|false The decoded data. */ - public static function jsonEncode(mixed $value, int $flags = 0, int $depth = 512): string|bool + public static function jsonEncode(mixed $value, int $flags = 0, int $depth = 512): string|false { return json_encode($value, $flags, $depth); } @@ -1616,9 +1615,9 @@ public static function randomBytes(int $length = 64): string * * @param string $data The data to check, or the path or URL of a file to check. * @param string $is_path If true, $data is a path or URL to a file. - * @return string|bool A MIME type, or false if we cannot determine it. + * @return string|false A MIME type, or false if we cannot determine it. */ - public static function getMimeType(string $data, bool $is_path = false): string|bool + public static function getMimeType(string $data, bool $is_path = false): string|false { $finfo_loaded = extension_loaded('fileinfo'); $exif_loaded = extension_loaded('exif') && function_exists('image_type_to_mime_type'); @@ -2212,7 +2211,7 @@ public static function obExit(?bool $header = null, ?bool $do_footer = null, boo * ADD MORE HERE. * * @param mixed $input Input to parse to find a callable. - * @return string|array|bool Either a callable, or false on failure. + * @return mixed Either a callable, or false on failure. */ public static function getCallable(mixed $input, ?bool $ignore_errors = null): mixed { @@ -2337,10 +2336,10 @@ final protected static function fixUtf8mb4(string $string): string * - $themedir (only works if SMF\Theme has already been initialized) * * @param string $string The string containing a valid format. - * @return string|bool The given string with the pipe and file info removed + * @return string|false The given string with the pipe and file info removed * or false if the file couldn't be loaded. */ - final protected static function loadFile(string $string): string|bool + final protected static function loadFile(string $string): string|false { if (empty($string)) { return false;