From b7939127e11d5df98188b4ece0fada81377782c3 Mon Sep 17 00:00:00 2001 From: Marcel Naeve Date: Mon, 11 Nov 2024 01:21:06 +0100 Subject: [PATCH] continued to document the classes and functions. --- scripts/class.FactorioVersion.php | 52 ++++++++++++++++++---- scripts/class.Systemctl.php | 4 ++ scripts/class.TerminalMessage.php | 37 +++++++++++++++- scripts/class.ValveRcon.php | 71 ++++++++++++++++++++++++++++++- scripts/func.downloadFile.php | 12 ++++-- 5 files changed, 160 insertions(+), 16 deletions(-) diff --git a/scripts/class.FactorioVersion.php b/scripts/class.FactorioVersion.php index ec5651d..c4d0f63 100644 --- a/scripts/class.FactorioVersion.php +++ b/scripts/class.FactorioVersion.php @@ -1,19 +1,34 @@ + * @license MIT License (http://www.opensource.org/licenses/mit) + */ class FactorioVersion { + /** + * @var string The Factorio Version + */ private $version; + + /** + * @var int The Factorio version converted to an comparable integer. + */ private $intVersion; /** - * Füllt eine Zeichenkette am anfang mit Nullen auf bis die Ziellänge erreicht ist. - * @param string Zu füllende Zeichenkette - * @param int Ziellänge der gefüllten Zeichenkette - * @return string die Zeichenkette mit Nullen vorne angefügt um die Ziellänge zu erreichen + * Fills a string with zeros at the beginning till string length matches the target length. + * @param string $str string to fill + * @param int $target_length Target length of the string + * @return string string with zeros at the beginning till string length matches */ private function zero_fill(string $str, int $target_length) { @@ -30,9 +45,9 @@ class FactorioVersion { } /** - * Formatiert die Factorio Versionsnummern um zu einem Vergleichbaren Integer. - * @param string Factorio Versions Zeichenkette Beispiel: 2.0.14 - * @return int zum einfachen Vergleich formatierter Versions-Integer. Beispiel: versionsFormat("2.0.14") -> "000200000014" -> int(200000014) + * Formats the Factorio version string to a comparable integer. + * @param string $vs Factorio version string (example: 2.0.14) + * @return int factorio version as comparable integer (example: versionFormat("2.0.14") -> "000200000014" -> int(200000014)) */ private function versionFormat(string $vs) : int { @@ -47,24 +62,43 @@ class FactorioVersion { } - + /** + * Constructor. + * @param string $version Factorio version string (example: 2.0.14) + */ public function __construct(string $version) { $this->version = $version; $this->intVersion = $this->versionFormat($version); } + /** + * Returns the Factorio version string (example: 2.0.14). + * @return string Factorio version string (example: 2.0.14) + */ public function getVersion() : string { return $this->version; } + /** + * Returns the Factorio version as a comparable integer (example: versionFormat("2.0.14") -> int(200000014)). + * @return integer Factorio version as a comparable integer (example: versionFormat("2.0.14") -> int(200000014)). + */ public function getIntVersion() : int { return $this->intVersion; } + /** + * Checks if the current Factorio version is newer than another version. + * @param FactorioVersion $other Another FactorioVersion object + */ public function isNewer(FactorioVersion $other) : bool { return $this->intVersion > $other->getIntVersion(); } + /** + * Checks if the current Factorio version is older than another version. + * @param FactorioVersion $other Another FactorioVersion object + */ public function isOlder(FactorioVersion $other) : bool { return $this->intVersion < $other->getIntVersion(); } diff --git a/scripts/class.Systemctl.php b/scripts/class.Systemctl.php index cd6fe51..e3ef1aa 100644 --- a/scripts/class.Systemctl.php +++ b/scripts/class.Systemctl.php @@ -1,5 +1,9 @@ + * @license MIT License (http://www.opensource.org/licenses/mit) + */ class TerminalMessage { + /** + * Send a message to the terminal ending with a line break at the end. + * @param string $msg The message to send. + */ public function send(string $msg) { echo $msg . PHP_EOL; } + /** + * Send a title to the terminal with a specified layer and and a double line break at the end. + * @param string $msg The title message to send. + * @param string $layer The layer (default: 0) + */ public function sendTitle(string $msg, int $layer=0) { $layerString = "#"; for($i=0; $i<$layer; $i++) { $layerString .= "#"; } self::send( "\033[1m[$layerString] $msg\033[0m" . PHP_EOL ); - } + /** + * Send a success message to the terminal with a green color and a line break at the end. + * @param string $msg The success message to send. + */ public function sendSuccess(string $msg) { self::send( "\033[1;32m[SUCCESS] $msg\033[0m" ); } + /** + * Send an info message to the terminal with a blue color and a line break at the end. + * @param string $msg The info message to send. + */ public function sendInfo(string $msg) { self::send( "\033[1;34m[INFO] $msg\033[0m" ); } + /** + * Send an error message to the terminal with a red color and a line break at the end. + * @param string $msg The error message to send. + * @param bool $critical If true, the script will terminate with a non-zero exit code (default: false). + */ public function sendError(string $msg, bool $critical=false) { self::send( "\033[1;31m[ERROR] $msg\033[0m" ); if ($critical) { @@ -32,6 +62,11 @@ class TerminalMessage { } } + /** + * Send a warning message to the terminal with a yellow color and a line break at the end. + * @param string $msg The warning message to send. + * @param bool $critical If true, the script will terminate with a non-zero exit code (default: false). + */ public function sendWarning(string $msg, bool $critical=false) { self::send( "\033[1;33m[WARNING] $msg\033[0m" ); if ($critical) { diff --git a/scripts/class.ValveRcon.php b/scripts/class.ValveRcon.php index 91c13ed..cc24ef1 100644 --- a/scripts/class.ValveRcon.php +++ b/scripts/class.ValveRcon.php @@ -1,17 +1,55 @@ + * @license MIT License (http://www.opensource.org/licenses/mit) + */ class ValveRcon { + /** + * @var string IP address of the RCON server + */ private $ip; + + /** + * @var int Port number of the RCON server + */ private $port; + + /** + * @var string Password to authenticate with the RCON server + */ private $password; + + /** + * @var int Timeout for socket operations in seconds + */ private $timeout; + /** + * @var resource Socket resource for RCON communication + */ private $socket; + + /** + * @var array Error details if any occurs during communication + */ private $err; + /** + * Constructor, setting variables. + * @param string $ip IP address of the RCON server + * @param int $port Port number of the RCON server + * @param string $password Password to authenticate with the RCON server + * @param int $timeout Timeout for socket operations in seconds (default: 2 seconds) + */ public function __construct(string $ip, int $port, string $password, int $timeout=2) { $this->ip = $ip; $this->port = $port; @@ -19,12 +57,17 @@ class ValveRcon { $this->timeout = $timeout; } + /** + * Establishes a connection to the RCON server. + * @return bool Connection established successfully? + */ private function connect() : bool { + // prepare variables for error handling $errno = null; $errmsg = ""; - $this->socket = fsockopen( + $this->socket = fsockopen( // connect to RCON server "udp://{$this->ip}", $this->port, $errno, @@ -32,7 +75,7 @@ class ValveRcon { $this->timeout ); - if(!$this->socket) { + if(!$this->socket) { // connection failed? $this->err = [ "code" => $errno, "message" => "Socket connection failed: $errmsg" @@ -44,6 +87,9 @@ class ValveRcon { } + /** + * Closes the connection to the RCON server + */ private function disconnect() : void { if ( $this->isConnected() ) { @@ -53,12 +99,19 @@ class ValveRcon { } + /** + * Checks if the connection to the RCON server is established. + */ private function isConnected() : bool { return ( get_resource_type($this->socket) !== null ); // check if socket is resource type, as it should be } + /** + * Receives data from the RCON server. + * @return string|null Received data or null if no data is available + */ private function read() : ?string { if (!$this->isConnected()) { @@ -82,6 +135,10 @@ class ValveRcon { } + /** + * Writes a command to the RCON server. + * @return bool $cmd Command writen successfully? + */ private function write(string $cmd) : bool { if (!$this->isConnected()) { @@ -96,6 +153,12 @@ class ValveRcon { } + /** + * Sends a command to the RCON server and optionally reads the response. + * @param string $cmd Command to send to the RCON server + * @param bool $read Should the response be read from the RCON server? (default: false) + * @return string|null Response from the RCON server or null if no response is expected or read fails + */ public function sendCommand(string $cmd, bool $read=false) : ?string { $this->connect(); @@ -125,6 +188,10 @@ class ValveRcon { } + /** + * Returns the last error details if any occurred during communication. + * @return object|null Last error details or null if no error has occurred (error object contains code and message as properties) + */ public function getError() :?object { if($this->err === null) { diff --git a/scripts/func.downloadFile.php b/scripts/func.downloadFile.php index f992696..1249a55 100644 --- a/scripts/func.downloadFile.php +++ b/scripts/func.downloadFile.php @@ -1,12 +1,16 @@