Allow custom deny reason to be written to debug log, add short description to readme.

Author: noplanman

README.md

@@ -42,6 +42,7 @@ A Telegram Bot based on the official [Telegram Bot API]
     - [getUserProfilePhoto](#getuserprofilephoto)
     - [getFile and downloadFile](#getfile-and-downloadfile)
     - [Send message to all active chats](#send-message-to-all-active-chats)
+    - [Filter Update](#filter-update)
 - [Utils](#utils)
     - [MySQL storage (Recommended)](#mysql-storage-recommended)
         - [External Database connection](#external-database-connection)
@@ -414,6 +415,25 @@ $results = Request::sendToActiveChats(
 
 You can also broadcast a message to users, from the private chat with your bot. Take a look at the [admin commands](#admin-commands) below.
 
+#### Filter Update
+
+Update processing can be allowed or denied by defining a custom update filter.
+Let's say we only want to allow messages from a user with ID 428, we can do the following before handling the request:
+
+```php
+$telegram->setUpdateFilter(function (Update $update, Telegram $telegram, &$reason = 'Update denied by update_filter') {
+    $user_id = $update->getMessage()->getFrom()->getId();
+    if ($user_id === 428) {
+        return true;
+    }
+
+    $reason = "Invalid user with ID {$user_id}";
+    return false;
+});
+```
+
+The reason for denying an update can be defined with the `$reason` parameter. This text gets written to the debug log.
+
 ## Utils
 
 ### MySQL storage (Recommended)

src/Telegram.php

@@ -464,14 +464,15 @@ public function processUpdate(Update $update)
         $this->last_update_id = $update->getUpdateId();
 
         if (is_callable($this->update_filter)) {
+            $reason = 'Update denied by update_filter';
             try {
-                $allowed = (bool) call_user_func($this->update_filter, $update, $this);
+                $allowed = (bool) call_user_func_array($this->update_filter, [$update, $this, &$reason]);
             } catch (\Exception $e) {
                 $allowed = false;
             }
 
             if (!$allowed) {
-                TelegramLog::debug('Update denied by update_filter');
+                TelegramLog::debug($reason);
                 return new ServerResponse(['ok' => false, 'description' => 'denied'], null);
             }
         }

tests/unit/TelegramTest.php

@@ -15,6 +15,7 @@
 use Longman\TelegramBot\Entities\Update;
 use Longman\TelegramBot\Exception\TelegramException;
 use Longman\TelegramBot\Telegram;
+use Longman\TelegramBot\TelegramLog;
 
 /**
  * @package         TelegramTest
@@ -171,14 +172,27 @@ public function testUpdateFilter()
             }
         }';
 
+        $debug_log_file = '/tmp/php-telegram-bot-update-filter-debug.log';
+        TelegramLog::initialize(
+            new \Monolog\Logger('bot_log', [
+                (new \Monolog\Handler\StreamHandler($debug_log_file, \Monolog\Logger::DEBUG))->setFormatter(new \Monolog\Formatter\LineFormatter(null, null, true)),
+            ])
+        );
+
         $update = new Update(json_decode($rawUpdate, true), $this->telegram->getBotUsername());
-        $this->telegram->setUpdateFilter(function ($update, $telegramInstance) {
-            if ($update->getMessage()->getChat()->getId() == 313534466) {
+        $this->telegram->setUpdateFilter(function (Update $update, Telegram $telegram, &$reason) {
+            if ($update->getMessage()->getChat()->getId() === 313534466) {
+                $reason = 'Invalid user, update denied.';
                 return false;
             }
             return true;
         });
         $response = $this->telegram->processUpdate($update);
         $this->assertFalse($response->isOk());
+
+        // Check that the reason is written to the debug log.
+        $debug_log = file_get_contents($debug_log_file);
+        $this->assertStringContainsString('Invalid user, update denied.', $debug_log);
+        file_exists($debug_log_file) && unlink($debug_log_file);
     }
 }