Improve APPEND results and safely expunge specific messages

src/AppendResult.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace DirectoryTree\ImapEngine;
+
+use DirectoryTree\ImapEngine\Connection\Responses\Data\ResponseCodeData;
+use DirectoryTree\ImapEngine\Connection\Responses\TaggedResponse;
+use DirectoryTree\ImapEngine\Connection\Tokens\Token;
+
+/**
+ * @see https://datatracker.ietf.org/doc/html/rfc4315#section-3
+ */
+class AppendResult
+{
+    /**
+     * Constructor.
+     */
+    public function __construct(
+        protected ?int $uidValidity = null,
+        protected ?int $uid = null,
+    ) {}
+
+    /**
+     * Create an append result from the tagged response.
+     */
+    public static function fromResponse(TaggedResponse $response): static
+    {
+        $data = $response->tokenAt(2);
+
+        if (! $data instanceof ResponseCodeData) {
+            return new static;
+        }
+
+        $code = $data->first();
+
+        if (! $code instanceof Token || ! $code->is('APPENDUID')) {
+            return new static;
+        }
+
+        return new static(
+            uidValidity: (int) $data->tokenAt(1)->value,
+            uid: (int) $data->tokenAt(2)->value,
+        );
+    }
+
+    /**
+     * Get the mailbox UID validity value.
+     */
+    public function uidValidity(): ?int
+    {
+        return $this->uidValidity;
+    }
+
+    /**
+     * Get the appended message UID.
+     */
+    public function uid(): ?int
+    {
+        return $this->uid;
+    }
+}

src/Connection/ConnectionInterface.php

@@ -2,6 +2,8 @@
 
 namespace DirectoryTree\ImapEngine\Connection;
 
+use DateTimeInterface;
+use DirectoryTree\ImapEngine\AppendResult;
 use DirectoryTree\ImapEngine\Collections\ResponseCollection;
 use DirectoryTree\ImapEngine\Connection\Responses\TaggedResponse;
 use DirectoryTree\ImapEngine\Connection\Responses\UntaggedResponse;
@@ -92,7 +94,7 @@ public function noop(): TaggedResponse;
      *
      * @see https://datatracker.ietf.org/doc/html/rfc9051#name-expunge-command
      */
-    public function expunge(): ResponseCollection;
+    public function expunge(array|int|null $uids = null): ResponseCollection;
 
     /**
      * Send a "CAPABILITY" command.
@@ -259,7 +261,7 @@ public function store(array|string $flags, array|int $from, ?int $to = null, ?st
      *
      * @see https://datatracker.ietf.org/doc/html/rfc9051#name-append-command
      */
-    public function append(string $folder, string $message, ?array $flags = null): TaggedResponse;
+    public function append(string $folder, string $message, ?array $flags = null, ?DateTimeInterface $date = null): AppendResult;
 
     /**
      * Send a "UID COPY" command.

src/Connection/ImapConnection.php

@@ -2,6 +2,8 @@
 
 namespace DirectoryTree\ImapEngine\Connection;
 
+use DateTimeInterface;
+use DirectoryTree\ImapEngine\AppendResult;
 use DirectoryTree\ImapEngine\Collections\ResponseCollection;
 use DirectoryTree\ImapEngine\Connection\Loggers\LoggerInterface;
 use DirectoryTree\ImapEngine\Connection\Responses\ContinuationResponse;
@@ -363,7 +365,7 @@ public function list(string $reference = '', string $folder = '*'): ResponseColl
     /**
      * {@inheritDoc}
      */
-    public function append(string $folder, string $message, ?array $flags = null): TaggedResponse
+    public function append(string $folder, string $message, ?array $flags = null, ?DateTimeInterface $date = null): AppendResult
     {
         $tokens = [];
 
@@ -373,11 +375,17 @@ public function append(string $folder, string $message, ?array $flags = null): T
             $tokens[] = Str::list($flags);
         }
 
+        if ($date) {
+            $tokens[] = Str::literal($date->format('d-M-Y H:i:s O'));
+        }
+
         $tokens[] = Str::literal($message);
 
         $this->send('APPEND', $tokens, tag: $tag);
 
-        return $this->assertTaggedResponse($tag);
+        return AppendResult::fromResponse(
+            $this->assertTaggedResponse($tag)
+        );
     }
 
     /**
@@ -557,9 +565,13 @@ public function id(?array $ids = null): UntaggedResponse
     /**
      * {@inheritDoc}
      */
-    public function expunge(): ResponseCollection
+    public function expunge(array|int|null $uids = null): ResponseCollection
     {
-        $this->send('EXPUNGE', tag: $tag);
+        $this->send(
+            $uids === null ? 'EXPUNGE' : 'UID EXPUNGE',
+            $uids === null ? [] : [Str::set($uids)],
+            $tag,
+        );
 
         $this->assertTaggedResponse($tag);
 

src/Folder.php

@@ -241,9 +241,9 @@ public function examine(): array
     /**
      * {@inheritDoc}
      */
-    public function expunge(): array
+    public function expunge(array|int|null $uids = null): array
     {
-        return $this->mailbox->connection()->expunge()->map(
+        return $this->mailbox->connection()->expunge($uids)->map(
             fn (UntaggedResponse $response) => $response->tokenAt(1)->value
         )->all();
     }

src/FolderInterface.php

@@ -79,7 +79,7 @@ public function examine(): array;
     /**
      * Expunge the mailbox and return the expunged message sequence numbers.
      */
-    public function expunge(): array;
+    public function expunge(array|int|null $uids = null): array;
 
     /**
      * Delete the current folder.

src/Message.php

@@ -171,7 +171,7 @@ public function flag(BackedEnum|string $flag, string $operation, bool $expunge =
             ->store($flag, $this->uid, mode: $operation);
 
         if ($expunge) {
-            $this->folder->expunge();
+            $this->folder->expunge($this->uid);
         }
 
         $this->flags = match ($operation) {
@@ -215,10 +215,6 @@ public function move(string $folder, bool $expunge = false): ?int
             case in_array('MOVE', $capabilities):
                 $response = $mailbox->connection()->move($folder, $this->uid);
 
-                if ($expunge) {
-                    $this->folder->expunge();
-                }
-
                 return MessageResponseParser::getUidFromCopy($response);
 
             case in_array('UIDPLUS', $capabilities):

src/MessageQuery.php

@@ -3,6 +3,7 @@
 namespace DirectoryTree\ImapEngine;
 
 use BackedEnum;
+use DateTimeInterface;
 use DirectoryTree\ImapEngine\Collections\MessageCollection;
 use DirectoryTree\ImapEngine\Collections\ResponseCollection;
 use DirectoryTree\ImapEngine\Connection\ConnectionInterface;
@@ -74,16 +75,11 @@ public function get(): MessageCollection
     /**
      * Append a new message to the folder.
      */
-    public function append(string $message, mixed $flags = null): int
+    public function append(string $message, mixed $flags = null, ?DateTimeInterface $date = null): AppendResult
     {
-        $response = $this->connection()->append(
-            $this->folder->path(), $message, (array) Str::enums($flags),
+        return $this->connection()->append(
+            $this->folder->path(), $message, (array) Str::enums($flags), $date,
         );
-
-        return (int) $response // TAG4 OK [APPENDUID <uidvalidity> <uid>] APPEND completed.
-            ->tokenAt(2) // [APPENDUID <uidvalidity> <uid>]
-            ->tokenAt(2) // <uid>
-            ->value;
     }
 
     /**
@@ -209,7 +205,7 @@ public function destroy(array|int $uids, bool $expunge = false): void
             ->store([ImapFlag::Deleted->value], $uids, mode: '+');
 
         if ($expunge) {
-            $this->folder->expunge();
+            $this->folder->expunge($uids);
         }
     }
 
@@ -231,7 +227,7 @@ public function flag(BackedEnum|string $flag, string $operation, bool $expunge =
         );
 
         if ($expunge) {
-            $this->folder->expunge();
+            $this->folder->expunge($uids);
         }
 
         return count($uids);
@@ -290,10 +286,6 @@ public function move(string $folder, bool $expunge = false): int
 
         $this->connection()->move($folder, $uids);
 
-        if ($expunge) {
-            $this->folder->expunge();
-        }
-
         return count($uids);
     }
 

src/MessageQueryInterface.php

@@ -3,6 +3,7 @@
 namespace DirectoryTree\ImapEngine;
 
 use BackedEnum;
+use DateTimeInterface;
 use DirectoryTree\ImapEngine\Collections\MessageCollection;
 use DirectoryTree\ImapEngine\Connection\ImapQueryBuilder;
 use DirectoryTree\ImapEngine\Enums\ImapFetchIdentifier;
@@ -207,7 +208,7 @@ public function get(): MessageCollection;
     /**
      * Append a new message to the folder.
      */
-    public function append(string $message, mixed $flags = null): int;
+    public function append(string $message, mixed $flags = null, ?DateTimeInterface $date = null): AppendResult;
 
     /**
      * Execute a callback over each message via a chunked query.

src/Testing/FakeFolder.php

@@ -141,7 +141,7 @@ public function examine(): array
     /**
      * {@inheritDoc}
      */
-    public function expunge(): array
+    public function expunge(array|int|null $uids = null): array
     {
         return [];
     }

src/Testing/FakeMessageQuery.php

@@ -3,6 +3,8 @@
 namespace DirectoryTree\ImapEngine\Testing;
 
 use BackedEnum;
+use DateTimeInterface;
+use DirectoryTree\ImapEngine\AppendResult;
 use DirectoryTree\ImapEngine\Collections\MessageCollection;
 use DirectoryTree\ImapEngine\Connection\ImapQueryBuilder;
 use DirectoryTree\ImapEngine\Enums\ImapFetchIdentifier;
@@ -62,7 +64,7 @@ public function firstOrFail(): MessageInterface
     /**
      * {@inheritDoc}
      */
-    public function append(string $message, mixed $flags = null): int
+    public function append(string $message, mixed $flags = null, ?DateTimeInterface $date = null): AppendResult
     {
         $uid = 1;
 
@@ -74,7 +76,7 @@ public function append(string $message, mixed $flags = null): int
             new FakeMessage($uid, $flags === null ? [] : $flags, $message)
         );
 
-        return $uid;
+        return new AppendResult(uid: $uid);
     }
 
     /**