Improve comment on return parameter

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 museum-digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,13 @@
+# Standard functions for museum-digital
+
+This repository contains the most basic functions for working on museum-digital. Functions are provided as static functions of classes.
+The (by far) most relevant classes in this repository are:
+
+- [MD_STD](./src/MD_STD.php)
+  This class mainly provides type-safe wrappers around internal PHP functions. Where the general [`realpath()`](https://www.php.net/manual/en/function.realpath.php) will return `false` if the provided path does not exist, `MD_STD::realpath()` will, e.g., throw an exception or return the absolute path of the input file.
+- [MD_STD_IN](./src/MD_STD_IN.php)
+  This class is concerned with safely getting input data. It thus mainly covers shorthand functions for validating or sanitizing various types of input data.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for the full license text.

src/MD_STD.php

@@ -94,6 +94,25 @@ final class MD_STD {
 
     }
 
+    /**
+     * Wrapper around unlink, that explicitly deletes files when existent, but
+     * accepts if they don't. An error is thrown if the files could not be
+     * deleted for other reasons.
+     *
+     * @see https://www.php.net/manual/en/function.unlink.php
+     *
+     * @param non-empty-string $filename File path.
+     *
+     * @return void
+     */
+    public static function unlink_if_exists(string $filename):void {
+
+        if (!\file_exists($filename)) return;
+
+        self::unlink($filename);
+
+    }
+
     /**
      * Gets contents of a folder.
      *
@@ -446,6 +465,23 @@ final class MD_STD {
 
     }
 
+    /**
+     * Returns expected user language without making use of a cookie..
+     *
+     * @param non-empty-array<non-empty-string> $allowed_langs Allowed languages.
+     * @param non-empty-string                  $default_lang  Default language.
+     *
+     * @return non-empty-string
+     */
+    public static function get_user_lang_no_cookie(array $allowed_langs, string $default_lang):string {
+
+        if (isset($_GET['navlang']) and in_array($_GET['navlang'], $allowed_langs, true)) {
+            return $_GET['navlang'];
+        }
+        return $lang = self::lang_getfrombrowser($allowed_langs, $default_lang, "", false);
+
+    }
+
     /**
      * Function lang_getfrombrowser gets the browser language based on HTTP headers.
      *
@@ -455,7 +491,7 @@ final class MD_STD {
      * @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
+     * @return non-empty-string
      */
     public static function lang_getfrombrowser(array $allowed_languages, string $default_language, string $lang_variable = "", bool $strict_mode = true):string {
 
@@ -685,7 +721,7 @@ final class MD_STD {
      */
     public static function ensure_file(string $filepath, array $accepted_mimetype = []):void {
 
-        if (!\file_exists($filepath)) {
+        if (!\is_file($filepath)) {
             throw new MDFileDoesNotExist("File " . basename($filepath) . " does not exist");
         }
 

src/MD_STD_IN.php

@@ -113,7 +113,7 @@ final class MD_STD_IN {
      *
      * @param array<mixed> $inputs Input array.
      *
-     * @return array<integer>
+     * @return list<integer>
      */
     public static function sanitize_id_array(array $inputs):array {