Find the folder containing a message (#92)

Fixes #89

Author: Stéphane Coinon

README.md

@@ -279,6 +279,11 @@ $aMessage = $oFolder->searchMessages([['TEXT', 'Hello world']], null, false, 'UT
 $aMessage = $oFolder->getMessages('ALL', null, false, false);
 ```
 
+Find the folder containing a message:
+``` php
+$oFolder = $aMessage->getContainingFolder();
+```
+
 ## Documentation
 ### [Client::class](src/IMAP/Client.php)
 | Method              | Arguments                                                                       | Return            | Description                                                                                                                   |
@@ -319,6 +324,7 @@ $aMessage = $oFolder->getMessages('ALL', null, false, false);
 | restore         |                               |                      | Restore a deleted Message              |
 | copy            | string $mailbox, int $options |                      | Copy the current Messages to a mailbox |
 | move            | string $mailbox, int $options |                      | Move the current Messages to a mailbox |
+| getContainingFolder | Folder or null $folder    | null|Folder          | Get the folder containing the message  |
 | moveToFolder    | string $mailbox, int $options |                      | Move the Message into an other Folder  |
 | setFlag         | string or array $flag         | boolean              | Set one or many flags                  |
 | unsetFlag       | string or array $flag         | boolean              | Unset one or many flags                |
@@ -348,6 +354,7 @@ $aMessage = $oFolder->getMessages('ALL', null, false, false);
 | getSender       |                               | array                | Get the current sender information     |
 | getBodies       |                               | mixed                | Get the current bodies                 |
 | getRawBody      |                               | mixed                | Get the current raw message body       |
+| is              |                               | boolean              | Does this message match another one?   |
 
 ### [Folder::class](src/IMAP/Folder.php)
 | Method            | Arguments                                                                           | Return            | Description                                    |

src/IMAP/Message.php

@@ -588,6 +588,46 @@ private function getEncoding($structure) {
         return null;
     }
 
+    /**
+     * Find the folder containing this message.
+     *
+     * @param null|Folder $folder where to start searching from (top-level inbox by default)
+     * @return null|Folder
+     */
+    public function getContainingFolder(Folder $folder = null)
+    {
+        $folder = $folder ?: $this->client->getFolders()->first();
+        $this->client->checkConnection();
+
+        // Try finding the message by uid in the current folder
+        $client = new Client;
+        $client->openFolder($folder);
+        $uidMatches = imap_fetch_overview($client->getConnection(), $this->uid, $this->fetch_options);
+        $uidMatch = count($uidMatches)
+            ? new Message($uidMatches[0]->uid, $uidMatches[0]->msgno, $client)
+            : null;
+        $client->disconnect();
+
+        // imap_fetch_overview() on a parent folder will return the matching message
+        // even when the message is in a child folder so we need to recursively
+        // search the children
+        foreach ($folder->children as $child) {
+            $childFolder = $this->getContainingFolder($child);
+
+            if ($childFolder) {
+                return $childFolder;
+            }
+        }
+
+        // before returning the parent
+        if ($this->is($uidMatch)) {
+            return $folder;
+        }
+
+        // or signalling that the message was not found in any folder
+        return null;
+    }
+
     /**
      * Move the Message into an other Folder
      *
@@ -813,4 +853,24 @@ public function getSender() {
     public function getBodies() {
         return $this->bodies;
     }
+
+    /**
+     * Does this message match another one?
+     *
+     * A match means same uid, message id, subject and date/time.
+     *
+     * @param  null|static $message
+     * @return boolean
+     */
+    public function is(Message $message = null)
+    {
+        if (is_null($message)) {
+            return false;
+        }
+
+        return $this->uid == $message->uid
+            && $this->message_id == $message->message_id
+            && $this->subject == $message->subject
+            && $this->date->eq($message->date);
+    }
 }