Merge pull request #264 from noplanman/improve_example_inline_comments

Update inline comments for hook.php and getUpdatesCLI.php

doc/01-utils.md

 ## Logging
-Telegram bot library feats [Monolog](https://github.com/Seldaek/monolog) to store logs.
+PHP Telegram Bot library features [Monolog](https://github.com/Seldaek/monolog) to store logs.
 
-Logs are divided in those streams:
+Logs are divided into the following streams:
 ### Error
-Collects all the exceptions throwned by the library:
-
+Collects all the exceptions thrown by the library:
 ```php
 TelegramLog::initErrorLog($path . '/' . $BOT_NAME . '_error.log');
 ```
 
 ### Debug
-Stores Curl messages with the server, useful for debugging:
-
+Stores requests made to the Telegram API, useful for debugging:
 ```php
 TelegramLog::initDebugLog($path . '/' . $BOT_NAME . '_debug.log');
 ```
 
 ### Raw data
-Incoming updates (json string from webhook and getUpdates) can be logged in a text file. Set this option with the methods:
+Incoming updates (JSON string from Webhook and getUpdates) get logged in a text file:
 ```php
 TelegramLog::initUpdateLog($path . '/' . $BOT_NAME . '_update.log');
 ```
-Why I need raw log?  
-Telegram api changes continuously and often happen that db schema is not uptodate with new entities/features. So can happen that your table schema would not be able to store valuable new information coming from Telegram.
+Why do I need to log the raw updates?
+Telegram API changes continuously and it often happens that the database schema is not up to date with new entities/features. So it can happen that your table schema doesn't allow storing new valuable information coming from Telegram.
 
-If you store raw data you can port all updates on the newest table schema just using [this script](../utils/importFromLog.php).
-Remember always backup first!!
+If you store the raw data you can import all updates on the newest table schema by simply using [this script](../utils/importFromLog.php).
+Remember to always backup first!!
 
 ## Stream and external sources
-Error and Debug streams relies on the `bot_log` instance that can be provided from an external source:
-
+Error and Debug streams rely on the `bot_log` instance that can be provided from an external source:
 ```php
 TelegramLog::initialize($monolog);
 ```
 
-Raw data relies on the `bot_update_log` instance that feats a custom format for this kind of logs.
+Raw data relies on the `bot_update_log` instance that uses a custom format.

examples/getUpdatesCLI.php

 #!/usr/bin/env php
 <?php
-//README
-//This configuration file is intented to run the bot with the webhook method
-//Uncommented parameters must be filled
+/**
+ * README
+ * This configuration file is intented to run the bot with the getUpdates method
+ * Uncommented parameters must be filled
+ */
 
-//bash script
-//while true; do ./getUpdatesCLI.php; done
+// Bash script
+// while true; do ./getUpdatesCLI.php; done
 
 // Load composer
 require __DIR__ . '/vendor/autoload.php';
 
+// Add you bot's API key and name
 $API_KEY = 'your_bot_api_key';
 $BOT_NAME = 'username_bot';
+
+// Define a path for your custom commands
 //$commands_path = __DIR__ . '/Commands/';
+
+// Enter your MySQL database credentials
 $mysql_credentials = [
    'host'     => 'localhost',
    'user'     => 'dbuser',
@@ -24,53 +31,54 @@ try {
     // Create Telegram API object
     $telegram = new Longman\TelegramBot\Telegram($API_KEY, $BOT_NAME);
 
+    // Error, Debug and Raw Update logging
+    //Longman\TelegramBot\TelegramLog::initialize($your_external_monolog_instance);
+    //Longman\TelegramBot\TelegramLog::initErrorLog($path . '/' . $BOT_NAME . '_error.log');
+    //Longman\TelegramBot\TelegramLog::initDebugLog($path . '/' . $BOT_NAME . '_debug.log');
+    //Longman\TelegramBot\TelegramLog::initUpdateLog($path . '/' . $BOT_NAME . '_update.log');
+
     // Enable MySQL
-    $telegram->enableMySQL($mysql_credentials);
+    $telegram->enableMySql($mysql_credentials);
 
-    //// Enable MySQL with table prefix
-    //$telegram->enableMySQL($mysql_credentials, $BOT_NAME . '_');
+    // Enable MySQL with table prefix
+    //$telegram->enableMySql($mysql_credentials, $BOT_NAME . '_');
 
-    //// Add an additional commands path
+    // Add an additional commands path
     //$telegram->addCommandsPath($commands_path);
 
-    //// Enable admin users
+    // Enable admin user(s)
     //$telegram->enableAdmin(your_telegram_id);
+    //$telegram->enableAdmins([your_telegram_id, other_telegram_id]);
 
-    //// Add the channel you want to manage
+    // Add the channel you want to manage
     //$telegram->setCommandConfig('sendtochannel', ['your_channel' => '@type_here_your_channel']);
 
-    //// Here you can set some command specific parameters,
-    //// for example, google geocode/timezone api key for date command:
+    // Here you can set some command specific parameters,
+    // for example, google geocode/timezone api key for /date command:
     //$telegram->setCommandConfig('date', ['google_api_key' => 'your_google_api_key_here']);
 
-    //// Logging
-    //\Longman\TelegramBot\TelegramLog::initialize($your_external_monolog_instance);
-    //\Longman\TelegramBot\TelegramLog::initErrorLog($path . '/' . $BOT_NAME . '_error.log');
-    //\Longman\TelegramBot\TelegramLog::initDebugLog($path . '/' . $BOT_NAME . '_debug.log');
-    //\Longman\TelegramBot\TelegramLog::initUpdateLog($path . '/' . $BOT_NAME . '_update.log');
-
-    //// Set custom Upload and Download path
+    // Set custom Upload and Download path
     //$telegram->setDownloadPath('../Download');
     //$telegram->setUploadPath('../Upload');
 
-    //// Botan.io integration
+    // Botan.io integration
     //$telegram->enableBotan('your_token');
 
-    // Handle telegram getUpdate request
-    $ServerResponse = $telegram->handleGetUpdates();
+    // Handle telegram getUpdates request
+    $serverResponse = $telegram->handleGetUpdates();
 
-    if ($ServerResponse->isOk()) {
-        $n_update = count($ServerResponse->getResult());
-        print(date('Y-m-d H:i:s', time()) . ' - Processed ' . $n_update . ' updates' . "\n");
+    if ($serverResponse->isOk()) {
+        $updateCount = count($serverResponse->getResult());
+        echo date('Y-m-d H:i:s', time()) . ' - Processed ' . $updateCount . ' updates';
     } else {
-        print(date('Y-m-d H:i:s', time()) . ' - Failed to fetch updates' . "\n");
-        echo $ServerResponse->printError() . "\n";
+        echo date('Y-m-d H:i:s', time()) . ' - Failed to fetch updates' . PHP_EOL;
+        echo $serverResponse->printError();
     }
 } catch (Longman\TelegramBot\Exception\TelegramException $e) {
     echo $e;
-    // log telegram errors
-    \Longman\TelegramBot\TelegramLog::error($e);
+    // Log telegram errors
+    Longman\TelegramBot\TelegramLog::error($e);
 } catch (Longman\TelegramBot\Exception\TelegramLogException $e) {
-    //catch log initilization errors
+    // Catch log initilization errors
     echo $e;
 }

examples/hook.php

 <?php
-//README
-//This configuration file is intended to run the bot with the webhook method.
-//Uncommented parameters must be filled
-//Please notice that if you open this file with your browser you'll get the "Input is empty!" Exception.
-//This is a normal behaviour because this address has to be reached only by Telegram server.
+/**
+ * README
+ * This configuration file is intended to run the bot with the webhook method.
+ * Uncommented parameters must be filled
+ *
+ * Please note that if you open this file with your browser you'll get the "Input is empty!" Exception.
+ * This is a normal behaviour because this address has to be reached only by Telegram server.
+ */
 
 // Load composer
 require __DIR__ . '/vendor/autoload.php';
 
+// Add you bot's API key and name
 $API_KEY = 'your_bot_api_key';
 $BOT_NAME = 'username_bot';
+
+// Define a path for your custom commands
 //$commands_path = __DIR__ . '/Commands/';
+
+// Enter your MySQL database credentials
 //$mysql_credentials = [
 //    'host'     => 'localhost',
 //    'user'     => 'dbuser',
@@ -22,46 +30,48 @@ try {
     // Create Telegram API object
     $telegram = new Longman\TelegramBot\Telegram($API_KEY, $BOT_NAME);
 
-    //// Enable MySQL
-    //$telegram->enableMySQL($mysql_credentials);
+    // Error, Debug and Raw Update logging
+    //Longman\TelegramBot\TelegramLog::initialize($your_external_monolog_instance);
+    //Longman\TelegramBot\TelegramLog::initErrorLog($path . '/' . $BOT_NAME . '_error.log');
+    //Longman\TelegramBot\TelegramLog::initDebugLog($path . '/' . $BOT_NAME . '_debug.log');
+    //Longman\TelegramBot\TelegramLog::initUpdateLog($path . '/' . $BOT_NAME . '_update.log');
+
+    // Enable MySQL
+    //$telegram->enableMySql($mysql_credentials);
 
-    //// Enable MySQL with table prefix
-    //$telegram->enableMySQL($mysql_credentials, $BOT_NAME . '_');
+    // Enable MySQL with table prefix
+    //$telegram->enableMySql($mysql_credentials, $BOT_NAME . '_');
 
-    //// Add an additional commands path
+    // Add an additional commands path
     //$telegram->addCommandsPath($commands_path);
 
-    //// Enable admin users
+    // Enable admin user(s)
     //$telegram->enableAdmin(your_telegram_id);
+    //$telegram->enableAdmins([your_telegram_id, other_telegram_id]);
 
-    //// Add the channel you want to manage
+    // Add the channel you want to manage
     //$telegram->setCommandConfig('sendtochannel', ['your_channel' => '@type_here_your_channel']);
 
-    //// Here you can set some command specific parameters,
-    //// for example, google geocode/timezone api key for date command:
+    // Here you can set some command specific parameters,
+    // for example, google geocode/timezone api key for /date command:
     //$telegram->setCommandConfig('date', ['google_api_key' => 'your_google_api_key_here']);
 
-    //// Logging
-    //\Longman\TelegramBot\TelegramLog::initialize($your_external_monolog_instance);
-    //\Longman\TelegramBot\TelegramLog::initErrorLog($path . '/' . $BOT_NAME . '_error.log');
-    //\Longman\TelegramBot\TelegramLog::initDebugLog($path . '/' . $BOT_NAME . '_debug.log');
-    //\Longman\TelegramBot\TelegramLog::initUpdateLog($path . '/' . $BOT_NAME . '_update.log');
-
-    //// Set custom Upload and Download path
+    // Set custom Upload and Download path
     //$telegram->setDownloadPath('../Download');
     //$telegram->setUploadPath('../Upload');
 
-    //// Botan.io integration
+    // Botan.io integration
     //$telegram->enableBotan('your_token');
 
     // Handle telegram webhook request
     $telegram->handle();
 } catch (Longman\TelegramBot\Exception\TelegramException $e) {
-    // Silence is gold!
-    // echo $e;
-    // log telegram errors
-    \Longman\TelegramBot\TelegramLog::error($e);
+    // Silence is golden!
+    //echo $e;
+    // Log telegram errors
+    Longman\TelegramBot\TelegramLog::error($e);
 } catch (Longman\TelegramBot\Exception\TelegramLogException $e) {
-    // Silence is gold! Uncomment this to catch log initilization errors
+    // Silence is golden!
+    // Uncomment this to catch log initilization errors
     //echo $e;
 }