museum-digital/MD_STD
32
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Improve phpdoc types, type-safety

Browse Source
This commit is contained in:
Joshua Ramon Enslin 2021-11-29 22:30:28 +01:00
parent 86c8235dae
commit 3f37dd7a9e
Signed by: jrenslin
GPG Key ID: 46016F84501B70AE
2 changed files with 72 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
src/MD_STD.php
View File

@ -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<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,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<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 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<string> $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<string> $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<string> $urls URL to query.
* @param integer $timeout Timeout in milliseconds.
* @param array<string> $headers HTTP headers to pass on.
* Analogous to CURLOPT_HTTPHEADER.
* @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.
*
* @return array<string>
*/
@ -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,11 +440,11 @@ 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
* 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<non-empty-string> $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<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 = [];

29
src/MD_STD_IN.php
View File

@ -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<string> $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<string> $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<string> $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<string> $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<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
* 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<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
* 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;