resource provider and service improvements

shared/lib/Mail/Service/ServiceCollectionMutableInterface.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+use KTXF\Mail\Collection\ICollectionBase;
+use KTXF\Mail\Collection\ICollectionMutable;
+
+/**
+ * Mail Service Collection Mutable Interface
+ * 
+ * Optional interface for services that support collection CRUD operations.
+ * Provides mailbox/folder creation, modification, deletion, and moving.
+ * 
+ * @since 2025.05.01
+ */
+interface ServiceCollectionMutableInterface extends ServiceBaseInterface {
+
+    public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate';
+    public const CAPABILITY_COLLECTION_MODIFY = 'CollectionModify';
+    public const CAPABILITY_COLLECTION_DESTROY = 'CollectionDestroy';
+    public const CAPABILITY_COLLECTION_MOVE = 'CollectionMove';
+
+    /**
+     * Creates a fresh collection instance for configuration
+     *
+     * @since 2025.05.01
+     *
+     * @return ICollectionMutable Fresh collection object
+     */
+    public function collectionFresh(): ICollectionMutable;
+
+    /**
+     * Creates a new collection
+     *
+     * @since 2025.05.01
+     *
+     * @param string|int|null $location Parent collection ID (null for root)
+     * @param ICollectionMutable $collection Collection to create
+     * @param array $options Protocol-specific options
+     *
+     * @return ICollectionBase Created collection with assigned ID
+     */
+    public function collectionCreate(string|int|null $location, ICollectionMutable $collection, array $options = []): ICollectionBase;
+
+    /**
+     * Modifies an existing collection
+     *
+     * @since 2025.05.01
+     *
+     * @param string|int $identifier Collection ID
+     * @param ICollectionMutable $collection Updated collection data
+     *
+     * @return ICollectionBase Modified collection
+     */
+    public function collectionModify(string|int $identifier, ICollectionMutable $collection): ICollectionBase;
+
+    /**
+     * Destroys a collection
+     *
+     * @since 2025.05.01
+     *
+     * @param string|int $identifier Collection ID
+     * @param bool $recursive Destroy child collections too
+     *
+     * @return bool True if destroyed
+     */
+    public function collectionDestroy(string|int $identifier, bool $recursive = false): bool;
+
+    /**
+     * Moves a collection to a new parent
+     *
+     * @since 2025.05.01
+     *
+     * @param string|int $identifier Collection ID
+     * @param string|int|null $targetLocation New parent ID (null for root)
+     *
+     * @return ICollectionBase Moved collection
+     */
+    public function collectionMove(string|int $identifier, string|int|null $targetLocation): ICollectionBase;
+
+}