index/src/Environment.php

<?php
// Environment.php
// Created: 2021-04-30
// Updated: 2022-02-27

namespace Index;

use RuntimeException;

/**
 * Provides information about the current runtime environment.
 */
final class Environment {
    /**
     * Contains the end-of-line sequence for the current platform.
     *
     * @var string
     */
    public const NEWLINE = PHP_EOL;

    /**
     * Contains the amount of bytes in an integer for this system.
     *
     * @var int
     */
    public const INT_SIZE = PHP_INT_SIZE;

    private static ?Version $indexVersion = null;
    private static ?Version $phpVersion = null;
    private static array $phpVersions = [];

    /**
     * Checks whether the current PHP environment is running in debug mode.
     *
     * Essentially checks if any sort of error reporting is enabled. It shouldn't be in prod.
     *
     * @return bool true if the environment is in debug mode, false is not.
     */
    public static function isDebug(): bool {
        return error_reporting() !== 0;
    }

    /**
     * Toggles debug mode.
     *
     * Essentially turns all error reporting on or off.
     *
     * @param bool $debug true if debug mode should be enabled, false if it should be disabled.
     */
    public static function setDebug(bool $debug = false): void {
        if($debug) {
            ini_set('display_errors', 'on');
            error_reporting(-1);
        } else {
            ini_set('display_errors', 'off');
            error_reporting(0);
        }
    }

    /**
     * Reads an environment variable.
     *
     * @param string $name Name of the environment variable.
     * @param bool $localOnly true if only variables local to the application should be read,
     *                        false if greater level operating system variables should be included.
     * @return ?string null if the variable doesn't exist, otherwise a string of the value.
     */
    public static function getVariable(string $name, bool $localOnly = true): ?string {
        return ($value = getenv($name, $localOnly)) === false ? null : $value;
    }

    /**
     * Writes an application-local environment variable.
     *
     * @param string $name Name of the environment variable.
     * @param mixed $value Value that should be assigned to the environment variable. Will be cast to a string.
     */
    public static function setVariable(string $name, mixed $value): void {
        putenv($name . '=' . ((string)$value));
    }

    /**
     * Removes an application-local environment variable.
     *
     * @param string $name Name of the environment variable.
     */
    public static function removeVariable(string $name): void {
        putenv($name);
    }

    /**
     * Gets the current version of the Index library.
     *
     * Parses the VERSION in the root of the Index directory.
     *
     * @return Version A Version instance representing the version of the Index Library.
     */
    public static function getIndexVersion(): Version {
        if(self::$indexVersion === null)
            self::$indexVersion = Version::parse(trim(file_get_contents(NDX_ROOT . DIRECTORY_SEPARATOR . 'VERSION')));
        return self::$indexVersion;
    }

    /**
     * Gets the version of the PHP installation Index is running on.
     *
     * @return Version A Version instance representing the version of PHP.
     */
    public static function getPHPVersion(): Version {
        if(self::$phpVersion === null)
            self::$phpVersion = new Version(PHP_MAJOR_VERSION, PHP_MINOR_VERSION, PHP_RELEASE_VERSION);
        return self::$phpVersion;
    }

    /**
     * Gets the version of a PHP extension.
     *
     * @param string $extension Name of the extension.
     * @return ?Version null if the extension is not installed, otherwise an instance of Version representing the version of the extension.
     */
    public static function getPHPExtensionVersion(string $extension): ?Version {
        if(!isset(self::$phpVersions[$extension])) {
            $rawVersion = phpversion($extension);
            self::$phpVersions[$extension] = empty($rawVersion) ? Version::empty() : Version::parse($rawVersion);
        }
        return self::$phpVersions[$extension];
    }

    /**
     * Gets the name of the Operating System PHP is running on.
     *
     * @return string Name of the Operating System.
     */
    public static function getOSName(): string {
        static $value = null;
        $value ??= php_uname('s');
        return $value;
    }

    /**
     * Checks if we're running on Windows.
     *
     * @return bool true if we're running on Windows, otherwise false.
     */
    public static function isWindows(): bool {
        return self::isWindowsNT()
            || self::getOSName() === 'Windows';
    }

    /**
     * Checks if we're running on Windows NT.
     *
     * @return bool true if we're running on Windows NT, otherwise false.
     */
    public static function isWindowsNT(): bool {
        return ($os = self::getOSName()) === 'Windows NT'
            || $os === 'Windows_NT'
            || $os === 'WindowsNT';
    }

    /**
     * Checks if we're running on a Unix-like Operating System.
     *
     * @return bool true if we're running on a Unix-like Operating System, otherwise false.
     */
    public static function isUnixLike(): bool {
        return self::isLinux()
            || self::isBSD()
            || self::isMacOS()
            || self::isSolaris();
    }

    /**
     * Checks if we're running on a BSD derivative.
     *
     * @return bool true if we're running on a BSD derivative, otherwise false.
     */
    public static function isBSD(): bool {
        return self::isOpenBSD()
            || self::isFreeBSD()
            || self::isNetBSD()
            || self::isDragonFlyBSD()
            || self::getOSName() === 'BSD';
    }

    /**
     * Checks if we're running on OpenBSD.
     *
     * @return bool true if we're running on OpenBSD, otherwise false.
     */
    public static function isOpenBSD(): bool {
        return self::getOSName() === 'OpenBSD';
    }

    /**
     * Checks if we're running on FreeBSD.
     *
     * @return bool true if we're running on FreeBSD, otherwise false.
     */
    public static function isFreeBSD(): bool {
        return self::getOSName() === 'FreeBSD';
    }

    /**
     * Checks if we're running on NetBSD.
     *
     * @return bool true if we're running on NetBSD, otherwise false.
     */
    public static function isNetBSD(): bool {
        return self::getOSName() === 'NetBSD';
    }

    /**
     * Checks if we're running on DragonFly BSD.
     *
     * @return bool true if we're running on DragonFly BSD, otherwise false.
     */
    public static function isDragonFlyBSD(): bool {
        return self::getOSName() === 'DragonFly';
    }

    /**
     * Checks if we're running on macOS.
     *
     * @return bool true if we're running on macOS, otherwise false.
     */
    public static function isMacOS(): bool {
        return self::getOSName() === 'Darwin';
    }

    /**
     * Checks if we're running on Solaris.
     *
     * @return bool true if we're running on Solaris, otherwise false.
     */
    public static function isSolaris(): bool {
        return self::getOSName() === 'SunOS';
    }

    /**
     * Checks if we're running on Linux.
     *
     * @return bool true if we're running on Linux, otherwise false.
     */
    public static function isLinux(): bool {
        return self::getOSName() === 'Linux';
    }

    /**
     * Returns the name of the SAPI PHP is currently running through.
     *
     * @return string Name of the SAPI.
     */
    public static function getSAPIName(): string {
        static $sapi = null;
        $sapi ??= php_sapi_name();
        return $sapi;
    }

    /**
     * Checks if we're running through Apache2Handler.
     *
     * @return bool true if we're running through Apache2Handler, otherwise false.
     */
    public static function isApache2(): bool {
        return ($sapi = self::getSAPIName()) === 'apache' || $sapi === 'apache2handler';
    }

    /**
     * Checks if we're running through CGI.
     *
     * @return bool true if we're running through CGI, otherwise false.
     */
    public static function isCGI(): bool {
        return self::getSAPIName() === 'cgi';
    }

    /**
     * Checks if we're running through FastCGI (and/or php-fpm).
     *
     * @return bool true if we're running through FastCGI, otherwise false.
     */
    public static function isFastCGI(): bool {
        return ($sapi = self::getSAPIName()) === 'cgi-fcgi' || $sapi === 'fpm-fcgi';
    }

    /**
     * Checks if we're running through console.
     *
     * @return bool true if we're running through console, otherwise false.
     */
    public static function isConsole(): bool {
        return self::getSAPIName() === 'cli';
    }

    /**
     * Checks if we're running through the built-in development server.
     *
     * @return bool true if we're running through the built-in development server, otherwise false.
     */
    public static function isDebugServer(): bool {
        return self::getSAPIName() === 'cli-server';
    }

    /**
     * Checks if we're running through LiteSpeed.
     *
     * @return bool true if we're running through LiteSpeed, otherwise false.
     */
    public static function isLiteSpeed(): bool {
        return self::getSAPIName() === 'litespeed';
    }

    /**
     * Checks if we're running through PHPDBG.
     *
     * @return bool true if we're running through PHPDBG, otherwise false.
     */
    public static function isPHPDebugger(): bool {
        return self::getSAPIName() === 'phpdbg';
    }

    /**
     * Checks if we're running on a 32-bit system.
     *
     * @return bool true if we're on 32-bit, false if not.
     */
    public static function is32Bit(): bool {
        return PHP_INT_SIZE === 4;
    }

    /**
     * Checks if we're running on a 64-bit system.
     *
     * @return bool true if we're on 64-bit, false if not.
     */
    public static function is64Bit(): bool {
        return PHP_INT_SIZE === 8;
    }
}