From 7e743542d0cb77396173d74f3dcfe1635eeda68c Mon Sep 17 00:00:00 2001 From: Sebastian Krupinski Date: Wed, 25 Feb 2026 15:33:59 -0500 Subject: [PATCH] refactor: standardize design Signed-off-by: Sebastian Krupinski --- .../Personal/CollectionProperties.php | 3 - ...{Collection.php => CollectionResource.php} | 2 +- .../{Entity.php => EntityResource.php} | 5 +- lib/Providers/Personal/PersonalService.php | 36 ++++---- lib/Providers/Provider.php | 5 +- lib/Store/Personal/Store.php | 82 ++++++++----------- 6 files changed, 56 insertions(+), 77 deletions(-) rename lib/Providers/Personal/{Collection.php => CollectionResource.php} (97%) rename lib/Providers/Personal/{Entity.php => EntityResource.php} (96%) diff --git a/lib/Providers/Personal/CollectionProperties.php b/lib/Providers/Personal/CollectionProperties.php index 926b567..9fba333 100644 --- a/lib/Providers/Personal/CollectionProperties.php +++ b/lib/Providers/Personal/CollectionProperties.php @@ -12,9 +12,6 @@ namespace KTXM\ProviderLocalChrono\Providers\Personal; use KTXF\Chrono\Collection\CollectionContent; use KTXF\Chrono\Collection\CollectionPropertiesMutableAbstract; -/** - * Personal Chrono Collection Properties Implementation - */ class CollectionProperties extends CollectionPropertiesMutableAbstract { /** diff --git a/lib/Providers/Personal/Collection.php b/lib/Providers/Personal/CollectionResource.php similarity index 97% rename from lib/Providers/Personal/Collection.php rename to lib/Providers/Personal/CollectionResource.php index 1881e88..332a87f 100644 --- a/lib/Providers/Personal/Collection.php +++ b/lib/Providers/Personal/CollectionResource.php @@ -11,7 +11,7 @@ namespace KTXM\ProviderLocalChrono\Providers\Personal; use KTXF\Chrono\Collection\CollectionMutableAbstract; -class Collection extends CollectionMutableAbstract { +class CollectionResource extends CollectionMutableAbstract { private ?string $userId = null; private ?string $collectionUuid = null; diff --git a/lib/Providers/Personal/Entity.php b/lib/Providers/Personal/EntityResource.php similarity index 96% rename from lib/Providers/Personal/Entity.php rename to lib/Providers/Personal/EntityResource.php index 9f52cd7..8bc5451 100644 --- a/lib/Providers/Personal/Entity.php +++ b/lib/Providers/Personal/EntityResource.php @@ -12,10 +12,7 @@ namespace KTXM\ProviderLocalChrono\Providers\Personal; use KTXF\Chrono\Entity\EntityMutableAbstract; use KTXF\Chrono\Event\EventObject; -/** - * Personal Chrono Entity Resource Implementation - */ -class Entity extends EntityMutableAbstract { +class EntityResource extends EntityMutableAbstract { private ?string $tenantId = null; private ?string $userId = null; diff --git a/lib/Providers/Personal/PersonalService.php b/lib/Providers/Personal/PersonalService.php index 0623ff9..f6d78b6 100644 --- a/lib/Providers/Personal/PersonalService.php +++ b/lib/Providers/Personal/PersonalService.php @@ -156,8 +156,7 @@ class PersonalService implements ServiceBaseInterface, ServiceCollectionMutableI // Collection operations - public function collectionList(string|int|null $location, ?IFilter $filter = null, ?ISort $sort = null): array - { + public function collectionList(string|int|null $location, ?IFilter $filter = null, ?ISort $sort = null): array { $entries = $this->store->collectionList($this->serviceTenantId, $this->serviceUserId, $filter, $sort); $this->serviceCollectionCache = $entries; return $entries ?? []; @@ -212,14 +211,14 @@ class PersonalService implements ServiceBaseInterface, ServiceCollectionMutableI return null; } - public function collectionFresh(): Collection { - return new Collection(); + public function collectionFresh(): CollectionResource { + return new CollectionResource(); } public function collectionCreate(string|int|null $location, CollectionMutableInterface $collection, array $options = []): CollectionBaseInterface { // convert collection to a native type if needed - if (!($collection instanceof Collection)) { - $nativeCollection = new Collection(); + if (!($collection instanceof CollectionResource)) { + $nativeCollection = new CollectionResource(); $nativeCollection->jsonDeserialize($collection->jsonSerialize()); } else { $nativeCollection = clone $collection; @@ -244,16 +243,16 @@ class PersonalService implements ServiceBaseInterface, ServiceCollectionMutableI throw new InvalidParameterException("Invalid: Collection identifier '$id' does not exist or does not belong to user '{$this->serviceUserId}'"); } // convert collection to a native type if needed - if (!($collection instanceof Collection)) { - $nativeCollection = new Collection(); + if (!($collection instanceof CollectionResource)) { + $nativeCollection = new CollectionResource(); $data = $collection->jsonSerialize(); - $data[Collection::JSON_PROPERTY_IDENTIFIER] = $id; + $data[CollectionResource::JSON_PROPERTY_IDENTIFIER] = $id; $nativeCollection->jsonDeserialize($data); } else { $nativeCollection = clone $collection; if ($nativeCollection->identifier() === null) { $data = $nativeCollection->jsonSerialize(); - $data[Collection::JSON_PROPERTY_IDENTIFIER] = $id; + $data[CollectionResource::JSON_PROPERTY_IDENTIFIER] = $id; $nativeCollection->jsonDeserialize($data); } } @@ -279,6 +278,8 @@ class PersonalService implements ServiceBaseInterface, ServiceCollectionMutableI return false; } + // Entity operations + public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $options = null): array { // validate id if (!is_string($collection)) { @@ -293,7 +294,6 @@ class PersonalService implements ServiceBaseInterface, ServiceCollectionMutableI return $entries ?? []; } - public function entityListFilter(): Filter { return new Filter($this->serviceAbilities[self::CAPABILITY_ENTITY_LIST_FILTER] ?? []); } @@ -360,11 +360,11 @@ class PersonalService implements ServiceBaseInterface, ServiceCollectionMutableI return $entries ?? []; } - public function entityFresh(): Entity { - return new Entity(); + public function entityFresh(): EntityResource { + return new EntityResource(); } - public function entityCreate(string|int $collection, EntityMutableInterface $entity, array $options = []): Entity { + public function entityCreate(string|int $collection, EntityMutableInterface $entity, array $options = []): EntityResource { // validate collection identifier if (!is_string($collection)) { throw new InvalidParameterException("Invalid: Collection identifier '$collection' is not valid"); @@ -374,7 +374,7 @@ class PersonalService implements ServiceBaseInterface, ServiceCollectionMutableI throw new InvalidParameterException("Invalid: Collection identifier '$collection' does not exist or does not belong to user '{$this->serviceUserId}'"); } // convert entity to a native type if needed - if (!($entity instanceof Entity)) { + if (!($entity instanceof EntityResource)) { $nativeEntity = $this->entityFresh(); $nativeEntity->jsonDeserialize($entity->jsonSerialize()); } else { @@ -386,7 +386,7 @@ class PersonalService implements ServiceBaseInterface, ServiceCollectionMutableI return $result; } - public function entityUpdate(string|int $collection, string|int $identifier, EntityMutableInterface $entity): Entity { + public function entityUpdate(string|int $collection, string|int $identifier, EntityMutableInterface $entity): EntityResource { // validate collection identifier if (!is_string($collection)) { throw new InvalidParameterException("Invalid: Collection identifier '$collection' is not valid"); @@ -406,7 +406,7 @@ class PersonalService implements ServiceBaseInterface, ServiceCollectionMutableI } // convert entity to a native type if needed - if (!($entity instanceof Entity)) { + if (!($entity instanceof EntityResource)) { $nativeEntity = $this->entityFresh(); $nativeEntity->jsonDeserialize($entity->jsonSerialize()); } else { @@ -419,7 +419,7 @@ class PersonalService implements ServiceBaseInterface, ServiceCollectionMutableI return $result; } - public function entityDelete(string|int $collection, string|int $identifier): EntityMutableInterface { + public function entityDelete(string|int $collection, string|int $identifier): EntityResource { // validate collection identifier if (!is_string($collection)) { throw new InvalidParameterException("Invalid: Collection identifier '$collection' is not valid"); diff --git a/lib/Providers/Provider.php b/lib/Providers/Provider.php index 8ab761f..56109c0 100644 --- a/lib/Providers/Provider.php +++ b/lib/Providers/Provider.php @@ -14,9 +14,6 @@ use KTXF\Chrono\Provider\ProviderBaseInterface; use KTXF\Chrono\Service\ServiceBaseInterface; use KTXM\ProviderLocalChrono\Providers\Personal\PersonalService; -/** - * Local Storage Provider for Chrono - */ class Provider implements ProviderBaseInterface { @@ -55,7 +52,7 @@ class Provider implements ProviderBaseInterface public function type(): string { - return self::TYPE_MAIL; + return self::TYPE_CHRONO; } public function identifier(): string diff --git a/lib/Store/Personal/Store.php b/lib/Store/Personal/Store.php index 6ac41d9..c8bd872 100644 --- a/lib/Store/Personal/Store.php +++ b/lib/Store/Personal/Store.php @@ -17,15 +17,13 @@ use KTXF\Resource\Range\Range; use KTXF\Resource\Range\RangeType; use KTXF\Resource\Sort\Sort; use KTXF\Utile\UUID; -use KTXM\ProviderLocalChrono\Providers\Personal\Collection; -use KTXM\ProviderLocalChrono\Providers\Personal\Entity; +use KTXM\ProviderLocalChrono\Providers\Personal\CollectionResource; +use KTXM\ProviderLocalChrono\Providers\Personal\EntityResource; class Store { protected string $_CollectionTable = 'provider_local_chrono_collection'; - protected string $_CollectionClass = 'KTXM\ProviderLocalChrono\Providers\Personal\Collection'; protected string $_EntityTable = 'provider_local_chrono_entity'; - protected string $_EntityClass = 'KTXM\ProviderLocalChrono\Providers\Personal\Entity'; protected string $_ChronicleTable = 'provider_local_chrono_chronicle'; protected array $_CollectionFilterAttributeMap = [ @@ -145,7 +143,7 @@ class Store { $cursor = $this->_store->selectCollection($this->_CollectionTable)->find($query, $options); $list = []; foreach ($cursor as $entry) { - $entry = (new Collection())->fromStore($entry); + $entry = $this->collectionFresh()->fromStore($entry); $identifier = $entry->identifier(); if ($identifier !== null) { $list[(string) $identifier] = $entry; @@ -180,9 +178,9 @@ class Store { * @param string $userId user identifier * @param string $identifier collection identifier * - * @return Collection + * @return CollectionResource|null */ - public function collectionFetch(string $tenantId, string $userId, string $identifier): ?Collection { + public function collectionFetch(string $tenantId, string $userId, string $identifier): ?CollectionResource { $cursor = $this->_store->selectCollection($this->_CollectionTable)->findOne([ 'tid' => $tenantId, 'uid' => $userId, @@ -191,7 +189,7 @@ class Store { if ($cursor === null) { return null; } - $entry = (new Collection())->fromStore($cursor); + $entry = $this->collectionFresh()->fromStore($cursor); return $entry; } @@ -200,10 +198,10 @@ class Store { * * @since Release 1.0.0 * - * @return Collection + * @return CollectionResource */ - public function collectionFresh(): Collection { - return new $this->_CollectionClass; + public function collectionFresh(): CollectionResource { + return new CollectionResource(); } /** @@ -212,11 +210,11 @@ class Store { * @since Release 1.0.0 * * @param string $userId user identifier - * @param Collection $entity + * @param CollectionResource $entity * - * @return Collection + * @return CollectionResource */ - public function collectionCreate(string $tenantId, string $userId, Collection $entity): Collection { + public function collectionCreate(string $tenantId, string $userId, CollectionResource $entity): CollectionResource { // convert entity to store format $data = $entity->toStore(); // prepare data for creation @@ -229,8 +227,7 @@ class Store { // create entry $result = $this->_store->selectCollection($this->_CollectionTable)->insertOne($data); if ($result->getInsertedCount() === 1) { - $entity = new Collection(); - $entity->fromStore($data); + $entity = $this->collectionFresh()->fromStore($data); } return $entity; } @@ -241,11 +238,11 @@ class Store { * @since Release 1.0.0 * * @param string $userId user identifier - * @param Collection $entity + * @param CollectionResource $entity * - * @return Collection + * @return CollectionResource */ - public function collectionModify(string $tenantId, string $userId, Collection $entity): Collection { + public function collectionModify(string $tenantId, string $userId, CollectionResource $entity): CollectionResource { // convert entity to store format $data = $entity->toStore(); // prepare data for modification @@ -268,11 +265,11 @@ class Store { * * @since Release 1.0.0 * - * @param Collection $entity + * @param CollectionResource $entity * - * @return Collection + * @return CollectionResource */ - public function collectionDestroy(string $tenantId, string $userId, Collection $entity): Collection { + public function collectionDestroy(string $tenantId, string $userId, CollectionResource $entity): CollectionResource { $identifier = $entity->identifier(); if ($identifier === null) { return $entity; @@ -351,7 +348,7 @@ class Store { $cursor = $this->_store->selectCollection($this->_EntityTable)->find($query, $findOptions); $list = []; foreach ($cursor as $entry) { - $entity = (new Entity())->fromStore($entry); + $entity = $this->entityFresh()->fromStore($entry); $identifier = $entity->identifier(); if ($identifier !== null) { $list[(string) $identifier] = $entity; @@ -405,7 +402,7 @@ class Store { * @param string $collection collection identifier * @param string ...$identifiers entity identifiers (eid UUID strings) * - * @return array + * @return array */ public function entityFetch(string $tenantId, string $userId, string $collectionId, string ...$identifiers): array { // Query for entities using eid field @@ -418,7 +415,7 @@ class Store { $list = []; foreach ($cursor as $entry) { - $entity = (new Entity())->fromStore($entry); + $entity = $this->entityFresh()->fromStore($entry); $identifier = $entity->identifier(); if ($identifier !== null) { $list[(string) $identifier] = $entity; @@ -433,21 +430,12 @@ class Store { * * @since Release 1.0.0 * - * @return Entity + * @return EntityResource */ - public function entityFresh(): Entity { - return new Entity(); + public function entityFresh(): EntityResource { + return new EntityResource(); } - /** - * create a entity entry in the data store - * - * @since Release 1.0.0 - * - * @param Entity $entity entity to create - * - * @return Entity - */ /** * create a entity entry in the data store * @@ -455,11 +443,11 @@ class Store { * * @param string $userId user identifier * @param string $collection collection identifier - * @param Entity $entity entity to create + * @param EntityResource $entity entity to create * - * @return Entity + * @return EntityResource */ - public function entityCreate(string $tenantId, string $userId, string $collectionId, Entity $entity): Entity { + public function entityCreate(string $tenantId, string $userId, string $collectionId, EntityResource $entity): EntityResource { // convert entity to store format $data = $entity->toStore(); // assign identifiers and timestamps @@ -476,7 +464,7 @@ class Store { if ($result->getInsertedCount() === 1) { $eid = $data['eid']; - $entity->fromStore($data); + $entity = $this->entityFresh()->fromStore($data); // Chronicle the creation (operation 1) $this->chronicleDocument($tenantId, $collectionId, $eid, 1); } @@ -492,11 +480,11 @@ class Store { * @param string $userId user identifier * @param string $collection collection identifier * @param string $identifier entity identifier - * @param Entity $entity entity to modify + * @param EntityResource $entity entity to modify * - * @return Entity + * @return EntityResource */ - public function entityModify(string $tenantId, string $userId, string $collectionId, string $identifier, Entity $entity): Entity { + public function entityModify(string $tenantId, string $userId, string $collectionId, string $identifier, EntityResource $entity): EntityResource { // convert entity to store format $data = $entity->toStore(); $data['modifiedOn'] = date('c'); @@ -524,11 +512,11 @@ class Store { * * @param string $userId user identifier * @param string $collection collection identifier - * @param Entity $entity entity to delete + * @param EntityResource $entity entity to delete * - * @return Entity + * @return EntityResource */ - public function entityDestroy(string $tenantId, string $userId, string $collectionId, Entity $entity): Entity { + public function entityDestroy(string $tenantId, string $userId, string $collectionId, EntityResource $entity): EntityResource { $identifier = $entity->identifier(); if ($identifier === null) { return $entity;