From 3f37dd7a9ea7354b3b58a93cd1dc36da8879db31 Mon Sep 17 00:00:00 2001 From: Joshua Ramon Enslin Date: Mon, 29 Nov 2021 22:30:28 +0100 Subject: [PATCH] Improve phpdoc types, type-safety --- src/MD_STD.php | 110 +++++++++++++++++++++++----------------------- src/MD_STD_IN.php | 29 ++++++------ 2 files changed, 72 insertions(+), 67 deletions(-) diff --git a/src/MD_STD.php b/src/MD_STD.php index 0067221..74af66b 100644 --- a/src/MD_STD.php +++ b/src/MD_STD.php @@ -13,7 +13,7 @@ final class MD_STD { * Wrapper around file_get_contents, that provides catches errors on it and returns * with type safety. * - * @param string $filename Filepath of the file to read. + * @param non-empty-string $filename Filepath of the file to read. * * @return string */ @@ -37,14 +37,14 @@ final class MD_STD { * Returns the real path of a relative file path. Throws an error rather than * returning the default false. * - * @param string $path File path to convert. + * @param non-empty-string $path File path to convert. * - * @return string + * @return non-empty-string */ public static function realpath(string $path):string { $output = \realpath($path); - if (!\is_string($output)) { + if (!\is_string($output) || empty($output)) { throw new MDFileDoesNotExist("The file {$path} does not exist or is not readable."); } return $output; @@ -57,10 +57,10 @@ final class MD_STD { * * @see https://www.php.net/manual/en/function.mkdir.php * - * @param string $pathname The directory path. - * @param integer $mode Permissions. - * @param boolean $recursive Allows the creation of nested directories - * specified in the pathname. + * @param non-empty-string $pathname The directory path. + * @param integer $mode Permissions. + * @param boolean $recursive Allows the creation of nested directories + * specified in the pathname. * * @return void */ @@ -82,7 +82,7 @@ final class MD_STD { * * @see https://www.php.net/manual/en/function.unlink.php * - * @param string $filename File path. + * @param non-empty-string $filename File path. * * @return void */ @@ -97,9 +97,9 @@ final class MD_STD { /** * Gets contents of a folder. * - * @param string $filepath Directory path. + * @param non-empty-string $filepath Directory path. * - * @return array + * @return array */ public static function scandir(string $filepath):array { @@ -137,8 +137,8 @@ final class MD_STD { * Function checking if a string starts with another. * DEPRECATED. Can be replaced by PHP8's str_starts_with. * - * @param string $haystack String to check. - * @param string $needle Potential start of $haystack. + * @param non-empty-string $haystack String to check. + * @param non-empty-string $needle Potential start of $haystack. * * @return boolean */ @@ -156,8 +156,8 @@ final class MD_STD { /** * Function checking if a string starts with any input from the input array. * - * @param string $haystack String to check. - * @param string[] $needles Array containing potential start values of $haystack. + * @param non-empty-string $haystack String to check. + * @param string[] $needles Array containing potential start values of $haystack. * * @return boolean */ @@ -177,8 +177,8 @@ final class MD_STD { /** * Function checking if a string contains another in a case-insensitive way. * - * @param string $haystack String to check. - * @param string $needle Potential start of $haystack. + * @param non-empty-string $haystack String to check. + * @param non-empty-string $needle Potential start of $haystack. * * @return boolean */ @@ -193,8 +193,8 @@ final class MD_STD { * Function checking if a string contains any of a given set of strings in a * case-insensitive way. * - * @param string $haystack String to check. - * @param string[] $needles Potential values contained in haystack. + * @param non-empty-string $haystack String to check. + * @param array $needles Potential values contained in haystack. * * @return boolean */ @@ -210,9 +210,9 @@ final class MD_STD { /** * Type-safe(r) wrapper around preg_replace. * - * @param string $pattern The pattern to search for. It can be either a string or an array with strings. - * @param string $replacement To replace with. - * @param string $subject The string or an array with strings to search and replace. + * @param non-empty-string $pattern The pattern to search for. It can be either a string or an array with strings. + * @param string $replacement To replace with. + * @param non-empty-string $subject The string or an array with strings to search and replace. * * @return string */ @@ -289,8 +289,8 @@ final class MD_STD { /** * Initializes a curl request with the given presets. * - * @param string $url URL to query. - * @param integer $timeout Timeout in milliseconds. + * @param non-empty-string $url URL to query. + * @param integer $timeout Timeout in milliseconds. * * @return CurlHandle */ @@ -321,10 +321,10 @@ final class MD_STD { /** * Wrapper for curling contents from the web. * - * @param string $url URL to query. - * @param integer $timeout Timeout in milliseconds. - * @param array $headers HTTP headers to pass on. - * Analogous to CURLOPT_HTTPHEADER. + * @param non-empty-string $url URL to query. + * @param integer $timeout Timeout in milliseconds. + * @param array $headers HTTP headers to pass on. + * Analogous to CURLOPT_HTTPHEADER. * * @return string */ @@ -353,10 +353,10 @@ final class MD_STD { * Wrapper for curling multiple pages from the web at ones and returning their contents. * Adapted from hushuilong's comment at https://www.php.net/manual/de/function.curl-multi-init.php#105252. * - * @param array $urls URL to query. - * @param integer $timeout Timeout in milliseconds. - * @param array $headers HTTP headers to pass on. - * Analogous to CURLOPT_HTTPHEADER. + * @param non-empty-array $urls URL to query. + * @param integer $timeout Timeout in milliseconds. + * @param array $headers HTTP headers to pass on. + * Analogous to CURLOPT_HTTPHEADER. * * @return array */ @@ -400,10 +400,10 @@ final class MD_STD { /** * Sets and returns user language based on a session cookie. * - * @param array $allowed_langs Allowed languages. - * @param string $default_lang Default language. + * @param non-empty-array $allowed_langs Allowed languages. + * @param non-empty-string $default_lang Default language. * - * @return string + * @return non-empty-string */ public static function get_user_lang(array $allowed_langs, string $default_lang):string { @@ -431,6 +431,8 @@ final class MD_STD { } } + if (empty($lang)) return $default_lang; + return $lang; } @@ -438,11 +440,11 @@ final class MD_STD { /** * Function lang_getfrombrowser gets the browser language based on HTTP headers. * - * @param array $allowed_languages Array containing all the languages for which - * there are translations. - * @param string $default_language Default language of the instance of MD. - * @param string $lang_variable Currently set language variable. Optional. - * @param boolean $strict_mode Whether to demand "de-de" (true) or "de" (false) Optional. + * @param non-empty-array $allowed_languages Array containing all the languages for which + * there are translations. + * @param non-empty-string $default_language Default language of the instance of MD. + * @param string $lang_variable Currently set language variable. Optional. + * @param boolean $strict_mode Whether to demand "de-de" (true) or "de" (false) Optional. * * @return string */ @@ -527,7 +529,7 @@ final class MD_STD { /** * Type-safe wrapper around filesize, if output is false, throws an error. * - * @param string $filename File name. + * @param non-empty-string $filename File name. * * @return integer */ @@ -550,7 +552,7 @@ final class MD_STD { * @param integer $bytes A file size, e.g. returned from filesize(). * @param integer $decimals Number of decimal digits to allow. * - * @return string + * @return non-empty-string */ public static function human_filesize(int $bytes, int $decimals = 2):string { @@ -617,7 +619,7 @@ final class MD_STD { /** * Wrapper around the finfo functions to get the mime content type of a file. * - * @param string $filepath Expected file path. + * @param non-empty-string $filepath Expected file path. * * @return string */ @@ -638,13 +640,13 @@ final class MD_STD { /** * Wrapper around the finfo functions to get the mime content type of a file. * - * @param string $url Expected file path. + * @param non-empty-string $url Expected file path. * * @return string */ public static function remote_mime_content_type(string $url):string { - if (($tmp_file = \tempnam(\sys_get_temp_dir(), "remote_mime_type_check")) === false) { + if (empty($tmp_file = \tempnam(\sys_get_temp_dir(), "remote_mime_type_check"))) { throw new Exception("Failed to get temporary file location"); } @@ -668,8 +670,8 @@ final class MD_STD { /** * Checks if a file exists, with one of the expected mime types. * - * @param string $filepath File path of the file that needs to exist. - * @param string[] $accepted_mimetype Mime type the file should have. + * @param non-empty-string $filepath File path of the file that needs to exist. + * @param string[] $accepted_mimetype Mime type the file should have. * * @return void */ @@ -696,7 +698,7 @@ final class MD_STD { * Wrapper around exec, to be used with editing functions. * Pipes STDERR to STDOUT and throws an Exception on any error. * - * @param string $cmds Commands to run. + * @param non-empty-string $cmds Commands to run. * * @return void */ @@ -748,7 +750,7 @@ final class MD_STD { /** * Checks if a directory is writable. * - * @param string $dir Directory path. + * @param non-empty-string $dir Directory path. * * @return void */ @@ -768,16 +770,16 @@ final class MD_STD { * Splits an lists of integers into parts of a predefined size and returns those * as sub-lists of a superordinate list. * - * @param integer[] $input Input array. - * @param integer $size Size of each part of the return set. + * @param integer[] $input Input array. + * @param positive-int $size Size of each part of the return set. * * @return array */ public static function split_int_array_into_sized_parts(array $input, int $size):array { - if ($size < 1) { - throw new Exception("Size must be lower than 1"); - } + /* + if ($size < 1) throw new Exception("Size of the target array must be a positive integer"); + */ $output = []; diff --git a/src/MD_STD_IN.php b/src/MD_STD_IN.php index 680140b..ffeb3e4 100644 --- a/src/MD_STD_IN.php +++ b/src/MD_STD_IN.php @@ -134,9 +134,9 @@ final class MD_STD_IN { * Retrieves HTTP input texts from GET or POST variables, whatever is provided. * If neither is given, returns a provided default. * - * @param string $var_name Variable name. - * @param string $default Default value for the output. - * @param array $allowed List of allowed values. Defaults to empty (all values allowed). + * @param non-empty-string $var_name Variable name. + * @param string $default Default value for the output. + * @param array $allowed List of allowed values. Defaults to empty (all values allowed). * * @return string */ @@ -164,9 +164,9 @@ final class MD_STD_IN { * Retrieves HTTP input texts from POST variables. * If none is given, returns a provided default. * - * @param string $var_name Variable name. - * @param string $default Default value for the output. - * @param array $allowed List of allowed values. Defaults to empty (all values allowed). + * @param non-empty-string $var_name Variable name. + * @param string $default Default value for the output. + * @param array $allowed List of allowed values. Defaults to empty (all values allowed). * * @return string */ @@ -362,19 +362,22 @@ final class MD_STD_IN { * Wrapper around move_uploaded_file that throws errors in case the upload failed * for an identifiable reason. * - * @param string $filename Name of the file to upload. - * @param string $destination Destination to move the file to. - * @param array $mime_types Optional array of acceptable mime types. If this is - * not empty, the file will be checked for having one - * of the given mime types. If it does not, an error - * will be thrown. + * @param non-empty-string $filename Name of the file to upload. + * @param non-empty-string $destination Destination to move the file to. + * @param array $mime_types Optional array of acceptable mime types. If this is + * not empty, the file will be checked for having one + * of the given mime types. If it does not, an error + * will be thrown. * * @return boolean */ public static function move_uploaded_file(string $filename, string $destination, array $mime_types = []):bool { MD_STD::ensure_file($filename, $mime_types); - MD_STD::check_is_writable(dirname($destination)); + if (empty($destDir = dirname($destination))) { + return false; + } + MD_STD::check_is_writable($destDir); if (!(\move_uploaded_file($filename, $destination))) { return false;