Improve phpdoc types, type-safety
This commit is contained in:
parent
86c8235dae
commit
3f37dd7a9e
|
@ -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,7 +57,7 @@ final class MD_STD {
|
|||
*
|
||||
* @see https://www.php.net/manual/en/function.mkdir.php
|
||||
*
|
||||
* @param string $pathname The directory path.
|
||||
* @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.
|
||||
|
@ -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<string>
|
||||
* @return array<non-empty-string>
|
||||
*/
|
||||
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,7 +156,7 @@ final class MD_STD {
|
|||
/**
|
||||
* Function checking if a string starts with any input from the input array.
|
||||
*
|
||||
* @param string $haystack String to check.
|
||||
* @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<non-empty-string> $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 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 string $subject The string or an array with strings to search and replace.
|
||||
* @param non-empty-string $subject The string or an array with strings to search and replace.
|
||||
*
|
||||
* @return string
|
||||
*/
|
||||
|
@ -289,7 +289,7 @@ final class MD_STD {
|
|||
/**
|
||||
* Initializes a curl request with the given presets.
|
||||
*
|
||||
* @param string $url URL to query.
|
||||
* @param non-empty-string $url URL to query.
|
||||
* @param integer $timeout Timeout in milliseconds.
|
||||
*
|
||||
* @return CurlHandle
|
||||
|
@ -321,7 +321,7 @@ final class MD_STD {
|
|||
/**
|
||||
* Wrapper for curling contents from the web.
|
||||
*
|
||||
* @param string $url URL to query.
|
||||
* @param non-empty-string $url URL to query.
|
||||
* @param integer $timeout Timeout in milliseconds.
|
||||
* @param array<string> $headers HTTP headers to pass on.
|
||||
* Analogous to CURLOPT_HTTPHEADER.
|
||||
|
@ -353,7 +353,7 @@ 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<string> $urls URL to query.
|
||||
* @param non-empty-array<non-empty-string> $urls URL to query.
|
||||
* @param integer $timeout Timeout in milliseconds.
|
||||
* @param array<string> $headers HTTP headers to pass on.
|
||||
* Analogous to CURLOPT_HTTPHEADER.
|
||||
|
@ -400,10 +400,10 @@ final class MD_STD {
|
|||
/**
|
||||
* Sets and returns user language based on a session cookie.
|
||||
*
|
||||
* @param array<string> $allowed_langs Allowed languages.
|
||||
* @param string $default_lang Default language.
|
||||
* @param non-empty-array<non-empty-string> $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,9 +440,9 @@ final class MD_STD {
|
|||
/**
|
||||
* Function lang_getfrombrowser gets the browser language based on HTTP headers.
|
||||
*
|
||||
* @param array<string> $allowed_languages Array containing all the languages for which
|
||||
* @param non-empty-array<non-empty-string> $allowed_languages Array containing all the languages for which
|
||||
* there are translations.
|
||||
* @param string $default_language Default language of the instance of MD.
|
||||
* @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.
|
||||
*
|
||||
|
@ -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,7 +670,7 @@ 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 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
|
||||
*/
|
||||
|
@ -769,15 +771,15 @@ final class MD_STD {
|
|||
* as sub-lists of a superordinate list.
|
||||
*
|
||||
* @param integer[] $input Input array.
|
||||
* @param integer $size Size of each part of the return set.
|
||||
* @param positive-int $size Size of each part of the return set.
|
||||
*
|
||||
* @return array<integer[]>
|
||||
*/
|
||||
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 = [];
|
||||
|
||||
|
|
|
@ -134,7 +134,7 @@ 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 non-empty-string $var_name Variable name.
|
||||
* @param string $default Default value for the output.
|
||||
* @param array<string> $allowed List of allowed values. Defaults to empty (all values allowed).
|
||||
*
|
||||
|
@ -164,7 +164,7 @@ 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 non-empty-string $var_name Variable name.
|
||||
* @param string $default Default value for the output.
|
||||
* @param array<string> $allowed List of allowed values. Defaults to empty (all values allowed).
|
||||
*
|
||||
|
@ -362,8 +362,8 @@ 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 non-empty-string $filename Name of the file to upload.
|
||||
* @param non-empty-string $destination Destination to move the file to.
|
||||
* @param array<string> $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
|
||||
|
@ -374,7 +374,10 @@ final class MD_STD_IN {
|
|||
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;
|
||||
|
|
Loading…
Reference in New Issue
Block a user