Improved Docs & added 'getSocket()'

* Improved Docs * Added `getSocket()` function * Variables Cleanup
felixms · Jun 3, 2016 · 5fc00ef · 5fc00ef
1 parent ffed65f
commit 5fc00ef
Show file tree

Hide file tree

Showing 2 changed files with 74 additions and 56 deletions.
diff --git a/README.md b/README.md
@@ -1,21 +1,21 @@
 # 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.
 <br>
 <br>
 ## 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: |
 |33905          | Arma 2        | :white_check_mark: |
 <br>
 <br>
 ## Requirements
-ARC 2.1 requires **PHP 5.4** or higher, nothing more! (*For <b>PHP 5.3</b> 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 <b>PHP 5.3</b> support use [ARC 1.3](https://github.com/Nizarii/arma-rcon-class-php/tree/ARC-1.3))*
 <br>
 <br>
 ## Installation 
@@ -35,26 +35,31 @@ Just include ARC in your project: `require_once 'arc.php';`
 <br>
 ## 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.
+<br><br>
 #### 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!*
+<br>
+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(); 
+//...
 ```
 <br>
 ## 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*
 <br>
 <br>
 ## 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.
diff --git 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()