Mailbox: add renaming capability (#540)

Fixes #446

src/Exception/RenameMailboxException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ddeboer\Imap\Exception;
+
+final class RenameMailboxException extends AbstractException
+{
+}

src/Mailbox.php

@@ -10,6 +10,7 @@
 use Ddeboer\Imap\Exception\InvalidSearchCriteriaException;
 use Ddeboer\Imap\Exception\MessageCopyException;
 use Ddeboer\Imap\Exception\MessageMoveException;
+use Ddeboer\Imap\Exception\RenameMailboxException;
 use Ddeboer\Imap\Search\ConditionInterface;
 use Ddeboer\Imap\Search\LogicalOperator\All;
 
@@ -41,6 +42,23 @@ public function getName(): string
         return $this->name;
     }
 
+    public function renameTo(string $name): bool
+    {
+        $encodedName = \mb_convert_encoding($name, 'UTF7-IMAP', 'UTF-8');
+        $oldFullName = $this->getFullEncodedName();
+        $newFullName = \preg_replace('/' . \preg_quote(\mb_convert_encoding($this->name, 'UTF7-IMAP', 'UTF-8')) . '$/', $encodedName, $oldFullName);
+        \assert(null !== $newFullName);
+
+        $return = \imap_renamemailbox($this->resource->getStream(), $oldFullName, $newFullName);
+        if (false === $return) {
+            throw new RenameMailboxException('Could not rename mailbox');
+        }
+        $this->name       = $name;
+        $this->info->name = $newFullName;
+
+        return true;
+    }
+
     public function getEncodedName(): string
     {
         /** @var string $name */

src/MailboxInterface.php

@@ -20,6 +20,11 @@ interface MailboxInterface extends \Countable, \IteratorAggregate
      */
     public function getName(): string;
 
+    /**
+     * Set new mailbox name.
+     */
+    public function renameTo(string $name): bool;
+
     /**
      * Get mailbox encoded path.
      */

tests/AbstractTest.php

@@ -18,6 +18,7 @@ abstract class AbstractTest extends TestCase
     public const SPECIAL_CHARS = 'A_\\|!"£$%&()=?àèìòùÀÈÌÒÙ<>-@#[]_ß_б_π_€_✔_你_يد_Z_';
 
     protected ?string $mailboxName;
+    protected ?string $altName;
 
     final protected function getConnection(): ConnectionInterface
     {
@@ -40,6 +41,7 @@ final protected function createMailbox(ConnectionInterface $connection = null):
     {
         $connection        = $connection ?? $this->getConnection();
         $this->mailboxName = \uniqid('mailbox_' . self::SPECIAL_CHARS);
+        $this->altName     = \uniqid('mailbox_' . self::SPECIAL_CHARS);
 
         return $connection->createMailbox($this->mailboxName);
     }

tests/MailboxTest.php

@@ -9,6 +9,7 @@
 use Ddeboer\Imap\Exception\MessageCopyException;
 use Ddeboer\Imap\Exception\MessageDoesNotExistException;
 use Ddeboer\Imap\Exception\MessageMoveException;
+use Ddeboer\Imap\Exception\RenameMailboxException;
 use Ddeboer\Imap\Exception\ReopenMailboxException;
 use Ddeboer\Imap\MailboxInterface;
 use Ddeboer\Imap\MessageIterator;
@@ -39,6 +40,24 @@ public function testGetName(): void
         static::assertSame($this->mailboxName, $this->mailbox->getName());
     }
 
+    public function testRenameTo(): void
+    {
+        static::assertNotSame($this->mailboxName, $this->altName);
+
+        /** @var string $altName */
+        $altName = $this->altName;
+        static::assertTrue($this->mailbox->renameTo($altName));
+        static::assertSame($this->altName, $this->mailbox->getName());
+
+        /** @var string $mailboxName */
+        $mailboxName = $this->mailboxName;
+        static::assertTrue($this->mailbox->renameTo($mailboxName));
+        static::assertSame($this->mailboxName, $this->mailbox->getName());
+
+        static::expectException(RenameMailboxException::class);
+        $this->mailbox->renameTo($mailboxName);
+    }
+
     public function testGetFullEncodedName(): void
     {
         static::assertIsString($this->mailboxName);