Nodarx/server
1
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Projects Releases Activity

refactor: people interfaces to unified design

Browse Source 
Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
This commit is contained in:
Sebastian Krupinski
2026-06-20 19:04:39 -04:00
parent 802849a60d
commit a6e2a447e5
13 changed files with 148 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files
shared/lib/People/Service/ServiceBaseInterface.php
+54 -27
View File
@@ -9,16 +9,19 @@ declare(strict_types=1);
namespace KTXF\People\Service;
use Generator;
use KTXF\People\Collection\CollectionBaseInterface;
use KTXF\People\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;
/**
* Service Base Interface
* People Service Base Interface
*
* Minimum interface for a service, providing read-only access to collections and entities.
*
@@ -71,7 +74,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
* @param IFilter|null $filter Optional filter criteria
* @param ISort|null $sort Optional sort order
*
* @return array<string|int,CollectionBaseInterface> Collections indexed by ID
* @return array<string|int,CollectionBaseInterface> Collections indexed by identifier
*/
public function collectionList(string|int $location, ?IFilter $filter = null, ?ISort $sort = null): array;
@@ -98,9 +101,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<string|int,bool> Map of ID => exists
* @return array<string|int,bool> Map of identifier => exists
*/
public function collectionExtant(string|int $location, string|int ...$identifiers): array;
@@ -109,29 +112,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<string|int,EntityBaseInterface> Messages indexed by ID
* @return array<string,EntityBaseInterface> 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
*
@@ -140,7 +158,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
*
@@ -149,7 +167,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
*
@@ -160,40 +178,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<string|int,bool> Map of ID => exists
* @return array<string|int,bool> 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<string|int,EntityBaseInterface> Messages indexed by ID
* @return array<string,EntityBaseInterface> 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<string,EntityBaseInterface> Yields entities one by one
*/
public function entityFetchStream(EntityIdentifierInterface ...$identifiers): Generator;
}
shared/lib/People/Service/ServiceCollectionMutableInterface.php
+12 -11
View File
@@ -11,9 +11,11 @@ namespace KTXF\People\Service;
use KTXF\People\Collection\CollectionBaseInterface;
use KTXF\People\Collection\CollectionMutableInterface;
use KTXF\People\Collection\CollectionPropertiesBaseInterface;
use KTXF\Resource\Identifier\CollectionIdentifierInterface;
/**
* Service Collection Mutable Interface
* People Service Collection Mutable Interface
*
* Optional interface for services that support collection CRUD operations.
*
@@ -39,37 +41,36 @@ interface ServiceCollectionMutableInterface {
*
* @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;
}
shared/lib/People/Service/ServiceConfigurableInterface.php
+1 -1
View File
@@ -14,7 +14,7 @@ use KTXF\Resource\Provider\ResourceServiceConfigureInterface;
/**
* Service Configurable Interface
*
* Optional interface for services that require configuration
* Extends base service interface with setter methods for mutable properties
*
* @since 2025.05.01
*/
shared/lib/People/Service/ServiceEntityMutableInterface.php
+53 -15
View File
@@ -11,18 +11,21 @@ namespace KTXF\People\Service;
use KTXF\People\Entity\EntityBaseInterface;
use KTXF\People\Entity\EntityMutableInterface;
use KTXF\People\Entity\EntityPropertiesMutableInterface;
use KTXF\Resource\Identifier\CollectionIdentifierInterface;
use KTXF\Resource\Identifier\EntityIdentifierInterface;
/**
* Service Entity Mutable Interface
*
* Optional interface for services that support entity CRUD operations.
* Optional interface for services that support entity CRUD operations
*
* @since 2025.05.01
*/
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';
@@ -41,36 +44,71 @@ interface ServiceEntityMutableInterface {
*
* @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<string, array{
* disposition: 'moved'|'deleted'|'error',
* destination: ?CollectionIdentifierInterface,
* mutation: EntityIdentifierInterface
* }> 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<string, array{
* disposition: 'moved'|'error',
* destination: ?CollectionIdentifierInterface,
* mutation: EntityIdentifierInterface
* }> 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<string, array{
* disposition: 'copied'|'error',
* destination: ?CollectionIdentifierInterface,
* mutation: EntityIdentifierInterface
* }> Results keyed by source entity identifier
*/
public function entityDelete(string|int $collection, string|int $identifier): EntityBaseInterface;
public function entityCopy(CollectionIdentifierInterface $target, EntityIdentifierInterface ...$sources): array;
}
shared/lib/People/Service/ServiceMutableInterface.php
+1 -1
View File
@@ -12,7 +12,7 @@ namespace KTXF\People\Service;
/**
* Service Mutable Interface
*
* Marker interface for services that support mutable operations
* Extends base service interface with setter methods for mutable properties
*
* @since 2025.05.01
*/