expunge option added to critical imap operations

Author: Webklex

src/IMAP/Client.php

@@ -152,7 +152,8 @@ public function setConfig(array $config) {
     /**
      * Get the current imap resource
      *
-     * @return resource|boolean
+     * @return bool|resource
+     * @throws ConnectionFailedException
      */
     public function getConnection() {
         $this->checkConnection();
@@ -324,38 +325,50 @@ public function openFolder(Folder $folder, $attempts = 3) {
     /**
      * Create a new Folder
      * @param string $name
+     * @param boolean $expunge
      *
      * @return bool
      * @throws ConnectionFailedException
      */
-    public function createFolder($name) {
+    public function createFolder($name, $expunge = true) {
         $this->checkConnection();
-        return imap_createmailbox($this->getConnection(), $this->getAddress() . imap_utf7_encode($name));
+        $status = imap_createmailbox($this->getConnection(), $this->getAddress() . imap_utf7_encode($name));
+        if($expunge) $this->expunge();
+
+        return $status;
     }
 
     /**
      * Rename Folder
-     * @param string $old_name
-     * @param string $new_name
+     * @param string  $old_name
+     * @param string  $new_name
+     * @param boolean $expunge
      *
      * @return bool
      * @throws ConnectionFailedException
      */
-    public function renameFolder($old_name, $new_name) {
+    public function renameFolder($old_name, $new_name, $expunge = true) {
         $this->checkConnection();
-        return imap_renamemailbox($this->getConnection(), $this->getAddress() . imap_utf7_encode($old_name), $this->getAddress() . imap_utf7_encode($new_name));
+        $status = imap_renamemailbox($this->getConnection(), $this->getAddress() . imap_utf7_encode($old_name), $this->getAddress() . imap_utf7_encode($new_name));
+        if($expunge) $this->expunge();
+
+        return $status;
     }
 
      /**
      * Delete Folder
      * @param string $name
+      * @param boolean $expunge
      *
      * @return bool
      * @throws ConnectionFailedException
      */
-    public function deleteFolder($name) {
+    public function deleteFolder($name, $expunge = true) {
         $this->checkConnection();
-        return imap_deletemailbox($this->getConnection(), $this->getAddress() . imap_utf7_encode($name));
+        $status = imap_deletemailbox($this->getConnection(), $this->getAddress() . imap_utf7_encode($name));
+        if($expunge) $this->expunge();
+
+        return $status;
     }
 
     /**

src/IMAP/Folder.php

@@ -129,6 +129,7 @@ public function __construct(Client $client, $folder) {
      * @param string $charset
      *
      * @return WhereQuery
+     * @throws Exceptions\ConnectionFailedException
      */
     public function query($charset = 'UTF-8'){
         $this->getClient()->checkConnection();
@@ -139,13 +140,15 @@ public function query($charset = 'UTF-8'){
 
     /**
      * @inheritdoc self::query($charset = 'UTF-8')
+     * @throws Exceptions\ConnectionFailedException
      */
     public function search($charset = 'UTF-8'){
         return $this->query($charset);
     }
 
     /**
      * @inheritdoc self::query($charset = 'UTF-8')
+     * @throws Exceptions\ConnectionFailedException
      */
     public function messages($charset = 'UTF-8'){
         return $this->query($charset);
@@ -359,14 +362,15 @@ protected function parseAttributes($attributes) {
 
     /**
      * Delete the current Mailbox
+     * @param boolean $expunge
      *
      * @return bool
      *
      * @throws Exceptions\ConnectionFailedException
      */
-    public function delete() {
+    public function delete($expunge = true) {
         $status = imap_deletemailbox($this->client->getConnection(), $this->path);
-        $this->client->expunge();
+        if($expunge) $this->client->expunge();
 
         return $status;
     }
@@ -375,14 +379,15 @@ public function delete() {
      * Move or Rename the current Mailbox
      *
      * @param string $target_mailbox
+     * @param boolean $expunge
      *
      * @return bool
      *
      * @throws Exceptions\ConnectionFailedException
      */
-    public function move($target_mailbox) {
+    public function move($target_mailbox, $expunge = true) {
         $status = imap_renamemailbox($this->client->getConnection(), $this->path, $target_mailbox);
-        $this->client->expunge();
+        if($expunge) $this->client->expunge();
 
         return $status;
     }

src/IMAP/Message.php

@@ -721,7 +721,9 @@ public function getEncoding($structure) {
      * Find the folder containing this message.
      *
      * @param null|Folder $folder where to start searching from (top-level inbox by default)
+     *
      * @return null|Folder
+     * @throws Exceptions\ConnectionFailedException
      */
     public function getContainingFolder(Folder $folder = null) {
         $folder = $folder ?: $this->client->getFolders()->first();
@@ -758,10 +760,10 @@ public function getContainingFolder(Folder $folder = null) {
 
     /**
      * Move the Message into an other Folder
-     *
-     * @param string  $mailbox
+     * @param string $mailbox
      *
      * @return bool
+     * @throws Exceptions\ConnectionFailedException
      */
     public function moveToFolder($mailbox = 'INBOX') {
         $this->client->createFolder($mailbox);
@@ -771,23 +773,30 @@ public function moveToFolder($mailbox = 'INBOX') {
 
     /**
      * Delete the current Message
+     * @param bool $expunge
      *
      * @return bool
+     * @throws Exceptions\ConnectionFailedException
      */
-    public function delete() {
+    public function delete($expunge = true) {
         $status = imap_delete($this->client->getConnection(), $this->uid, FT_UID);
-        $this->client->expunge();
+        if($expunge) $this->client->expunge();
 
         return $status;
     }
 
     /**
      * Restore a deleted Message
+     * @param boolean $expunge
      *
      * @return bool
+     * @throws Exceptions\ConnectionFailedException
      */
-    public function restore() {
-        return imap_undelete($this->client->getConnection(), $this->uid, FT_UID);
+    public function restore($expunge = true) {
+        $status = imap_undelete($this->client->getConnection(), $this->uid, FT_UID);
+        if($expunge) $this->client->expunge();
+
+        return $status;
     }
 
     /**
@@ -816,7 +825,10 @@ public function hasAttachments() {
      */
     public function setFlag($flag) {
         $flag = "\\".trim(is_array($flag) ? implode(" \\", $flag) : $flag);
-        return imap_setflag_full($this->client->getConnection(), $this->getUid(), $flag, SE_UID);
+        $status = imap_setflag_full($this->client->getConnection(), $this->getUid(), $flag, SE_UID);
+        $this->parseFlags();
+
+        return $status;
     }
 
     /**
@@ -827,7 +839,10 @@ public function setFlag($flag) {
      */
     public function unsetFlag($flag) {
         $flag = "\\".trim(is_array($flag) ? implode(" \\", $flag) : $flag);
-        return imap_clearflag_full($this->client->getConnection(), $this->getUid(), $flag, SE_UID);
+        $status = imap_clearflag_full($this->client->getConnection(), $this->getUid(), $flag, SE_UID);
+        $this->parseFlags();
+
+        return $status;
     }
 
     /**