MD_STD/MD_STD.php

<?PHP
/**
 * Provides type-safe overrides of default PHP functions.
 */
declare(strict_types = 1);

/**
 * Standard class providing overrides of default PHP functions as static
 * functions.
 */
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.
     *
     * @return string
     */
    public static function file_get_contents(string $filename):string {

        if (substr($filename, 0, 4) !== 'http' && !file_exists($filename)) {
            throw new MDFileDoesNotExist("There is no file {$filename}");
        }

        $contents = file_get_contents($filename);

        if (is_bool($contents)) {
            throw new MDFileIsNotReadable("File {$filename} is not readable");
        }

        return $contents;

    }

    /**
     * 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.
     *
     * @return string
     */
    public static function realpath(string $path):string {

        $output = realpath($path);
        if (!is_string($output)) throw new MDFileDoesNotExist("The file {$path} does not exist or is not readable.");
        return $output;

    }

    /**
     * Gets contents of a folder.
     *
     * @param string $filepath Directory path.
     *
     * @return array<string>
     */
    public static function scandir(string $filepath):array {

        if (!is_dir($filepath) || ($output = scandir($filepath)) === false) {
            throw new MDFileDoesNotExist("There is no file {$filepath}");
        }

        return array_values(array_diff($output, ['.', '..', '.git']));

    }

    /**
     * Type safe wrapper around ob_get_clean():  Gets the current buffer
     * contents and delete current output buffer.
     *
     * @return string
     */
    public static function ob_get_clean():string {

        $output = ob_get_clean();
        if ($output === false) throw new MDOutputBufferNotStarted("Output buffer was not started");
        return $output;

    }

    /**
     * Function checking if a string starts with another.
     *
     * @param string $haystack String to check.
     * @param string $needle   Potential start of $haystack.
     *
     * @return boolean
     */
    public static function startsWith(string $haystack, string $needle):bool {

        if (substr($haystack, 0, strlen($needle)) == $needle) return true;
        else return false;

    }

    /**
     * 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.
     *
     * @return boolean
     */
    public static function startsWithAny(string $haystack, array $needles):bool {

        $output = false;
        foreach ($needles as $needle) {
            $output = self::startsWith($haystack, $needle);
            if ($output == true) return $output;
        }
        return $output;

    }

    /**
     * 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.
     *
     * @return string
     */
    public static function preg_replace_str(string $pattern, string $replacement, string $subject):string {

        $output = preg_replace($pattern, $replacement, $subject);
        if ($output === null) {
            throw new Exception("Error replacing in $subject: Replacing $pattern with $replacement");
        }

        return $output;

    }

    /**
     * Type-safe wrapper around json_encode.
     *
     * @see https://www.php.net/manual/en/function.json-encode.php
     *
     * @param array<mixed> $value   The value being encoded. Can be any type except a resource.
     * @param integer      $options Bitmask consisting of JSON_FORCE_OBJECT, JSON_HEX_QUOT ...
     * @param integer      $depth   Depth of coding.
     *
     * @return string
     */
    public static function json_encode(array $value, int $options = 0, int $depth = 512):string {

        $output = json_encode($value, $options, $depth);
        if ($output === false) throw new Exception("JSON output could not be generated");
        return $output;

    }

    /**
     * Wrapper for curling contents from the web.
     *
     * @param string  $url     URL to query.
     * @param integer $timeout Timeout in milliseconds.
     *
     * @return string
     */
    public static function runCurl(string $url, int $timeout = 1200):string {

        $curl = curl_init();

        curl_setopt($curl, CURLOPT_URL, $url);
        curl_setopt($curl, CURLOPT_HEADER, false);
        curl_setopt($curl, CURLOPT_CONNECTTIMEOUT_MS, $timeout); //timeout in seconds
        curl_setopt($curl, CURLOPT_TIMEOUT_MS, $timeout);        //timeout in seconds
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
        curl_setopt($curl, CURLOPT_USERAGENT, 'md-bot/1.0');
        $result = curl_exec($curl);

        curl_close($curl);
        if (is_bool($result)) return "";
        return $result;

    }

}