From 6ca83a7dd7f627d95ac573fc99ed338d82a5daf8 Mon Sep 17 00:00:00 2001 From: Sebastian Krupinski Date: Thu, 25 Jun 2026 23:47:17 -0400 Subject: [PATCH] refactor: use unified service provider desing Signed-off-by: Sebastian Krupinski --- .../Collection/CollectionMutableAbstract.php | 4 + .../CollectionPropertiesBaseAbstract.php | 24 +++--- .../CollectionPropertiesBaseInterface.php | 17 ++-- .../CollectionPropertiesMutableAbstract.php | 4 +- .../CollectionPropertiesMutableInterface.php | 4 +- .../lib/Chrono/Entity/EntityBaseAbstract.php | 12 ++- .../lib/Chrono/Entity/EntityBaseInterface.php | 2 - .../Chrono/Entity/EntityMutableAbstract.php | 14 ++-- .../Chrono/Entity/EntityMutableInterface.php | 2 - .../Entity/EntityPropertiesBaseAbstract.php | 5 +- .../EntityPropertiesMutableInterface.php | 2 - .../Chrono/Provider/ProviderBaseInterface.php | 2 +- .../ProviderServiceMutateInterface.php | 15 ++-- .../Provider/ProviderServiceTestInterface.php | 31 +++---- .../Chrono/Service/ServiceBaseInterface.php | 83 +++++++++++++------ .../ServiceCollectionMutableInterface.php | 27 +++--- .../Service/ServiceConfigurableInterface.php | 7 +- .../Service/ServiceEntityMutableInterface.php | 73 ++++++++++++---- .../Service/ServiceMutableInterface.php | 5 +- 19 files changed, 198 insertions(+), 135 deletions(-) diff --git a/shared/lib/Chrono/Collection/CollectionMutableAbstract.php b/shared/lib/Chrono/Collection/CollectionMutableAbstract.php index 1af83d6..53e8e2f 100644 --- a/shared/lib/Chrono/Collection/CollectionMutableAbstract.php +++ b/shared/lib/Chrono/Collection/CollectionMutableAbstract.php @@ -40,6 +40,10 @@ abstract class CollectionMutableAbstract extends NodeMutableAbstract implements // Copy all property values $this->properties->setLabel($value->getLabel()); + $this->properties->setDescription($value->getDescription()); + $this->properties->setRank($value->getRank()); + $this->properties->setVisibility($value->getVisibility()); + $this->properties->setColor($value->getColor()); return $this; } diff --git a/shared/lib/Chrono/Collection/CollectionPropertiesBaseAbstract.php b/shared/lib/Chrono/Collection/CollectionPropertiesBaseAbstract.php index 7799508..242f2ec 100644 --- a/shared/lib/Chrono/Collection/CollectionPropertiesBaseAbstract.php +++ b/shared/lib/Chrono/Collection/CollectionPropertiesBaseAbstract.php @@ -20,22 +20,18 @@ use KTXF\Resource\Provider\Node\NodePropertiesBaseAbstract; */ abstract class CollectionPropertiesBaseAbstract extends NodePropertiesBaseAbstract implements CollectionPropertiesBaseInterface { - public const JSON_TYPE = CollectionPropertiesBaseInterface::JSON_TYPE; - /** * @inheritDoc */ - public function content(): CollectionContent { - $content = $this->data[self::PROPERTY_CONTENTS] ?? null; - if ($content instanceof CollectionContent) { - return $content; + public function content(): array { + $content = $this->data[self::PROPERTY_CONTENT] ?? null; + if (is_array($content)) { + return array_filter(array_map(function ($item) { + return $item instanceof CollectionContent ? $item : CollectionContent::tryFrom($item); + }, $content)); + } else { + return []; } - - if (is_string($content)) { - return CollectionContent::tryFrom($content) ?? CollectionContent::Event; - } - - return CollectionContent::Event; } /** @@ -55,8 +51,8 @@ abstract class CollectionPropertiesBaseAbstract extends NodePropertiesBaseAbstra /** * @inheritDoc */ - public function getPriority(): ?int { - return $this->data[self::PROPERTY_PRIORITY] ?? null; + public function getRank(): ?int { + return $this->data[self::PROPERTY_RANK] ?? null; } /** diff --git a/shared/lib/Chrono/Collection/CollectionPropertiesBaseInterface.php b/shared/lib/Chrono/Collection/CollectionPropertiesBaseInterface.php index 2781935..2c22d9f 100644 --- a/shared/lib/Chrono/Collection/CollectionPropertiesBaseInterface.php +++ b/shared/lib/Chrono/Collection/CollectionPropertiesBaseInterface.php @@ -14,15 +14,22 @@ use KTXF\Resource\Provider\Node\NodePropertiesBaseInterface; interface CollectionPropertiesBaseInterface extends NodePropertiesBaseInterface { public const JSON_TYPE = 'chrono:collection'; - public const PROPERTY_CONTENTS = 'content'; + public const PROPERTY_CONTENT = 'content'; public const PROPERTY_LABEL = 'label'; public const PROPERTY_DESCRIPTION = 'description'; - public const PROPERTY_PRIORITY = 'priority'; + public const PROPERTY_RANK = 'rank'; public const PROPERTY_VISIBILITY = 'visibility'; public const PROPERTY_COLOR = 'color'; - public function content(): CollectionContent; + /** + * Gets the content type of this collection + * + * @since 2025.05.01 + * + * @return CollectionContent[] Returns an array of content types, a single content type, or null if not set + */ + public function content(): array; /** * Gets the human friendly name of this collection (e.g. Personal Calendar) @@ -39,11 +46,11 @@ interface CollectionPropertiesBaseInterface extends NodePropertiesBaseInterface public function getDescription(): ?string; /** - * Gets the priority of this collection + * Gets the rank of this collection * * @since 2025.05.01 */ - public function getPriority(): ?int; + public function getRank(): ?int; /** * Gets the visibility of this collection diff --git a/shared/lib/Chrono/Collection/CollectionPropertiesMutableAbstract.php b/shared/lib/Chrono/Collection/CollectionPropertiesMutableAbstract.php index 88c1e2c..8ed3a79 100644 --- a/shared/lib/Chrono/Collection/CollectionPropertiesMutableAbstract.php +++ b/shared/lib/Chrono/Collection/CollectionPropertiesMutableAbstract.php @@ -48,8 +48,8 @@ abstract class CollectionPropertiesMutableAbstract extends CollectionPropertiesB /** * @inheritDoc */ - public function setPriority(?int $value): static { - $this->data[self::PROPERTY_PRIORITY] = $value; + public function setRank(?int $value): static { + $this->data[self::PROPERTY_RANK] = $value; return $this; } diff --git a/shared/lib/Chrono/Collection/CollectionPropertiesMutableInterface.php b/shared/lib/Chrono/Collection/CollectionPropertiesMutableInterface.php index 2fc9314..3b4c993 100644 --- a/shared/lib/Chrono/Collection/CollectionPropertiesMutableInterface.php +++ b/shared/lib/Chrono/Collection/CollectionPropertiesMutableInterface.php @@ -30,11 +30,11 @@ interface CollectionPropertiesMutableInterface extends CollectionPropertiesBaseI public function setDescription(?string $value): static; /** - * Sets the priority of this collection + * Sets the rank of this collection * * @since 2025.05.01 */ - public function setPriority(?int $value): static; + public function setRank(?int $value): static; /** * Sets the visibility of this collection diff --git a/shared/lib/Chrono/Entity/EntityBaseAbstract.php b/shared/lib/Chrono/Entity/EntityBaseAbstract.php index e94da59..f1ea194 100644 --- a/shared/lib/Chrono/Entity/EntityBaseAbstract.php +++ b/shared/lib/Chrono/Entity/EntityBaseAbstract.php @@ -9,18 +9,24 @@ declare(strict_types=1); namespace KTXF\Chrono\Entity; +use KTXF\Resource\Identifier\EntityIdentifier; use KTXF\Resource\Provider\Node\NodeBaseAbstract; /** * Abstract Chrono Entity Base Class - * + * * Provides common implementation for chrono entities - * + * * @since 2025.05.01 */ abstract class EntityBaseAbstract extends NodeBaseAbstract implements EntityBaseInterface { - protected EntityPropertiesBaseAbstract $properties; + protected string $type = 'chrono:entity'; + protected EntityPropertiesBaseInterface $properties; + + protected function nodeIdentifier(): EntityIdentifier { + return new EntityIdentifier($this->data[static::PROPERTY_PROVIDER], $this->data[static::PROPERTY_SERVICE], $this->data[static::PROPERTY_COLLECTION], $this->data[static::PROPERTY_IDENTIFIER]); + } /** * @inheritDoc diff --git a/shared/lib/Chrono/Entity/EntityBaseInterface.php b/shared/lib/Chrono/Entity/EntityBaseInterface.php index afeedf3..85af2d6 100644 --- a/shared/lib/Chrono/Entity/EntityBaseInterface.php +++ b/shared/lib/Chrono/Entity/EntityBaseInterface.php @@ -13,8 +13,6 @@ use KTXF\Resource\Provider\Node\NodeBaseInterface; interface EntityBaseInterface extends NodeBaseInterface { - public const JSON_TYPE = 'chrono.entity'; - /** * Gets the entity properties * diff --git a/shared/lib/Chrono/Entity/EntityMutableAbstract.php b/shared/lib/Chrono/Entity/EntityMutableAbstract.php index 77af5af..da0ecbc 100644 --- a/shared/lib/Chrono/Entity/EntityMutableAbstract.php +++ b/shared/lib/Chrono/Entity/EntityMutableAbstract.php @@ -9,21 +9,25 @@ declare(strict_types=1); namespace KTXF\Chrono\Entity; +use KTXF\Resource\Identifier\EntityIdentifier; use KTXF\Resource\Provider\Node\NodeMutableAbstract; use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface; /** * Abstract Chrono Entity Mutable Class - * + * * Provides common implementation for mutable chrono entities - * + * * @since 2025.05.01 */ abstract class EntityMutableAbstract extends NodeMutableAbstract implements EntityMutableInterface { - public const JSON_TYPE = EntityMutableInterface::JSON_TYPE; + protected string $type = 'chrono:entity'; + protected EntityPropertiesMutableInterface $properties; - protected EntityPropertiesMutableAbstract $properties; + protected function nodeIdentifier(): EntityIdentifier { + return new EntityIdentifier($this->data[static::PROPERTY_PROVIDER], $this->data[static::PROPERTY_SERVICE], (string) $this->data[static::PROPERTY_COLLECTION], (string) $this->data[static::PROPERTY_IDENTIFIER]); + } /** * @inheritDoc @@ -40,7 +44,7 @@ abstract class EntityMutableAbstract extends NodeMutableAbstract implements Enti throw new \InvalidArgumentException('Properties must implement EntityPropertiesMutableInterface'); } - $this->properties->setDataRaw($value->getDataRaw()); + $this->properties = $value; return $this; } diff --git a/shared/lib/Chrono/Entity/EntityMutableInterface.php b/shared/lib/Chrono/Entity/EntityMutableInterface.php index cf6f2d1..4ca5bdd 100644 --- a/shared/lib/Chrono/Entity/EntityMutableInterface.php +++ b/shared/lib/Chrono/Entity/EntityMutableInterface.php @@ -16,8 +16,6 @@ use KTXF\Resource\Provider\Node\NodeMutableInterface; */ interface EntityMutableInterface extends EntityBaseInterface, NodeMutableInterface { - public const JSON_TYPE = EntityBaseInterface::JSON_TYPE; - /** * Gets the entity properties (mutable) * diff --git a/shared/lib/Chrono/Entity/EntityPropertiesBaseAbstract.php b/shared/lib/Chrono/Entity/EntityPropertiesBaseAbstract.php index 0031224..20c85ec 100644 --- a/shared/lib/Chrono/Entity/EntityPropertiesBaseAbstract.php +++ b/shared/lib/Chrono/Entity/EntityPropertiesBaseAbstract.php @@ -13,8 +13,9 @@ use KTXF\Resource\Provider\Node\NodePropertiesBaseAbstract; abstract class EntityPropertiesBaseAbstract extends NodePropertiesBaseAbstract implements EntityPropertiesBaseInterface { - public const JSON_TYPE = EntityPropertiesBaseInterface::JSON_TYPE; - + /** + * @inheritDoc + */ public function getDataRaw(): array|string|null { return $this->data[self::PROPERTY_DATA] ?? null; } diff --git a/shared/lib/Chrono/Entity/EntityPropertiesMutableInterface.php b/shared/lib/Chrono/Entity/EntityPropertiesMutableInterface.php index ebb3d2c..71caee9 100644 --- a/shared/lib/Chrono/Entity/EntityPropertiesMutableInterface.php +++ b/shared/lib/Chrono/Entity/EntityPropertiesMutableInterface.php @@ -13,8 +13,6 @@ use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface; interface EntityPropertiesMutableInterface extends EntityPropertiesBaseInterface, NodePropertiesMutableInterface { - public const JSON_TYPE = EntityPropertiesBaseInterface::JSON_TYPE; - public function setDataRaw(array|string|null $value): static; } diff --git a/shared/lib/Chrono/Provider/ProviderBaseInterface.php b/shared/lib/Chrono/Provider/ProviderBaseInterface.php index 87efb1b..fe2fdd5 100644 --- a/shared/lib/Chrono/Provider/ProviderBaseInterface.php +++ b/shared/lib/Chrono/Provider/ProviderBaseInterface.php @@ -12,7 +12,7 @@ namespace KTXF\Chrono\Provider; use KTXF\Resource\Provider\ResourceProviderBaseInterface; /** - * Chrono Provider Base Interface + * Provider Base Interface * * @since 2025.05.01 */ diff --git a/shared/lib/Chrono/Provider/ProviderServiceMutateInterface.php b/shared/lib/Chrono/Provider/ProviderServiceMutateInterface.php index 8de64e6..9923edb 100644 --- a/shared/lib/Chrono/Provider/ProviderServiceMutateInterface.php +++ b/shared/lib/Chrono/Provider/ProviderServiceMutateInterface.php @@ -12,11 +12,9 @@ namespace KTXF\Chrono\Provider; use KTXF\Resource\Provider\ResourceProviderServiceMutateInterface; /** - * Chrono Provider Service Mutate Interface + * Provider Service Mutate Interface * - * Optional interface for providers that support service CRUD operations. - * - * Implementations return ServiceMutableInterface instances (which extend ResourceServiceMutateInterface). + * Optional interface for providers that support service CRUD operations * * @since 2025.05.01 * @@ -25,11 +23,8 @@ use KTXF\Resource\Provider\ResourceProviderServiceMutateInterface; * @method string serviceModify(string $tenantId, ?string $userId, ServiceMutableInterface $service) Modify a chrono service configuration * @method bool serviceDestroy(string $tenantId, ?string $userId, ServiceMutableInterface $service) Delete a chrono service configuration */ -interface ProviderServiceMutateInterface extends ProviderBaseInterface, ResourceProviderServiceMutateInterface { - - public const JSON_TYPE = ProviderBaseInterface::JSON_TYPE; - - // Methods inherited from ResourceProviderServiceMutateInterface - // Implementations should return/accept ServiceMutableInterface instances +interface ProviderServiceMutateInterface extends ResourceProviderServiceMutateInterface { + // Methods inherited from ResourceProviderServiceMutateInterface + } diff --git a/shared/lib/Chrono/Provider/ProviderServiceTestInterface.php b/shared/lib/Chrono/Provider/ProviderServiceTestInterface.php index 39613d5..ee99091 100644 --- a/shared/lib/Chrono/Provider/ProviderServiceTestInterface.php +++ b/shared/lib/Chrono/Provider/ProviderServiceTestInterface.php @@ -10,36 +10,27 @@ declare(strict_types=1); namespace KTXF\Chrono\Provider; use KTXF\Chrono\Service\ServiceBaseInterface; +use KTXF\Chrono\Service\ServiceMutableInterface; /** - * Chrono Provider Service Test Interface + * Provider Service Test Interface * - * Optional interface for chrono providers that support testing service connections. - * Providers implementing this interface can validate connection parameters, - * test authentication, and verify service availability before creating a - * persistent service configuration. - * - * Supports two testing modes: - * 1. Testing an existing service (validate current configuration) - * 2. Testing a fresh configuration (validate before saving) + * Optional interface for providers that support testing service connections * * @since 2025.05.01 */ -interface ProviderServiceTestInterface extends ProviderBaseInterface { +interface ProviderServiceTestInterface { + + public const CAPABILITY_SERVICE_TEST = 'ServiceTest'; /** * Test a service connection * - * Tests connectivity, authentication, and capabilities of a service. - * - * For new services: use serviceFresh() to create a service, configure it with - * setters, then pass it to this method for testing before persisting. - * - * For existing services: fetch the service and pass it directly. + * Tests connectivity, authentication, and capabilities of a service * * @since 2025.05.01 * - * @param ServiceBaseInterface $service Service to test (can be fresh/unsaved or existing) + * @param ServiceBaseInterface|ServiceMutableInterface $service Service to test (can be fresh/unsaved or existing) * @param array $options Provider-specific test options: * - 'timeout' => int (seconds, default: 10) * - 'verify_ssl' => bool (default: true) @@ -48,10 +39,10 @@ interface ProviderServiceTestInterface extends ProviderBaseInterface { * * @return array Test results in the format: * [ - * 'success' => bool, - * 'message' => 'Connection successful' | 'Error message' + * 'disposition' => 'Success' | 'Failure' | 'Warning', + * 'message' => 'Connection successful' | 'Error message', * ] */ - public function serviceTest(ServiceBaseInterface $service, array $options = []): array; + public function serviceTest(ServiceBaseInterface|ServiceMutableInterface $service, array $options = []): array; } diff --git a/shared/lib/Chrono/Service/ServiceBaseInterface.php b/shared/lib/Chrono/Service/ServiceBaseInterface.php index 3cd63b3..c59f83c 100644 --- a/shared/lib/Chrono/Service/ServiceBaseInterface.php +++ b/shared/lib/Chrono/Service/ServiceBaseInterface.php @@ -9,16 +9,21 @@ declare(strict_types=1); namespace KTXF\Chrono\Service; +use Generator; use KTXF\Chrono\Collection\CollectionBaseInterface; +use KTXF\Chrono\Entity\EntityBaseInterface; use KTXF\Resource\Delta\Delta; use KTXF\Resource\Filter\IFilter; +use KTXF\Resource\Identifier\EntityIdentifierInterface; use KTXF\Resource\Provider\ResourceServiceBaseInterface; use KTXF\Resource\Range\IRange; use KTXF\Resource\Range\RangeType; use KTXF\Resource\Sort\ISort; /** - * Chrono Service Base Interface + * Service Base Interface + * + * Minimum interface for a service, providing read-only access to collections and entities. * * @since 2025.05.01 */ @@ -70,7 +75,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { * @param IFilter|null $filter Optional filter criteria * @param ISort|null $sort Optional sort order * - * @return array Collections indexed by ID + * @return array Collections indexed by identifier */ public function collectionList(string|int $location, ?IFilter $filter = null, ?ISort $sort = null): array; @@ -97,9 +102,9 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { * * @since 2025.05.01 * - * @param string|int ...$identifiers Collection IDs to check + * @param string|int ...$identifiers Collection identifiers to check * - * @return array Map of ID => exists + * @return array Map of identifier => exists */ public function collectionExtant(string|int $location, string|int ...$identifiers): array; @@ -108,29 +113,44 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { * * @since 2025.05.01 * - * @param string|int $identifier Collection ID + * @param string|int $identifier Collection identifier * * @return CollectionBaseInterface|null Collection or null if not found */ public function collectionFetch(string|int $identifier): ?CollectionBaseInterface; /** - * Lists messages in a collection + * Lists entities in a collection * * @since 2025.05.01 * - * @param string|int $collection Collection ID + * @param string|int $collection Collection identifier * @param IFilter|null $filter Optional filter criteria * @param ISort|null $sort Optional sort order * @param IRange|null $range Optional pagination - * @param array|null $properties Optional message properties to fetch + * @param array|null $properties Optional entity properties to fetch * - * @return array Messages indexed by ID + * @return array Entities indexed by Urn */ - public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array; + public function entityListBulk(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array; /** - * Creates a filter builder for messages + * Lists entities in a collection + * + * @since 2025.05.01 + * + * @param string|int $collection Collection identifier + * @param IFilter|null $filter Optional filter criteria + * @param ISort|null $sort Optional sort order + * @param IRange|null $range Optional pagination + * @param array|null $properties Optional entity properties to fetch + * + * @return Generator Yields entities one by one as EntityBaseInterface + */ + public function entityListStream(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): Generator; + + /** + * Creates a filter builder for entities * * @since 2025.05.01 * @@ -139,7 +159,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { public function entityListFilter(): IFilter; /** - * Creates a sort builder for messages + * Creates a sort builder for entities * * @since 2025.05.01 * @@ -148,7 +168,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { public function entityListSort(): ISort; /** - * Creates a range builder for messages + * Creates a range builder for entities * * @since 2025.05.01 * @@ -159,40 +179,49 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { public function entityListRange(RangeType $type): IRange; /** - * Gets incremental changes since last sync + * Gets incremental changes since last signature * * @since 2025.05.01 * - * @param string|int $collection Collection ID - * @param string $signature Sync token from previous sync - * @param string $detail Detail level: 'ids', 'minimal', 'full' + * @param string|int $collection Collection identifier + * @param string $signature Token from previous delta * * @return array ['signature' => string, 'added' => array, 'modified' => array, 'removed' => array] */ - public function entityDelta(string|int $collection, string $signature, string $detail = 'ids'): Delta; + public function entityDelta(string|int $collection, string $signature): Delta; /** - * Checks if messages exist + * Checks if entities exist * * @since 2025.05.01 * - * @param string|int $collection Collection ID - * @param string|int ...$identifiers Message IDs to check + * @param string|int $collection Collection identifier + * @param string|int ...$identifiers Entity identifiers to check * - * @return array Map of ID => exists + * @return array Map of identifier => exists */ public function entityExtant(string|int $collection, string|int ...$identifiers): array; /** - * Fetches one or more entities + * Fetches one or more entities as an array * * @since 2025.05.01 * - * @param string|int $collection Collection ID - * @param string|int ...$identifiers Message IDs to fetch + * @param EntityIdentifierInterface ...$identifiers Entity identifiers to fetch * - * @return array Messages indexed by ID + * @return array Entities indexed by Urn */ - public function entityFetch(string|int $collection, string|int ...$identifiers): array; + public function entityFetchBulk(EntityIdentifierInterface ...$identifiers): array; + + /** + * Fetches one or more entities as a stream + * + * @since 2025.05.01 + * + * @param EntityIdentifierInterface ...$identifiers Entity identifiers to fetch + * + * @return Generator Yields entities one by one + */ + public function entityFetchStream(EntityIdentifierInterface ...$identifiers): Generator; } diff --git a/shared/lib/Chrono/Service/ServiceCollectionMutableInterface.php b/shared/lib/Chrono/Service/ServiceCollectionMutableInterface.php index 022e147..c8748eb 100644 --- a/shared/lib/Chrono/Service/ServiceCollectionMutableInterface.php +++ b/shared/lib/Chrono/Service/ServiceCollectionMutableInterface.php @@ -11,13 +11,17 @@ namespace KTXF\Chrono\Service; use KTXF\Chrono\Collection\CollectionBaseInterface; use KTXF\Chrono\Collection\CollectionMutableInterface; +use KTXF\Chrono\Collection\CollectionPropertiesBaseInterface; +use KTXF\Resource\Identifier\CollectionIdentifierInterface; /** - * Chrono Service Collection Mutable Interface + * Service Collection Mutable Interface + * + * Optional interface for services that support collection CRUD operations. * * @since 2025.05.01 */ -interface ServiceCollectionMutableInterface extends ServiceBaseInterface { +interface ServiceCollectionMutableInterface { public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate'; public const CAPABILITY_COLLECTION_UPDATE = 'CollectionUpdate'; @@ -37,37 +41,36 @@ interface ServiceCollectionMutableInterface extends ServiceBaseInterface { * * @since 2025.05.01 * - * @param string|int|null $location Parent collection ID (null for root) - * @param CollectionMutableInterface $collection Collection to create + * @param CollectionIdentifierInterface|null $target Target collection identifier (parent) + * @param CollectionPropertiesBaseInterface $properties Collection properties * @param array $options Protocol-specific options * * @return CollectionBaseInterface Created collection with assigned ID */ - public function collectionCreate(string|int|null $location, CollectionMutableInterface $collection, array $options = []): CollectionBaseInterface; + public function collectionCreate(CollectionIdentifierInterface|null $target, CollectionPropertiesBaseInterface $properties, array $options = []): CollectionBaseInterface; /** * Updates an existing collection * * @since 2025.05.01 * - * @param string|int $identifier Collection ID - * @param CollectionMutableInterface $collection Updated collection data + * @param CollectionIdentifierInterface $target Target collection identifier + * @param CollectionPropertiesBaseInterface $properties Updated collection data * * @return CollectionBaseInterface Updated collection */ - public function collectionUpdate(string|int $identifier, CollectionMutableInterface $collection): CollectionBaseInterface; + public function collectionUpdate(CollectionIdentifierInterface $target, CollectionPropertiesBaseInterface $properties): CollectionBaseInterface; /** * Deletes a collection * * @since 2025.05.01 * - * @param string|int $identifier Collection ID + * @param CollectionIdentifierInterface $target Target collection identifier * @param bool $force Force deletion even if not empty - * @param bool $recursive Recursively delete contents * - * @return bool True if deleted + * @return CollectionBaseInterface|true Collection object on soft delete, true on hard delete */ - public function collectionDelete(string|int $identifier, bool $force = false, bool $recursive = false): bool; + public function collectionDelete(CollectionIdentifierInterface $target, bool $force = false): CollectionBaseInterface | true; } diff --git a/shared/lib/Chrono/Service/ServiceConfigurableInterface.php b/shared/lib/Chrono/Service/ServiceConfigurableInterface.php index 699f65e..830a511 100644 --- a/shared/lib/Chrono/Service/ServiceConfigurableInterface.php +++ b/shared/lib/Chrono/Service/ServiceConfigurableInterface.php @@ -12,15 +12,12 @@ namespace KTXF\Chrono\Service; use KTXF\Resource\Provider\ResourceServiceConfigureInterface; /** - * Chrono Service Configurable Interface + * Service Configurable Interface * - * Extends base service interface with setter methods for mutable properties. - * Used for service configuration and updates. + * Extends base service interface with setter methods for mutable properties * * @since 2025.05.01 */ interface ServiceConfigurableInterface extends ServiceMutableInterface, ResourceServiceConfigureInterface { - public const JSON_TYPE = ServiceBaseInterface::JSON_TYPE; - } diff --git a/shared/lib/Chrono/Service/ServiceEntityMutableInterface.php b/shared/lib/Chrono/Service/ServiceEntityMutableInterface.php index 95d9f30..e2cb935 100644 --- a/shared/lib/Chrono/Service/ServiceEntityMutableInterface.php +++ b/shared/lib/Chrono/Service/ServiceEntityMutableInterface.php @@ -11,19 +11,21 @@ namespace KTXF\Chrono\Service; use KTXF\Chrono\Entity\EntityBaseInterface; use KTXF\Chrono\Entity\EntityMutableInterface; +use KTXF\Chrono\Entity\EntityPropertiesMutableInterface; +use KTXF\Resource\Identifier\CollectionIdentifierInterface; +use KTXF\Resource\Identifier\EntityIdentifierInterface; /** - * Chrono Service Entity Mutable Interface + * Service Entity Mutable Interface * - * Optional interface for services that support entity CRUD operations. - * Provides entity creation, modification, deletion, copying, moving, and flag management. + * Optional interface for services that support entity CRUD operations * * @since 2025.05.01 */ -interface ServiceEntityMutableInterface extends ServiceBaseInterface { +interface ServiceEntityMutableInterface { public const CAPABILITY_ENTITY_CREATE = 'EntityCreate'; - public const CAPABILITY_ENTITY_UPDATE = 'EntityUpdate'; + public const CAPABILITY_ENTITY_MODIFY = 'EntityModify'; public const CAPABILITY_ENTITY_DELETE = 'EntityDelete'; public const CAPABILITY_ENTITY_COPY = 'EntityCopy'; public const CAPABILITY_ENTITY_MOVE = 'EntityMove'; @@ -42,36 +44,71 @@ interface ServiceEntityMutableInterface extends ServiceBaseInterface { * * @since 2025.05.01 * - * @param string|int $collection collection identifier - * @param EntityMutableInterface $entity Entity data - * @param array $options additional options + * @param CollectionIdentifierInterface $target Target collection identifier + * @param EntityPropertiesMutableInterface $properties Entity properties + * @param array $options Additional options * * @return EntityBaseInterface Created entity */ - public function entityCreate(string|int $collection, EntityMutableInterface $entity, array $options = []): EntityBaseInterface; + public function entityCreate(CollectionIdentifierInterface $target, EntityPropertiesMutableInterface $properties, array $options = []): EntityBaseInterface; /** * Modifies an existing entity * * @since 2025.05.01 * - * @param string|int $collection Collection identifier - * @param string|int $identifier Entity identifier - * @param EntityMutableInterface $entity Entity data + * @param EntityIdentifierInterface $target Target entity identifier + * @param EntityPropertiesMutableInterface $properties Entity properties to update * * @return EntityBaseInterface Modified entity */ - public function entityUpdate(string|int $collection, string|int $identifier, EntityMutableInterface $entity): EntityBaseInterface; + public function entityModify(EntityIdentifierInterface $target, EntityPropertiesMutableInterface $properties): EntityBaseInterface; + /** - * Deletes an existing entity in the specified collection + * Deletes entities + * + * @since 2026.04.01 + * + * @param EntityIdentifierInterface ...$targets Source entities to delete + * + * @return array Results keyed by source entity identifier + */ + public function entityDelete(EntityIdentifierInterface ...$targets): array; + + /** + * Moves entities to another collection + * + * @since 2025.05.01 + * + * @param CollectionIdentifierInterface $target Target collection identifier + * @param EntityIdentifierInterface ...$sources Source entities to move + * + * @return array Results keyed by source entity identifier + */ + public function entityMove(CollectionIdentifierInterface $target, EntityIdentifierInterface ...$sources): array; + + /** + * Copies entities to another collection * * @since 2025.05.01 * - * @param string|int $collection Collection identifier - * @param string|int $identifier Entity identifier to delete + * @param CollectionIdentifierInterface $target Target collection identifier + * @param EntityIdentifierInterface ...$sources Source entities to copy * - * @return EntityBaseInterface Deleted entity + * @return array Results keyed by source entity identifier */ - public function entityDelete(string|int $collection, string|int $identifier): EntityBaseInterface; + public function entityCopy(CollectionIdentifierInterface $target, EntityIdentifierInterface ...$sources): array; } diff --git a/shared/lib/Chrono/Service/ServiceMutableInterface.php b/shared/lib/Chrono/Service/ServiceMutableInterface.php index bd76fc7..2f7823f 100644 --- a/shared/lib/Chrono/Service/ServiceMutableInterface.php +++ b/shared/lib/Chrono/Service/ServiceMutableInterface.php @@ -12,11 +12,10 @@ namespace KTXF\Chrono\Service; /** * Chrono Service Mutable Interface * - * Extends base service interface with setter methods for mutable properties. - * Used for service configuration and updates. + * Extends base service interface with setter methods for mutable properties * * @since 2025.05.01 */ -interface ServiceMutableInterface extends ServiceBaseInterface { +interface ServiceMutableInterface { }