From 5fc00ef85d8f0b517664637ff7a2629ec33096ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20Sch=C3=A4fer?= Date: Fri, 3 Jun 2016 15:19:43 +0200 Subject: [PATCH] Improved Docs & added 'getSocket()' * Improved Docs * Added `getSocket()` function * Variables Cleanup --- README.md | 95 +++++++++++++++++++++++++++++++------------------------ arc.php | 35 ++++++++++++-------- 2 files changed, 74 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index b53a669..3eda28b 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ # Arma RCon Class (ARC) 2.1 for PHP [![Codacy](https://img.shields.io/codacy/f42d50a9693b4febb34fab3f68315365.svg)](https://www.codacy.com/app/nizari/arma-rcon-class-php) [![Packagist Version](https://img.shields.io/packagist/v/nizarii/arma-rcon-class.svg)](https://packagist.org/packages/nizarii/arma-rcon-class) -[![GitHub license](https://img.shields.io/github/license/nizarii/arma-rcon-class-php.svg)](https://github.com/Nizarii/arma-rcon-class-php/) +[![GitHub License](https://img.shields.io/github/license/nizarii/arma-rcon-class-php.svg)](https://github.com/Nizarii/arma-rcon-class-php/) ARC is a lightweight PHP class, which allows you connecting and sending commands easily via RCon to your ARMA game server. See "Supported Servers" for a list of supported games.

## Supported Servers -| App ID | Game | RCON Support | +| App ID | Game | RCon Support | |---------------|---------------|:------------------:| |233780 | Arma 3 | :white_check_mark: | |33935 | Arma 2: Operation Arrowhead | :white_check_mark: | @@ -15,7 +15,7 @@ ARC is a lightweight PHP class, which allows you connecting and sending commands

## Requirements -ARC 2.1 requires **PHP 5.4** or higher, nothing more! (*For PHP 5.3 support use [ARC 1.3](https://github.com/Nizarii/arma-rcon-class-php/tree/ARC-1.3)*) +ARC 2.1 requires **PHP 5.4** or higher, nothing more! *(For PHP 5.3 support use [ARC 1.3](https://github.com/Nizarii/arma-rcon-class-php/tree/ARC-1.3))*

## Installation @@ -35,26 +35,31 @@ Just include ARC in your project: `require_once 'arc.php';`
## Examples #### Getting started -After installing ARC, you need to create a new object. It will automatically create a new connection to the server and login: +After installing ARC, you can easily use ARC as shown below. It will automatically establish a new connection to the server and login: ```php -$rcon = new \Nizarii\ARC("Your server IP", "RCon password"); +use \Nizarii\ARC; + +$rcon = new ARC(string $ServerIP, string $RConPassword [, int Port = 2302 [, array $Options = array()]]); ``` -The default port is `2302`. You are able to send commands with the `command()` function: +You are able to send commands with the `command()` function: ```php -$rcon->command("Say -1 hello!"); // To say something in global chat, you may use 'sayGlobal()', see 'Functions' +//... +$rcon->command("YourCommand"); ``` ARC will throw `Exceptions` if anything goes wrong, so you can do a try-catch function: ```php +use \Nizarii\ARC; + try { - $rcon = new \Nizarii\ARC("Your server IP", "RCon password", Port); + $rcon = new ARC('127.0.0.1', 'password'); $array = $rcon->getPlayersArray(); $rcon - ->sayGlobal('test') - ->kickPlayer(1, 'test') - ->sayPlayer(0, 'test') + ->sayGlobal('example') + ->kickPlayer(1, 'example') + ->sayPlayer(0, 'example') ->disconnect() ; @@ -65,48 +70,54 @@ catch (Exception $e) echo "Ups! Something went wrong: {$e->getMessage()}"; } ``` +Please consider that ARC only checks whether the command has been *successfully sent* via the socket to the server. It *does not* check if the command has been executed on the server-side. +

#### Options -ARC can send a heartbeat packet to the server. In order to do this, you need to enable this feature: -```php -$rcon = new \Nizarii\ARC("Your server IP", "RCon password", Port, [ - 'heartbeat' => true, // must be a boolean -]); -``` -Another option is `timeout_seconds`, which sets a timeout value on the connection: +Options can be passed to ARC as an array via the fourth parameter of the constructor. The following options are currently available: +* `bool heartbeat = false`: Send a heartbeat packet to the server +* `int timeout_sec = 1`: Sets a timeout value on the connection + +*Suggestions for new options are always welcome!* +
+Basic options usage: ```php -$rcon = new \Nizarii\ARC("Your server IP", "RCon password", Port, [ - 'timeout_sec' => 1, // must be an integer, by default 1 second +use \Nizarii\ARC; + +$rcon = new ARC('127.0.0.1', 'RCon password', 2322, [ + 'heartbeat' => true, + 'timeout_sec' => 2 ]); -$rcon->writeBans(); +//... ```
## Functions ARC features many functions to send BattlEye commands easier. After creating a new connections as explained above, you are able to use any of these functions: -* `command(string $command)`: Sends any command to the BattlEye server and returns its answer as a string. -* `getPlayers()`: Returns a list of all players online. -* `getPlayersArray()`: Returns an array of all players online. -* `getMissions()`: Returns a list of the available missions on the server. -* `getBans()`: Returns a list of all BE server bans. -* `getBansArray()`: Returns an array of all server bans. -* `kickPlayer(int $player, string $reason = 'Admin Kick')`: Kicks a player who is currently on the server. -* `sayGlobal(string $message)`: Sends a global message to all players. -* `sayPlayer(int $player, string $message)`: Sends a message to a specific player. -* `loadScripts()`: Loads the "scripts.txt" file without the need to restart the server. -* `maxPing(int $ping)`: Changes the MaxPing value. If a player has a higher ping, he will be kicked from the server. -* `changePassword(string $password)`: Changes the RCon password. -* `loadBans()`: (Re)load the BE ban list from bans.txt. -* `banPlayer(string $player, string $reason, int $time = 0)`: Ban a player's BE GUID from the server. If time is not specified or 0, the ban will be permanent; If reason is not specified the player will be kicked with "Banned". -* `addBan(string $player, string $reason, int $time = 0)`: Same as "banPlayer", but allows to ban a player that is not currently on the server. -* `removeBan(int $banid)`: Removes a ban. -* `writeBans()`: Removes expired bans from bans file. -* `getBEServerVersion()`: Gets the current version of the BE server. -* `disconnect()`: Closes the connection. -* `reconnect()`: Closes the connection & opens a new one. +* `string command(string $command)`: Sends any command to the BattlEye server +* `string getPlayers()`: Gets a list of all players online +* `array getPlayersArray()`: Gets an array of all players online +* `string getMissions()`: Gets a list of the available missions on the server +* `string getBans()`: Gets a list of all BE server bans +* `array getBansArray()`: Gets an array of all bans +* `object kickPlayer(int $player [, string $reason = 'Admin Kick'])`: Kicks a player who is currently on the server +* `object sayGlobal(string $message)`: Sends a global message to all players +* `object sayPlayer(int $player, string $message)`: Sends a message to a specific player +* `object loadScripts()`: Loads the "scripts.txt" file without the need to restart the server +* `object maxPing(int $ping)`: Changes the MaxPing value. If a player has a higher ping, he will be kicked from the server +* `object changePassword(string $password)`: Changes RCon password +* `object loadBans()`: (Re)loads the BE ban list from "bans.txt" +* `object banPlayer(string $player [, string $reason = 'Banned' [, int $time = 0]])`: Ban a player's BE GUID from the server (If the time is 0, the ban will be permanent) +* `object addBan(string $player [, string $reason = 'Banned' [, int $time = 0]])`: Same as "banPlayer()", but allows to ban a player that is not currently on the server +* `object removeBan(int $banid)`: Removes a ban +* `object writeBans()`: Removes expired bans from the bans file +* `object getBEServerVersion()`: Gets the current version of the BE server +* `disconnect()`: Closes the current connection +* `object reconnect()`: Closes the current connection & creates a new one +* `resource getSocket()`: Get the socket used by ARC to send commands *See [here](https://community.bistudio.com/wiki/BattlEye "BattlEye Wiki") for more information about BattlEye*

## License -ARC is licensed under the MIT License. See `LICENSE`-file for further information. +ARC is licensed under the MIT License. See `LICENSE`-file for further information. \ No newline at end of file diff --git a/arc.php b/arc.php index 45d2d07..00cf733 100644 --- a/arc.php +++ b/arc.php @@ -8,7 +8,7 @@ * @since September 26, 2015 * @link https://github.com/Nizarii/arma-rcon-php-class * @license MIT-License - * @version 2.1 + * @version 2.1.1 * */ @@ -54,7 +54,7 @@ class ARC { * * @var string */ - public $RCONpassword; + public $RConPassword; /** @@ -90,18 +90,18 @@ class ARC { * * @param string $serverIP IP of the Arma server * @param integer $serverPort Port of the Arma server - * @param string $RCONpassword RCon password required by BattlEye + * @param string $RConPassword RCon password required by BattlEye * @param array $options Options array of ARC * @throws \Exception If wrong parameter types are passed to the function */ - public function __construct($serverIP, $RCONpassword, $serverPort = 2302, array $options = array()) + public function __construct($serverIP, $RConPassword, $serverPort = 2302, array $options = array()) { - if ( !is_int($serverPort) || !is_string($RCONpassword) || !is_string($serverIP) ) + if ( !is_int($serverPort) || !is_string($RConPassword) || !is_string($serverIP) ) throw new \Exception('[ARC] Wrong parameter type!'); $this->serverIP = $serverIP; $this->serverPort = $serverPort; - $this->RCONpassword = $RCONpassword; + $this->RConPassword = $RConPassword; $this->options = array_merge($this->options, $options); if ( !is_int($this->options['timeout_sec']) ) @@ -228,7 +228,7 @@ private function getAnswer() /** - * The heart of this class - this function actually sends the RCON command + * The heart of this class - this function actually sends the RCon command * * @param $command string The command sent to the server * @return bool Whether sending the command was successful or not @@ -257,7 +257,7 @@ private function send($command) */ private function getAuthCRC() { - $authCRC = sprintf("%x", crc32(chr(255).chr(00).trim($this->RCONpassword))); + $authCRC = sprintf("%x", crc32(chr(255).chr(00).trim($this->RConPassword))); $authCRC = array(substr($authCRC,-2,2),substr($authCRC,-4,2),substr($authCRC,-6,2),substr($authCRC,0,2)); return $authCRC; @@ -289,7 +289,7 @@ private function getLoginMessage() $authCRC = $this->getAuthCRC(); $loginmsg = "BE".chr(hexdec($authCRC[0])).chr(hexdec($authCRC[1])).chr(hexdec($authCRC[2])).chr(hexdec($authCRC[3])); - $loginmsg .= chr(hexdec('ff')).chr(hexdec('00')).$this->RCONpassword; + $loginmsg .= chr(hexdec('ff')).chr(hexdec('00')).$this->RConPassword; return $loginmsg; } @@ -310,6 +310,16 @@ private function sendHeartbeat() } + /** + * Returns the socket used by ARC, might be null if connection is closed + * + * @return null|resource + */ + public function getSocket() { + return $this->socket; + } + + /** * Sends a custom command to the BattlEye server * @@ -472,9 +482,6 @@ public function getPlayersArray() { $playersRaw = $this->getPlayers(); - if ( $playersRaw === false ) - return false; - $players = $this->cleanList($playersRaw); preg_match_all("#(\d+)\s+(\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}:\d+\b)\s+(\d+)\s+([0-9a-fA-F]+)\(\w+\)\s([\S ]+)$#im", $players, $str); $result = $this->formatList($str); @@ -558,7 +565,7 @@ public function removeBan($banid) * * @author nerdalertdk (https://github.com/nerdalertdk) * @link https://github.com/Nizarii/arma-rcon-class-php/issues/4 - * @return array|bool The list of bans or, if sending failed, false + * @return array The list of bans or, if sending failed, false */ public function getBansArray() { @@ -575,7 +582,7 @@ public function getBansArray() /** * Gets a list of all bans * - * @return ARC + * @return string * @throws \Exception If sending the command failed */ public function getBans()