ImapEngine v2.0

.github/workflows/run-integration-tests.yml

@@ -12,27 +12,38 @@ jobs:
     run-tests:
         runs-on: ${{ matrix.os }}
 
-        services:
-            greenmail:
-                image: greenmail/standalone:latest
-                env:
-                    GREENMAIL_OPTS: -Dgreenmail.setup.test.all -Dgreenmail.hostname=0.0.0.0 -Dgreenmail.auth.disabled -Dgreenmail.verbose
-                ports:
-                    - 3143:3143
+        env:
+            MAILBOX_HOST: 127.0.0.1
+            MAILBOX_PORT: ${{ matrix.port }}
+            MAILBOX_SERVER: ${{ matrix.server }}
+            MAILBOX_USERNAME: user@localhost.com
+            MAILBOX_PASSWORD: password
+            MAILBOX_ENCRYPTION: ""
 
         strategy:
             fail-fast: false
             matrix:
                 os: [ ubuntu-latest ]
                 php: [ 8.5, 8.4, 8.3, 8.2 ]
                 dependency-version: [ prefer-stable ]
+                server: [ greenmail ]
+                port: [ 3143 ]
+                include:
+                    - os: ubuntu-latest
+                      php: 8.4
+                      dependency-version: prefer-stable
+                      server: dovecot
+                      port: 4143
 
-        name: ${{ matrix.os }} - P${{ matrix.php }} - ${{ matrix.dependency-version }}
+        name: ${{ matrix.server }} - P${{ matrix.php }} - ${{ matrix.dependency-version }}
 
         steps:
             - name: Checkout code
               uses: actions/checkout@v4
 
+            - name: Start IMAP server
+              run: docker compose up -d ${{ matrix.server }}
+
             - name: Cache dependencies
               uses: actions/cache@v4
               with:
@@ -48,5 +59,16 @@ jobs:
               run: |
                   composer update --${{ matrix.dependency-version }} --prefer-dist --no-interaction
 
+            - name: Wait for IMAP server
+              run: php tests/wait-for-mailbox.php
+
             - name: Execute tests
               run: vendor/bin/pest --testsuite Integration
+
+            - name: Show IMAP server logs
+              if: failure()
+              run: docker compose logs --no-color ${{ matrix.server }}
+
+            - name: Stop IMAP server
+              if: always()
+              run: docker compose down --volumes

composer.json

@@ -17,7 +17,8 @@
         }
     ],
     "require": {
-        "php": "^8.1",
+        "php": "^8.2",
+        "php-64bit": "*",
         "symfony/mime": ">=6.0",
         "nesbot/carbon": ">=2.0",
         "illuminate/collections": ">=9.0",

docker-compose.yml

@@ -1,7 +1,16 @@
 services:
     greenmail:
-        image: greenmail/standalone:latest
+        image: greenmail/standalone:2.1.14
         environment:
             - GREENMAIL_OPTS=-Dgreenmail.setup.test.all -Dgreenmail.hostname=0.0.0.0 -Dgreenmail.auth.disabled -Dgreenmail.verbose
         ports:
-            - "3143:3143"
+            - "127.0.0.1:3143:3143"
+
+    dovecot:
+        image: dovecot/dovecot:2.4.3
+        environment:
+            USER_PASSWORD: password
+        volumes:
+            - ./tests/docker/dovecot.conf:/etc/dovecot/conf.d/99-test.conf:ro
+        ports:
+            - "127.0.0.1:4143:31143"

readme.md

@@ -16,3 +16,61 @@
 <p align="center">
   <a href="https://imapengine.com">View Documentation</a>
 </p>
+
+### Partial body fetching
+
+Fetch a byte range of a message section without downloading the whole section:
+
+```php
+$messages = $folder->messages()
+    ->with(MessageData::text()->partial(0, 4096)->peek())
+    ->get();
+
+$preview = $messages->first()->data()->get('BODY[TEXT]<0>');
+
+$chunk = $message->bodyPart('2', offset: 65536, length: 65536);
+```
+
+Offsets are zero-based and refer to transfer-encoded bytes. The server may return
+fewer bytes at the end of a section, or an empty string beyond its end. A missing
+message or section returns `null`. Partial data does not replace the complete body.
+
+Attachments obtained through `attachments(fetch: true)` download in 64 KiB chunks
+as their streams are read. Base64 and quoted-printable decoding continues across
+chunk boundaries. Decoded content is cached in a temporary stream that spills to
+disk beyond 2 MiB, allowing seeks and repeated reads without fetching again.
+
+```php
+$attachment = $message->attachments(fetch: true)[0];
+$attachment->save('/path/to/attachment.pdf');
+```
+
+`save()` copies stream chunks directly to the destination. Calling `contents()` or
+casting a stream to a string still allocates the requested contents in memory.
+The decoded stream size is unknown (`null`) until the section has been fully read.
+
+### Iterating over synchronization results
+
+`FetchResult::messages()` and `StoreResult::messages()` return collections of
+fetched message data. `FetchResult::vanished()` returns a `VanishedCollection`.
+Result constructors accept collections rather than arrays.
+
+`uids()`, `vanishedUids()`, and `modified()` return lazy collections. Iterate over
+them directly to process identifiers without first building the complete arrays:
+
+```php
+foreach ($changes->vanished() as $vanished) {
+    foreach ($vanished->uids() as $uid) {
+        // Remove the message from your local mailbox.
+    }
+}
+
+foreach ($store->modified() as $uid) {
+    // Reconcile a message whose conditional flag update was rejected.
+}
+```
+
+Call `->all()` when you need an array; this allocates memory for every returned
+identifier. `vanishedUids()` combines groups and tracks previously yielded UIDs
+to remove duplicates. Iterate over each group’s `uids()` for bounded-memory
+processing of large ranges.

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/Attachment.php

@@ -2,6 +2,7 @@
 
 namespace DirectoryTree\ImapEngine;
 
+use DirectoryTree\ImapEngine\Support\LazyBodyPartStream;
 use GuzzleHttp\Psr7\Utils;
 use Illuminate\Contracts\Support\Arrayable;
 use JsonSerializable;
@@ -63,7 +64,7 @@ public static function lazy(Message $message): array
                 $part->id(),
                 $part->contentType(),
                 $part->disposition()?->type()?->value,
-                new Support\LazyBodyPartStream($message, $part),
+                new LazyBodyPartStream($message, $part),
             );
         }
 
@@ -137,7 +138,23 @@ public function contentStream(): StreamInterface
      */
     public function save(string $path): false|int
     {
-        return file_put_contents($path, $this->contents());
+        if ($this->contentStream->isSeekable()) {
+            $this->contentStream->rewind();
+        }
+
+        if (! $resource = fopen($path, 'wb')) {
+            return false;
+        }
+
+        $destination = Utils::streamFor($resource);
+
+        try {
+            Utils::copyToStream($this->contentStream, $destination);
+
+            return $destination->tell();
+        } finally {
+            $destination->close();
+        }
     }
 
     /**

src/Authentication.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace DirectoryTree\ImapEngine;
+
+use DirectoryTree\ImapEngine\Connection\ConnectionInterface;
+use DirectoryTree\ImapEngine\Connection\Responses\TaggedResponse;
+use Throwable;
+
+class Authentication
+{
+    /**
+     * Constructor.
+     */
+    public function __construct(
+        protected ConnectionInterface $connection,
+        protected AuthenticatorInterface $authenticator,
+    ) {}
+
+    /**
+     * Authenticate the connection.
+     */
+    public function authenticate(bool $initial = false): TaggedResponse
+    {
+        $response = $this->authenticator->initial();
+
+        $sent = $initial && $response !== null;
+
+        $exchange = $this->connection->authenticate(
+            $this->authenticator->mechanism(),
+            $sent ? $response : null,
+        );
+
+        while ($exchange->valid()) {
+            $challenge = $exchange->current();
+
+            try {
+                if (! $sent && $response !== null) {
+                    $answer = $response;
+                    $sent = true;
+                } else {
+                    $answer = $this->authenticator->respond($challenge);
+                }
+            } catch (Throwable $e) {
+                $this->connection->disconnect();
+
+                throw $e;
+            }
+
+            $exchange->send($answer);
+        }
+
+        return $exchange->getReturn();
+    }
+}

src/Authentication/XOAuth2.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace DirectoryTree\ImapEngine\Authentication;
+
+use DirectoryTree\ImapEngine\AuthenticatorInterface;
+
+class XOAuth2 implements AuthenticatorInterface
+{
+    /**
+     * Constructor.
+     */
+    public function __construct(
+        protected string $user,
+        protected string $token,
+    ) {}
+
+    /**
+     * {@inheritDoc}
+     */
+    public function mechanism(): string
+    {
+        return 'XOAUTH2';
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function initial(): string
+    {
+        return "user=$this->user\1auth=Bearer $this->token\1\1";
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function respond(string $challenge): string
+    {
+        return '';
+    }
+}

src/AuthenticatorInterface.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace DirectoryTree\ImapEngine;
+
+interface AuthenticatorInterface
+{
+    /**
+     * Get the SASL mechanism name.
+     */
+    public function mechanism(): string;
+
+    /**
+     * Get the unencoded initial data, or null to await a challenge.
+     */
+    public function initial(): ?string;
+
+    /**
+     * Respond to a decoded challenge. Return null to cancel authentication.
+     */
+    public function respond(string $challenge): ?string;
+}