refactor: documents interfaces

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
2026-07-09 19:31:09 -04:00
parent 93d32d2a9f
commit 29d4c9130f
30 changed files with 479 additions and 376 deletions
@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Documents\Service;
+
+use KTXF\Documents\Collection\CollectionBaseInterface;
+use KTXF\Documents\Collection\CollectionMutableInterface;
+use KTXF\Documents\Collection\CollectionPropertiesBaseInterface;
+use KTXF\Resource\Identifier\CollectionIdentifierInterface;
+
+/**
+ * Service Collection Mutable Interface
+ *
+ * Optional interface for services that support collection CRUD operations.
+ *
+ * @since 2025.05.01
+ */
+interface ServiceCollectionMutableInterface {
+
+    public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate';
+    public const CAPABILITY_COLLECTION_UPDATE = 'CollectionUpdate';
+    public const CAPABILITY_COLLECTION_DELETE = 'CollectionDelete';
+    public const CAPABILITY_COLLECTION_MOVE = 'CollectionMove';
+    public const CAPABILITY_COLLECTION_COPY = 'CollectionCopy';
+
+    /**
+     * Creates a fresh collection instance for configuration
+     *
+     * @since 2025.05.01
+     *
+     * @return CollectionMutableInterface Fresh collection object
+     */
+    public function collectionFresh(): CollectionMutableInterface;
+
+    /**
+     * Creates a new collection
+     *
+     * @since 2025.05.01
+     *
+     * @param CollectionIdentifierInterface|null $target Target collection identifier (parent, null for root)
+     * @param CollectionPropertiesBaseInterface $properties Collection properties
+     * @param array $options Protocol-specific options
+     *
+     * @return CollectionBaseInterface Created collection with assigned ID
+     */
+    public function collectionCreate(CollectionIdentifierInterface|null $target, CollectionPropertiesBaseInterface $properties, array $options = []): CollectionBaseInterface;
+
+    /**
+     * Updates an existing collection
+     *
+     * @since 2025.05.01
+     *
+     * @param CollectionIdentifierInterface $target Target collection identifier
+     * @param CollectionPropertiesBaseInterface $properties Updated collection data
+     *
+     * @return CollectionBaseInterface Updated collection
+     */
+    public function collectionUpdate(CollectionIdentifierInterface $target, CollectionPropertiesBaseInterface $properties): CollectionBaseInterface;
+
+    /**
+     * Deletes a collection
+     *
+     * @since 2025.05.01
+     *
+     * @param CollectionIdentifierInterface $target Target collection identifier
+     * @param bool $force Force deletion even if not empty
+     *
+     * @return CollectionBaseInterface|true Collection object on soft delete, true on hard delete
+     */
+    public function collectionDelete(CollectionIdentifierInterface $target, bool $force = false): CollectionBaseInterface | true;
+
+    /**
+     * Moves a collection to a new parent
+     *
+     * @since 2025.05.01
+     *
+     * @param CollectionIdentifierInterface|null $target Target parent collection identifier (null for root)
+     * @param CollectionIdentifierInterface $source Source collection identifier
+     *
+     * @return CollectionBaseInterface Moved collection
+     */
+    public function collectionMove(CollectionIdentifierInterface|null $target, CollectionIdentifierInterface $source): CollectionBaseInterface;
+
+    /**
+     * Copies a collection to a new parent
+     *
+     * @since 2025.05.01
+     *
+     * @param CollectionIdentifierInterface|null $target Target parent collection identifier (null for root)
+     * @param CollectionIdentifierInterface $source Source collection identifier
+     *
+     * @return CollectionBaseInterface Copied collection
+     */
+    public function collectionCopy(CollectionIdentifierInterface|null $target, CollectionIdentifierInterface $source): CollectionBaseInterface;
+
+}