museum-digital/MD_STD
33
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 * Wrapper around file_get_contents, that provides catches errors on it and returns
* with type safety. * 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 * @return string
*/ */
@ -37,14 +37,14 @@ final class MD_STD {
* Returns the real path of a relative file path. Throws an error rather than * Returns the real path of a relative file path. Throws an error rather than
* returning the default false. * 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 { public static function realpath(string $path):string {
$output = \realpath($path); $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."); throw new MDFileDoesNotExist("The file {$path} does not exist or is not readable.");
} }
return $output; return $output;
@ -57,10 +57,10 @@ final class MD_STD {
* *
* @see https://www.php.net/manual/en/function.mkdir.php * @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 integer $mode Permissions.
* @param boolean $recursive Allows the creation of nested directories * @param boolean $recursive Allows the creation of nested directories
* specified in the pathname. * specified in the pathname.
* *
* @return void * @return void
*/ */
@ -82,7 +82,7 @@ final class MD_STD {
* *
* @see https://www.php.net/manual/en/function.unlink.php * @see https://www.php.net/manual/en/function.unlink.php
* *
* @param string $filename File path. * @param non-empty-string $filename File path.
* *
* @return void * @return void
*/ */
@ -97,9 +97,9 @@ final class MD_STD {
/** /**
* Gets contents of a folder. * 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 { public static function scandir(string $filepath):array {
@ -137,8 +137,8 @@ final class MD_STD {
* Function checking if a string starts with another. * Function checking if a string starts with another.
* DEPRECATED. Can be replaced by PHP8's str_starts_with. * DEPRECATED. Can be replaced by PHP8's str_starts_with.
* *
* @param string $haystack String to check. * @param non-empty-string $haystack String to check.
* @param string $needle Potential start of $haystack. * @param non-empty-string $needle Potential start of $haystack.
* *
* @return boolean * @return boolean
*/ */
@ -156,8 +156,8 @@ final class MD_STD {
/** /**
* Function checking if a string starts with any input from the input array. * 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. * @param string[] $needles Array containing potential start values of $haystack.
* *
* @return boolean * @return boolean
*/ */
@ -177,8 +177,8 @@ final class MD_STD {
/** /**
* Function checking if a string contains another in a case-insensitive way. * Function checking if a string contains another in a case-insensitive way.
* *
* @param string $haystack String to check. * @param non-empty-string $haystack String to check.
* @param string $needle Potential start of $haystack. * @param non-empty-string $needle Potential start of $haystack.
* *
* @return boolean * @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 * Function checking if a string contains any of a given set of strings in a
* case-insensitive way. * case-insensitive way.
* *
* @param string $haystack String to check. * @param non-empty-string $haystack String to check.
* @param string[] $needles Potential values contained in haystack. * @param array<non-empty-string> $needles Potential values contained in haystack.
* *
* @return boolean * @return boolean
*/ */
@ -210,9 +210,9 @@ final class MD_STD {
/** /**
* Type-safe(r) wrapper around preg_replace. * 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 $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 * @return string
*/ */
@ -289,8 +289,8 @@ final class MD_STD {
/** /**
* Initializes a curl request with the given presets. * 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. * @param integer $timeout Timeout in milliseconds.
* *
* @return CurlHandle * @return CurlHandle
*/ */
@ -321,10 +321,10 @@ final class MD_STD {
/** /**
* Wrapper for curling contents from the web. * 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 integer $timeout Timeout in milliseconds.
* @param array<string> $headers HTTP headers to pass on. * @param array<string> $headers HTTP headers to pass on.
* Analogous to CURLOPT_HTTPHEADER. * Analogous to CURLOPT_HTTPHEADER.
* *
* @return string * @return string
*/ */
@ -353,10 +353,10 @@ final class MD_STD {
* Wrapper for curling multiple pages from the web at ones and returning their contents. * 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. * 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 integer $timeout Timeout in milliseconds.
* @param array<string> $headers HTTP headers to pass on. * @param array<string> $headers HTTP headers to pass on.
* Analogous to CURLOPT_HTTPHEADER. * Analogous to CURLOPT_HTTPHEADER.
* *
* @return array<string> * @return array<string>
*/ */
@ -400,10 +400,10 @@ final class MD_STD {
/** /**
* Sets and returns user language based on a session cookie. * Sets and returns user language based on a session cookie.
* *
* @param array<string> $allowed_langs Allowed languages. * @param non-empty-array<non-empty-string> $allowed_langs Allowed languages.
* @param string $default_lang Default language. * @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 { 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; return $lang;
} }
@ -438,11 +440,11 @@ final class MD_STD {
/** /**
* Function lang_getfrombrowser gets the browser language based on HTTP headers. * 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. * 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 string $lang_variable Currently set language variable. Optional.
* @param boolean $strict_mode Whether to demand "de-de" (true) or "de" (false) Optional. * @param boolean $strict_mode Whether to demand "de-de" (true) or "de" (false) Optional.
* *
* @return string * @return string
*/ */
@ -527,7 +529,7 @@ final class MD_STD {
/** /**
* Type-safe wrapper around filesize, if output is false, throws an error. * 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 * @return integer
*/ */
@ -550,7 +552,7 @@ final class MD_STD {
* @param integer $bytes A file size, e.g. returned from filesize(). * @param integer $bytes A file size, e.g. returned from filesize().
* @param integer $decimals Number of decimal digits to allow. * @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 { 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. * 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 * @return string
*/ */
@ -638,13 +640,13 @@ final class MD_STD {
/** /**
* Wrapper around the finfo functions to get the mime content type of a file. * 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 * @return string
*/ */
public static function remote_mime_content_type(string $url):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"); 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. * 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. * @param string[] $accepted_mimetype Mime type the file should have.
* *
* @return void * @return void
*/ */
@ -696,7 +698,7 @@ final class MD_STD {
* Wrapper around exec, to be used with editing functions. * Wrapper around exec, to be used with editing functions.
* Pipes STDERR to STDOUT and throws an Exception on any error. * 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 * @return void
*/ */
@ -748,7 +750,7 @@ final class MD_STD {
/** /**
* Checks if a directory is writable. * Checks if a directory is writable.
* *
* @param string $dir Directory path. * @param non-empty-string $dir Directory path.
* *
* @return void * @return void
*/ */
@ -768,16 +770,16 @@ final class MD_STD {
* Splits an lists of integers into parts of a predefined size and returns those * Splits an lists of integers into parts of a predefined size and returns those
* as sub-lists of a superordinate list. * as sub-lists of a superordinate list.
* *
* @param integer[] $input Input array. * @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[]> * @return array<integer[]>
*/ */
public static function split_int_array_into_sized_parts(array $input, int $size):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 = []; $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. * Retrieves HTTP input texts from GET or POST variables, whatever is provided.
* If neither is given, returns a provided default. * 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 string $default Default value for the output.
* @param array<string> $allowed List of allowed values. Defaults to empty (all values allowed). * @param array<string> $allowed List of allowed values. Defaults to empty (all values allowed).
* *
* @return string * @return string
*/ */
@ -164,9 +164,9 @@ final class MD_STD_IN {
* Retrieves HTTP input texts from POST variables. * Retrieves HTTP input texts from POST variables.
* If none is given, returns a provided default. * 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 string $default Default value for the output.
* @param array<string> $allowed List of allowed values. Defaults to empty (all values allowed). * @param array<string> $allowed List of allowed values. Defaults to empty (all values allowed).
* *
* @return string * @return string
*/ */
@ -362,19 +362,22 @@ final class MD_STD_IN {
* Wrapper around move_uploaded_file that throws errors in case the upload failed * Wrapper around move_uploaded_file that throws errors in case the upload failed
* for an identifiable reason. * for an identifiable reason.
* *
* @param string $filename Name of the file to upload. * @param non-empty-string $filename Name of the file to upload.
* @param string $destination Destination to move the file to. * @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 * @param array<string> $mime_types Optional array of acceptable mime types. If this is
* not empty, the file will be checked for having one * not empty, the file will be checked for having one
* of the given mime types. If it does not, an error * of the given mime types. If it does not, an error
* will be thrown. * will be thrown.
* *
* @return boolean * @return boolean
*/ */
public static function move_uploaded_file(string $filename, string $destination, array $mime_types = []):bool { public static function move_uploaded_file(string $filename, string $destination, array $mime_types = []):bool {
MD_STD::ensure_file($filename, $mime_types); 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))) { if (!(\move_uploaded_file($filename, $destination))) {
return false; return false;