Imap idle command added

Author: Webklex

README.md

@@ -28,6 +28,7 @@ read and parse existing mails and much more.
     - [Idle](#idle)
     - [oAuth](#oauth)
     - [Events](#events)
+    - [Commands](#commands)
 - [Support](#support)
 - [Known issues](#known-issues)
 - [Security](#security)
@@ -216,6 +217,122 @@ Additional integration information:
 - https://laravel.com/docs/5.2/events#event-subscribers
 - https://github.com/Webklex/php-imap#events
 
+
+# Commands
+Let's assume you want to run the imap idle process in the background of your server to automatically handle new 
+messages. The following examples will show two major ways to archive this:
+
+### Event driven
+Start by adding the following to your `app/Console/Kernel.php` file:
+```php
+/**
+ * The Artisan commands provided by your application.
+ *
+ * @var array
+ */
+protected $commands = [
+    \Webklex\IMAP\Commands\ImapIdleCommand::class,
+];
+```
+Now register an event listener as described by [here](https://laravel.com/docs/7.x/events#event-subscribers).
+If you don't use the default account, or if you want to add some of your own magic, you'll need to create a 
+custom command (see next section).
+
+Finally test the command by running: 
+```bash
+php artisan imap:idle 
+```
+
+### Custom Command
+Create a new file like `app/Console/Commands/CustomImapIdleCommand.php` and add the following:
+```php
+<?php
+namespace App\Console\Commands;
+
+use Webklex\IMAP\Commands\ImapIdleCommand;
+use Webklex\PHPIMAP\Message;
+
+class CustomImapIdleCommand extends ImapIdleCommand {
+
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'custom_command';
+
+    /**
+     * Holds the account information
+     *
+     * @var string|array $account
+     */
+    protected $account = "default";
+
+    /**
+     * Callback used for the idle command and triggered for every new received message
+     * @param Message $message
+     */
+    public function onNewMessage(Message $message){
+        $this->info("New message received: ".$message->subject);
+    }
+
+}
+```
+..and add the following to your `app/Console/Kernel.php` file:
+```php
+/**
+ * The Artisan commands provided by your application.
+ *
+ * @var array
+ */
+protected $commands = [
+    \App\Console\Commands\CustomImapIdleCommand::class,
+];
+```
+
+Finally test the command by running: 
+```bash
+php artisan custom_command
+```
+
+## Service setup
+A basic systemd service can be setup by creating a service file like this:
+```bash
+nano /etc/systemd/system/imap-idle.service
+``` 
+..and adding:
+```bash
+[Unit]
+Description=ImapIdle
+After=multi-user.target 
+After=syslog.target 
+After=network-online.target
+
+[Service]
+Type=simple
+
+User=www-data
+Group=www-data
+
+WorkingDirectory=/var/www/my_project
+ExecStart=/var/www/my_project/artisan fetch:idle
+
+Restart=on-failure
+RestartSec=5s
+
+[Install]
+WantedBy=multi-user.target
+``` 
+
+You can now test the service by running:
+```bash
+systemctl start imap-idle.service
+systemctl status imap-idle.service
+systemctl stop imap-idle.service
+systemctl restart imap-idle.service
+``` 
+
+
 ## 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).

src/Commands/ImapIdleCommand.php

@@ -0,0 +1,101 @@
+<?php
+
+namespace Webklex\IMAP\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Log;
+use Webklex\IMAP\Facades\Client as ClientFacade;
+use Webklex\PHPIMAP\Exceptions\ConnectionFailedException;
+use Webklex\PHPIMAP\Exceptions\FolderFetchingException;
+use Webklex\PHPIMAP\Folder;
+use Webklex\PHPIMAP\Message;
+
+class ImapIdleCommand extends Command {
+
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'imap:idle';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Fetch new messages by utilising imap idle';
+
+    /**
+     * Holds the account information
+     *
+     * @var string|array $account
+     */
+    protected $account = "default";
+
+    /**
+     * Name of the used folder
+     *
+     * @var string $folder_name
+     */
+    protected $folder_name = "INBOX";
+
+    /**
+     * Create a new command instance.
+     *
+     * @return void
+     */
+    public function __construct() {
+        parent::__construct();
+    }
+
+    /**
+     * Callback used for the idle command and triggered for every new received message
+     * @param Message $message
+     */
+    public function onNewMessage(Message $message){
+        $this->info("New message received: ".$message->subject);
+    }
+
+    /**
+     * Execute the console command.
+     *
+     * @return int
+     */
+    public function handle() {
+        if (is_array($this->account)) {
+            $client = ClientFacade::make($this->account);
+        }else{
+            $client = ClientFacade::account($this->account);
+        }
+
+        try {
+            $client->connect();
+        } catch (ConnectionFailedException $e) {
+            Log::error($e->getMessage());
+            return 1;
+        }
+
+        /** @var Folder $folder */
+        try {
+            $folder = $client->getFolder($this->folder_name);
+        } catch (ConnectionFailedException $e) {
+            Log::error($e->getMessage());
+            return 1;
+        } catch (FolderFetchingException $e) {
+            Log::error($e->getMessage());
+            return 1;
+        }
+
+        try {
+            $folder->idle(function($message){
+                $this->onNewMessage($message);
+            });
+        } catch (\Exception $e) {
+            Log::error($e->getMessage());
+            return 1;
+        }
+
+        return 0;
+    }
+}