IDLE like support added #185

Author: Webklex

README.md

@@ -29,8 +29,9 @@ Laravel IMAP is an easy way to integrate the native php imap library into your *
     - [Attachments](#attachments)
     - [Advanced fetching](#advanced-fetching)
     - [Masking](#masking)
-    - [Specials](#specials)
+    - [Idle](#idle)
     - [Events](#events)
+    - [Specials](#specials)
 - [Support](#support)
 - [Documentation](#documentation)
   - [Client::class](#clientclass)
@@ -552,23 +553,35 @@ Additional examples can be found here:
 - [Custom attachment mask](https://github.com/Webklex/laravel-imap/blob/master/examples/custom_attachment_mask.php)
 
 
-#### Specials
-Find the folder containing a message:
+#### Idle
+Use the `Query::idle()` function to have an instance running which behaves like an idle imap connection.
+The callback and `Webklex\IMAP\Events\MessageNewEvent($message)` event get fired by every new incoming email.
 ``` php
-$oFolder = $aMessage->getContainingFolder();
+$timeout = 10;
+/** @var \Webklex\IMAP\Folder $folder */
+$folder->query()->subject('test')->idle(function($message){
+    /** @var \Webklex\IMAP\Message $message */
+    dump("new message", $message->subject);
+}, $timeout);
 ```
 
 #### Events
 The following events are available:
 - `Webklex\IMAP\Events\MessageDeletedEvent($message)` — triggered by `Message::delete`
 - `Webklex\IMAP\Events\MessageRestoredEvent($message)` — triggered by `Message::restore`
 - `Webklex\IMAP\Events\MessageMovedEvent($old_message, $new_message)` — triggered by `Message::move`
-- `Webklex\IMAP\Events\MessageNewEvent($message)` — not triggered
+- `Webklex\IMAP\Events\MessageNewEvent($message)` — can get triggered by `Query::idle()`
 
 Additional integration information:
 - https://laravel.com/docs/7.x/events#event-subscribers
 - https://laravel.com/docs/5.2/events#event-subscribers
 
+#### Specials
+Find the folder containing a message:
+``` php
+$oFolder = $aMessage->getContainingFolder();
+```
+
 ## Support
 If you encounter any problems or if you find a bug, please don't hesitate to create a new [issue](https://github.com/Webklex/laravel-imap/issues).
 However please be aware that it might take some time to get an answer.
@@ -676,6 +689,7 @@ if you're just wishing a feature ;)
 | getSender       |                               | array                | Get the current sender information     |
 | getBodies       |                               | mixed                | Get the current bodies                 |
 | getRawBody      |                               | mixed                | Get the current raw message body       |
+| getToken        |                               | string               | Get a base64 encoded message token     |
 | getFlags        |                               | FlagCollection       | Get the current message flags          |
 | is              |                               | boolean              | Does this message match another one?   |
 | getStructure    |                               | object               | The raw message structure              |
@@ -741,6 +755,7 @@ if you're just wishing a feature ;)
 | bcc                | string $value                     | WhereQuery        | Select messages matching a given receiver (BCC:) |
 | count              |                                   | integer           | Count all available messages matching the current search criteria |
 | get                |                                   | MessageCollection | Fetch messages with the current query |
+| idle               | mixed $callback($message), int $timeout = 10 |        | Simulate an idle connection to receive new messages "live" |
 | limit              | integer $limit, integer $page = 1 | WhereQuery        | Limit the amount of messages being fetched |
 | setFetchOptions    | boolean $fetch_options            | WhereQuery        | Set the fetch options |
 | setFetchBody       | boolean $fetch_body               | WhereQuery        | Set the fetch body option |

src/IMAP/Query/Query.php

@@ -14,6 +14,7 @@
 
 use Carbon\Carbon;
 use Webklex\IMAP\Client;
+use Webklex\IMAP\Events\MessageNewEvent;
 use Webklex\IMAP\Exceptions\GetMessagesFailedException;
 use Webklex\IMAP\Exceptions\MessageSearchValidationException;
 use Webklex\IMAP\IMAP;
@@ -240,6 +241,37 @@ public function paginate($per_page = 5, $page = null, $page_name = 'imap_page'){
         return $this->get()->paginate($per_page, $this->page, $page_name);
     }
 
+    /**
+     * Create an idle like instance to catch incoming messages
+     * @param callable|null $callback
+     * @param int $timeout
+     * @throws GetMessagesFailedException
+     * @throws \Webklex\IMAP\Exceptions\ConnectionFailedException
+     */
+    public function idle(callable $callback = null, $timeout = 10){
+        $known_messages = [];
+        $this->get()->each(function($message) use(&$known_messages){
+            /** @var Message $message */
+            $known_messages[] = $message->getToken();
+        });
+        while ($this->getClient()->isConnected()){
+            $this->getClient()->expunge();
+            $this->get()->each(function($message) use(&$known_messages, $callback){
+                /** @var \Webklex\IMAP\Message $message */
+                $token = $message->getToken();
+                if(in_array($token, $known_messages)){
+                    return;
+                }
+                $known_messages[] = $token;
+                MessageNewEvent::dispatch($message);
+                if ($callback){
+                    $callback($message);
+                }
+            });
+            sleep($timeout);
+        }
+    }
+
     /**
      * Get the raw IMAP search query
      *