General update on documentation

Also fixes some bugs (See #18 and #17) and other bugs that had not been detected before.
Also some micro-optimizations

src/Abstracts/TelegramMethods.php

@@ -48,6 +48,19 @@ public function performSpecialConditions(): TelegramMethods
             $this->reply_markup = json_encode($this->reply_markup);
         }
 
+        // Several classes may send a parse mode, so check before sending
+        // TODO Do I want to validate data in here? Should I?
+        /*
+         * if (!empty($this->parse_mode)) {
+            if (strtoupper($this->parse_mode) !== 'HTML' || strtoupper($this->parse_mode) !== 'MARKDOWN') {
+                throw new InvalidParseMode(sprintf(
+                    'An invalid value for parse_mode has been given. Please use HTML or Markdown. Provided: "%s"',
+                    $this->parse_mode
+                ));
+            }
+        }
+         */
+
         return $this;
     }
 

src/Abstracts/TelegramTypes.php

@@ -10,16 +10,16 @@
 
 abstract class TelegramTypes
 {
-    protected $logger = null;
+    protected $logger;
 
     public function __construct(array $data = null, LoggerInterface $logger = null)
     {
-        if (is_null($logger)) {
+        if ($logger === null) {
             $logger = new DummyLogger();
         }
 
         $this->logger = $logger;
-        if (!is_null($data)) {
+        if ($data !== null) {
             $this->populateObject($data);
         }
     }

src/Telegram/Methods/AnswerCallbackQuery.php

@@ -14,7 +14,11 @@
  * Use this method to send answers to callback queries sent from inline keyboards. The answer will be displayed to the
  * user as a notification at the top of the chat screen or as an alert. On success, True is returned.
  *
- * Objects defined as-is july 2016
+ * Alternatively, the user can be redirected to the specified Game URL. For this option to work, you must first create a
+ * game for your bot via BotFather and accept the terms. Otherwise, you may use links like
+ * telegram.me/your_bot?start=XXXX that open your bot with a parameter
+ *
+ * Objects defined as-is January 2017
  *
  * @see https://core.telegram.org/bots/api#answercallbackquery
  */

src/Telegram/Methods/EditMessageCaption.php

@@ -4,8 +4,14 @@
 
 namespace unreal4u\TelegramAPI\Telegram\Methods;
 
+use Psr\Log\LoggerInterface;
 use unreal4u\TelegramAPI\Abstracts\TelegramMethods;
+use unreal4u\TelegramAPI\Abstracts\TelegramTypes;
+use unreal4u\TelegramAPI\Exceptions\InvalidResultType;
+use unreal4u\TelegramAPI\InternalFunctionality\TelegramRawData;
+use unreal4u\TelegramAPI\Telegram\Types\Custom\ResultBoolean;
 use unreal4u\TelegramAPI\Telegram\Types\Inline\Keyboard\Markup;
+use unreal4u\TelegramAPI\Telegram\Types\Message;
 
 /**
  * Use this method to edit captions of messages sent by the bot or via the bot (for inline bots). On success, if edited
@@ -46,11 +52,24 @@ class EditMessageCaption extends TelegramMethods
      * Optional. A JSON-serialized object for an inline keyboard.
      * @var Markup
      */
-    public $reply_markup = null;
+    public $reply_markup;
 
     public function getMandatoryFields(): array
     {
         $returnValue = [];
         return $this->mandatoryUserOrInlineMessageId($returnValue);
     }
+
+    public static function bindToObject(TelegramRawData $data, LoggerInterface $logger): TelegramTypes
+    {
+        $typeOfResult = $data->getTypeOfResult();
+        switch ($typeOfResult) {
+            case 'array':
+                return new Message($data->getResult(), $logger);
+            case 'boolean':
+                return new ResultBoolean($data->getResultBoolean(), $logger);
+            default:
+                throw new InvalidResultType('Result is of type: %s. Expecting one of array or boolean');
+        }
+    }
 }

src/Telegram/Methods/EditMessageReplyMarkup.php

@@ -4,8 +4,14 @@
 
 namespace unreal4u\TelegramAPI\Telegram\Methods;
 
+use Psr\Log\LoggerInterface;
 use unreal4u\TelegramAPI\Abstracts\TelegramMethods;
+use unreal4u\TelegramAPI\Abstracts\TelegramTypes;
+use unreal4u\TelegramAPI\Exceptions\InvalidResultType;
+use unreal4u\TelegramAPI\InternalFunctionality\TelegramRawData;
+use unreal4u\TelegramAPI\Telegram\Types\Custom\ResultBoolean;
 use unreal4u\TelegramAPI\Telegram\Types\Inline\Keyboard\Markup;
+use unreal4u\TelegramAPI\Telegram\Types\Message;
 
 /**
  * Use this method to edit only the reply markup of messages sent by the bot or via the bot (for inline bots). On
@@ -40,11 +46,24 @@ class EditMessageReplyMarkup extends TelegramMethods
      * Optional. A JSON-serialized object for an inline keyboard.
      * @var Markup
      */
-    public $reply_markup = null;
+    public $reply_markup;
 
     public function getMandatoryFields(): array
     {
         $returnValue = [];
         return $this->mandatoryUserOrInlineMessageId($returnValue);
     }
+
+    public static function bindToObject(TelegramRawData $data, LoggerInterface $logger): TelegramTypes
+    {
+        $typeOfResult = $data->getTypeOfResult();
+        switch ($typeOfResult) {
+            case 'array':
+                return new Message($data->getResult(), $logger);
+            case 'boolean':
+                return new ResultBoolean($data->getResultBoolean(), $logger);
+            default:
+                throw new InvalidResultType('Result is of type: %s. Expecting one of array or boolean');
+        }
+    }
 }

src/Telegram/Methods/EditMessageText.php

@@ -4,8 +4,14 @@
 
 namespace unreal4u\TelegramAPI\Telegram\Methods;
 
+use Psr\Log\LoggerInterface;
 use unreal4u\TelegramAPI\Abstracts\TelegramMethods;
+use unreal4u\TelegramAPI\Abstracts\TelegramTypes;
+use unreal4u\TelegramAPI\Exceptions\InvalidResultType;
+use unreal4u\TelegramAPI\InternalFunctionality\TelegramRawData;
+use unreal4u\TelegramAPI\Telegram\Types\Custom\ResultBoolean;
 use unreal4u\TelegramAPI\Telegram\Types\Inline\Keyboard\Markup;
+use unreal4u\TelegramAPI\Telegram\Types\Message;
 
 /**
  * Use this method to edit text messages sent by the bot or via the bot (for inline bots). On success, if edited message
@@ -59,12 +65,25 @@ class EditMessageText extends TelegramMethods
      * Optional. A JSON-serialized object for an inline keyboard.
      * @var Markup
      */
-    public $reply_markup = null;
+    public $reply_markup;
 
     public function getMandatoryFields(): array
     {
         $returnValue[] = 'text';
         $this->mandatoryUserOrInlineMessageId($returnValue);
         return $returnValue;
     }
+
+    public static function bindToObject(TelegramRawData $data, LoggerInterface $logger): TelegramTypes
+    {
+        $typeOfResult = $data->getTypeOfResult();
+        switch ($typeOfResult) {
+            case 'array':
+                return new Message($data->getResult(), $logger);
+            case 'boolean':
+                return new ResultBoolean($data->getResultBoolean(), $logger);
+            default:
+                throw new InvalidResultType('Result is of type: %s. Expecting one of array or boolean');
+        }
+    }
 }

src/Telegram/Methods/GetUpdates.php

@@ -11,19 +11,9 @@
 use unreal4u\TelegramAPI\Telegram\Types\Custom\UpdatesArray;
 
 /**
- * This will get the updates Telegram has for our bot
+ * Use this method to receive incoming updates using long polling (wiki). An Array of Update objects is returned
  *
- * This will work under 3 conditions:
- *
- * <ul>
- *  <li>No more than 24 hours has passed since the last update</li>
- *  <li>No webhooks are configured</li>
- *  <li>There are available updates (doh)</li>
- * </ul>
- *
- * You can use this method to get the channel id the bot has to send messages to
- *
- * Objects defined as-is December 2016
+ * Objects defined as-is January 2017
  *
  * @see https://core.telegram.org/bots/api#getupdates
  */
@@ -32,7 +22,9 @@ class GetUpdates extends TelegramMethods
     /**
      * Identifier of the first update to be returned. Must be greater by one than the highest among the identifiers of
      * previously received updates. By default, updates starting with the earliest unconfirmed update are returned. An
-     * update is considered confirmed as soon as getUpdates is called with an offset higher than its update_id.
+     * update is considered confirmed as soon as getUpdates is called with an offset higher than its update_id. The
+     * negative offset can be specified to retrieve updates starting from -offset update from the end of the updates
+     * queue. All previous updates will forgotten
      * @var int
      */
     public $offset = 0;

src/Telegram/Methods/SendAudio.php

@@ -17,7 +17,7 @@
  * .ogg file encoded with OPUS. This behavior will be phased out in the future. For sending voice messages, use the
  * sendVoice method instead.
  *
- * Objects defined as-is july 2016
+ * Objects defined as-is January 2017
  *
  * @see https://core.telegram.org/bots/api#sendaudio
  */
@@ -30,12 +30,14 @@ class SendAudio extends TelegramMethods
     public $chat_id = '';
 
     /**
-     * Audio file to send. Associate an InputFile with it
+     * Audio file to send. Pass a file_id as String to send an audio file that exists on the Telegram servers
+     * (recommended), pass an HTTP URL as a String for Telegram to get an audio file from the Internet, or upload a new
+     * one using the InputFile class
      *
-     * @see unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile
-     * @var InputFile
+     * @see InputFile
+     * @var string|InputFile
      */
-    public $audio = null;
+    public $audio = '';
 
     /**
      * Optional. Audio caption, 0-200 characters

src/Telegram/Methods/SendChatAction.php

@@ -4,7 +4,11 @@
 
 namespace unreal4u\TelegramAPI\Telegram\Methods;
 
+use Psr\Log\LoggerInterface;
 use unreal4u\TelegramAPI\Abstracts\TelegramMethods;
+use unreal4u\TelegramAPI\Abstracts\TelegramTypes;
+use unreal4u\TelegramAPI\InternalFunctionality\TelegramRawData;
+use unreal4u\TelegramAPI\Telegram\Types\Custom\ResultBoolean;
 
 /**
  * Use this method when you need to tell the user that something is happening on the bot's side. The status is set for 5
@@ -42,4 +46,9 @@ public function getMandatoryFields(): array
             'action',
         ];
     }
+
+    public static function bindToObject(TelegramRawData $data, LoggerInterface $logger): TelegramTypes
+    {
+        return new ResultBoolean($data->getResultBoolean(), $logger);
+    }
 }

src/Telegram/Methods/SendContact.php

@@ -4,6 +4,7 @@
 
 namespace unreal4u\TelegramAPI\Telegram\Methods;
 
+use unreal4u\TelegramAPI\Abstracts\KeyboardMethods;
 use unreal4u\TelegramAPI\Abstracts\TelegramMethods;
 
 /**
@@ -56,9 +57,9 @@ class SendContact extends TelegramMethods
     /**
      * Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to
      * hide keyboard or to force a reply from the user.
-     * @var null
+     * @var KeyboardMethods
      */
-    public $reply_markup = null;
+    public $reply_markup;
 
     public function getMandatoryFields(): array
     {

src/Telegram/Methods/SendDocument.php

@@ -4,14 +4,15 @@
 
 namespace unreal4u\TelegramAPI\Telegram\Methods;
 
+use unreal4u\TelegramAPI\Abstracts\KeyboardMethods;
 use unreal4u\TelegramAPI\Abstracts\TelegramMethods;
 use unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile;
 
 /**
  * Use this method to send general files. On success, the sent Message is returned. Bots can currently send files of any
  * type of up to 50 MB in size, this limit may be changed in the future.
  *
- * Objects defined as-is july 2016
+ * Objects defined as-is January 2017
  *
  * @see https://core.telegram.org/bots/api#senddocument
  */
@@ -24,14 +25,13 @@ class SendDocument extends TelegramMethods
     public $chat_id = '';
 
     /**
-     * File to send. You can either pass a file_id as String to resend a file that is already on the Telegram servers,
-     * or upload a new file using the InputFile class
+     * File to send. Pass a file_id as String to send a file that exists on the Telegram servers (recommended), pass an
+     * HTTP URL as a String for Telegram to get a file from the Internet, or upload a new one using the InputFile class
      *
-     * @see unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile
-     *
-     * @var InputFile
+     * @see InputFile
+     * @var string|InputFile
      */
-    public $document = null;
+    public $document = '';
 
     /**
      * Optional. Document caption (may also be used when resending documents by file_id), 0-200 characters
@@ -56,9 +56,9 @@ class SendDocument extends TelegramMethods
     /**
      * Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to
      * hide keyboard or to force a reply from the user
-     * @var null
+     * @var KeyboardMethods
      */
-    public $reply_markup = null;
+    public $reply_markup;
 
     public function getMandatoryFields(): array
     {

src/Telegram/Methods/SendLocation.php

@@ -4,6 +4,7 @@
 
 namespace unreal4u\TelegramAPI\Telegram\Methods;
 
+use unreal4u\TelegramAPI\Abstracts\KeyboardMethods;
 use unreal4u\TelegramAPI\Abstracts\TelegramMethods;
 
 /**
@@ -50,9 +51,9 @@ class SendLocation extends TelegramMethods
     /**
      * Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to
      * hide keyboard or to force a reply from the user.
-     * @var null
+     * @var KeyboardMethods
      */
-    public $reply_markup = null;
+    public $reply_markup;
 
     public function getMandatoryFields(): array
     {

src/Telegram/Methods/SendMessage.php

@@ -60,7 +60,7 @@ class SendMessage extends TelegramMethods
      * hide keyboard or to force a reply from the user
      * @var KeyboardMethods
      */
-    public $reply_markup = null;
+    public $reply_markup;
 
     public function getMandatoryFields(): array
     {

src/Telegram/Methods/SendPhoto.php

@@ -5,11 +5,12 @@
 namespace unreal4u\TelegramAPI\Telegram\Methods;
 
 use unreal4u\TelegramAPI\Abstracts\TelegramMethods;
+use unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile;
 
 /**
  * Use this method to send photos. On success, the sent Message is returned
  *
- * Objects defined as-is july 2016
+ * Objects defined as-is January 2017
  *
  * @see https://core.telegram.org/bots/api#sendphoto
  */
@@ -22,12 +23,13 @@ class SendPhoto extends TelegramMethods
     public $chat_id = '';
 
     /**
-     * Photo to send. You can either pass a file_id as String to resend a photo that is already on the Telegram servers,
-     * or upload a new photo using the InputFile class
-     * @see unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile
-     * @var string
+     * Photo to send. Pass a file_id as String to send a photo that exists on the Telegram servers (recommended), pass
+     * an HTTP URL as a String for Telegram to get a photo from the Internet, or upload a new photo using the InputFile
+     * class.
+     * @see InputFile
+     * @var string|InputFile
      */
-    public $photo = null;
+    public $photo = '';
 
     /**
      * Optional. Photo caption (may also be used when resending photos by file_id)
@@ -54,7 +56,7 @@ class SendPhoto extends TelegramMethods
      * hide keyboard or to force a reply from the user
      * @var null
      */
-    public $reply_markup = null;
+    public $reply_markup;
 
     public function getMandatoryFields(): array
     {