feat: initial version

Signed-off-by: Sebastian Krupinski <root@LAPTOP-7DVOR6NC>

lib/Providers/CollectionResource.php

@@ -0,0 +1,101 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXM\ProviderImapMail\Providers;
+
+use Gricob\IMAP\Mailbox;
+use KTXF\Mail\Collection\CollectionMutableAbstract;
+
+/**
+ * IMAP Mail Collection Resource
+ *
+ * Represents one IMAP mailbox / folder.
+ */
+class CollectionResource extends CollectionMutableAbstract
+{
+    public function __construct(
+        string          $provider = 'imap',
+        string|int|null $service  = null,
+    ) {
+        parent::__construct($provider, $service);
+    }
+
+    // ── IMAP hydration ───────────────────────────────────────────────────────
+
+    /**
+     * Populate from a gricob Mailbox object.
+     *
+     * @param Mailbox $mailbox gricob Mailbox value object from LIST response
+     */
+    public function fromImap(Mailbox $mailbox): static
+    {
+        // The mailbox name is its unique identifier within the account
+        $this->data['identifier'] = $mailbox->name;
+
+        // Derive parent collection from path + delimiter
+        $delimiter = $mailbox->hierarchyDelimiter;
+        if ($delimiter && str_contains($mailbox->name, $delimiter)) {
+            $parts = explode($delimiter, $mailbox->name);
+            array_pop($parts);
+            $this->data['collection'] = implode($delimiter, $parts);
+        } else {
+            $this->data['collection'] = null;
+        }
+
+        $this->getProperties()->fromImap($mailbox);
+
+        return $this;
+    }
+
+    // ── Store (MongoDB cache) ────────────────────────────────────────────────
+
+    /**
+     * Serialise to a MongoDB document.
+     *
+     * The caller must inject the service UUID as `sid` before persisting.
+     */
+    public function toStore(): array
+    {
+        return array_merge(
+            $this->data,
+            [
+                'name'       => $this->data['identifier'],
+                'properties' => $this->getProperties()->toStore(),
+            ],
+        );
+    }
+
+    public function fromStore(array $data): static
+    {
+        $this->data = $data;
+        if (isset($data['properties'])) {
+            $this->getProperties()->fromStore($data['properties']);
+        }
+        return $this;
+    }
+
+    // ── Getters (lazy properties init) ───────────────────────────────────────
+
+    public function getProperties(): CollectionProperties
+    {
+        if (!isset($this->properties)) {
+            $this->properties = new CollectionProperties([]);
+        }
+        return $this->properties;
+    }
+
+    // ── JSON ─────────────────────────────────────────────────────────────────
+
+    public function jsonSerialize(): array
+    {
+        $data                      = $this->data;
+        $data['properties']        = $this->getProperties()->jsonSerialize();
+        return $data;
+    }
+}