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/Entity/EntityBaseAbstract.php
+7 -1
View File
@@ -9,6 +9,7 @@ declare(strict_types=1);
namespace KTXF\People\Entity;
use KTXF\Resource\Identifier\EntityIdentifier;
use KTXF\Resource\Provider\Node\NodeBaseAbstract;
/**
@@ -20,7 +21,12 @@ use KTXF\Resource\Provider\Node\NodeBaseAbstract;
*/
abstract class EntityBaseAbstract extends NodeBaseAbstract implements EntityBaseInterface {
protected EntityPropertiesBaseAbstract $properties;
protected string $type = 'people: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
shared/lib/People/Entity/EntityBaseInterface.php
-2
View File
@@ -13,8 +13,6 @@ use KTXF\Resource\Provider\Node\NodeBaseInterface;
interface EntityBaseInterface extends NodeBaseInterface {
public const JSON_TYPE = 'people:entity';
/**
* Gets the entity properties
*
shared/lib/People/Entity/EntityMutableAbstract.php
+7 -3
View File
@@ -9,6 +9,7 @@ declare(strict_types=1);
namespace KTXF\People\Entity;
use KTXF\Resource\Identifier\EntityIdentifier;
use KTXF\Resource\Provider\Node\NodeMutableAbstract;
use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
@@ -21,9 +22,12 @@ use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
*/
abstract class EntityMutableAbstract extends NodeMutableAbstract implements EntityMutableInterface {
public const JSON_TYPE = EntityMutableInterface::JSON_TYPE;
protected string $type = 'people: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;
}
shared/lib/People/Entity/EntityMutableInterface.php
-2
View File
@@ -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)
*
shared/lib/People/Entity/EntityPropertiesBaseAbstract.php
+3 -2
View File
@@ -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;
}
shared/lib/People/Entity/EntityPropertiesMutableInterface.php
-2
View File
@@ -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;
}
shared/lib/People/Provider/ProviderServiceMutateInterface.php
+3 -1
View File
@@ -14,7 +14,7 @@ use KTXF\Resource\Provider\ResourceProviderServiceMutateInterface;
/**
* Provider Service Mutate Interface
*
* Optional interface for providers that support service CRUD operations.
* Optional interface for providers that support service CRUD operations
*
* @since 2025.05.01
*
@@ -25,4 +25,6 @@ use KTXF\Resource\Provider\ResourceProviderServiceMutateInterface;
*/
interface ProviderServiceMutateInterface extends ResourceProviderServiceMutateInterface {
// Methods inherited from ResourceProviderServiceMutateInterface
}
shared/lib/People/Provider/ProviderServiceTestInterface.php
+7 -4
View File
@@ -9,6 +9,7 @@ declare(strict_types=1);
namespace KTXF\People\Provider;
use KTXF\Chrono\Service\ServiceMutableInterface;
use KTXF\Mail\Service\ServiceBaseInterface;
/**
@@ -20,6 +21,8 @@ use KTXF\Mail\Service\ServiceBaseInterface;
*/
interface ProviderServiceTestInterface {
public const CAPABILITY_SERVICE_TEST = 'ServiceTest';
/**
* Test a service connection
*
@@ -27,7 +30,7 @@ interface ProviderServiceTestInterface {
*
* @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)
@@ -36,10 +39,10 @@ interface ProviderServiceTestInterface {
*
* @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;
}
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
*/