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

refactor: standardize design

Browse Source 
Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
This commit is contained in:
Sebastian Krupinski
2026-02-25 15:34:19 -05:00
parent dce16eff59
commit 80434e5476
14 changed files with 622 additions and 1595 deletions
Download Patch File Download Diff File Expand all files Collapse all files

241
lib/Providers/Personal/PersonalService.php
View File

@@ -7,14 +7,16 @@ declare(strict_types=1);
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXM\PeopleProviderLocal\Providers\Personal;
namespace KTXM\ProviderLocalPeople\Providers\Personal;
use KTXF\People\Collection\ICollectionMutable;
use KTXF\People\Entity\IEntityBase;
use KTXF\People\Service\IServiceBase;
use KTXF\People\Entity\IEntityMutable;
use KTXF\People\Service\IServiceCollectionMutable;
use KTXF\People\Service\IServiceEntityMutable;
use KTXF\People\Collection\CollectionBaseInterface;
use KTXF\People\Collection\CollectionMutableInterface;
use KTXF\People\Entity\EntityMutableInterface;
use KTXF\People\Service\ServiceBaseInterface;
use KTXF\People\Service\ServiceCollectionMutableInterface;
use KTXF\People\Service\ServiceEntityMutableInterface;
use KTXF\Resource\Delta\Delta;
use KTXF\Resource\Delta\DeltaCollection;
use KTXF\Resource\Exceptions\InvalidParameterException;
use KTXF\Resource\Filter\Filter;
use KTXF\Resource\Filter\IFilter;
@@ -23,84 +25,84 @@ use KTXF\Resource\Range\RangeTally;
use KTXF\Resource\Range\RangeType;
use KTXF\Resource\Sort\ISort;
use KTXF\Resource\Sort\Sort;
use KTXM\PeopleProviderLocal\Store\Personal\Store;
use KTXM\ProviderLocalPeople\Store\Personal\Store;
class PersonalService implements IServiceBase, IServiceCollectionMutable, IServiceEntityMutable {
class PersonalService implements ServiceBaseInterface, ServiceCollectionMutableInterface, ServiceEntityMutableInterface {
protected const SERVICE_ID = 'personal';
protected const SERVICE_LABEL = 'Personal Contacts Service';
protected const SERVICE_PROVIDER = 'default';
public const JSON_TYPE = ServiceBaseInterface::JSON_TYPE;
private const PROVIDER_IDENTIFIER = 'default';
private const SERVICE_IDENTIFIER = 'personal';
private const SERVICE_LABEL = 'Personal Calendar Service';
protected array $serviceCollectionCache = [];
protected ?string $serviceTenantId = null;
protected ?string $serviceUserId = null;
protected ?bool $serviceEnabled = true;
protected array $serviceAbilities = [
private array $serviceAbilities = [
self::CAPABILITY_COLLECTION_LIST => true,
self::CAPABILITY_COLLECTION_LIST_FILTER => [
'id' => 'a:10:64:192',
'label' => 's:100:256:771',
'description' => 's:100:256:771',
self::CAPABILITY_COLLECTION_FILTER_LABEL => 's:100:256:256',
],
self::CAPABILITY_COLLECTION_LIST_SORT => [
'label',
'description'
self::CAPABILITY_COLLECTION_SORT_LABEL,
self::CAPABILITY_COLLECTION_SORT_RANK,
],
self::CAPABILITY_COLLECTION_EXTANT => true,
self::CAPABILITY_COLLECTION_FETCH => true,
self::CAPABILITY_COLLECTION_CREATE => true,
self::CAPABILITY_COLLECTION_MODIFY => true,
self::CAPABILITY_COLLECTION_DESTROY => true,
self::CAPABILITY_COLLECTION_CREATE => true,
self::CAPABILITY_COLLECTION_UPDATE => true,
self::CAPABILITY_COLLECTION_DELETE => true,
self::CAPABILITY_ENTITY_LIST => true,
self::CAPABILITY_ENTITY_LIST_FILTER => [
'*' => 's:200:256:771',
'uri' => 's:200:256:771',
'label' => 's:200:256:771',
'phone' => 's:200:256:771',
'email' => 's:200:256:771',
'location' => 's:200:256:771'
self::CAPABILITY_ENTITY_FILTER_ALL => 's:200:256:256',
self::CAPABILITY_ENTITY_FILTER_ID => 's:100:256:256',
self::CAPABILITY_ENTITY_FILTER_URID => 's:100:256:256',
self::CAPABILITY_ENTITY_FILTER_LABEL => 's:100:256:256',
],
self::CAPABILITY_ENTITY_LIST_SORT => [
'label',
'phone',
'email',
'location'
self::CAPABILITY_ENTITY_SORT_ID,
self::CAPABILITY_ENTITY_SORT_URID,
],
self::CAPABILITY_ENTITY_LIST_RANGE => [
'tally' => ['absolute', 'relative']
self::CAPABILITY_ENTITY_RANGE_TALLY => [
self::CAPABILITY_ENTITY_RANGE_TALLY_ABSOLUTE,
self::CAPABILITY_ENTITY_RANGE_TALLY_RELATIVE
],
],
self::CAPABILITY_ENTITY_DELTA => true,
self::CAPABILITY_ENTITY_EXTANT => true,
self::CAPABILITY_ENTITY_FETCH => true,
self::CAPABILITY_ENTITY_CREATE => true,
self::CAPABILITY_ENTITY_MODIFY => true,
self::CAPABILITY_ENTITY_DESTROY => true,
self::CAPABILITY_ENTITY_COPY => true,
self::CAPABILITY_ENTITY_MOVE => true,
self::CAPABILITY_ENTITY_UPDATE => true,
self::CAPABILITY_ENTITY_DELETE => true,
];
public function __construct(
private Store $store,
) {}
public function jsonSerialize(): mixed {
return [
self::JSON_PROPERTY_TYPE => self::JSON_TYPE,
self::JSON_PROPERTY_PROVIDER => self::SERVICE_PROVIDER,
self::JSON_PROPERTY_ID => self::SERVICE_ID,
self::JSON_PROPERTY_LABEL => self::SERVICE_LABEL,
self::JSON_PROPERTY_CAPABILITIES => $this->serviceAbilities,
self::JSON_PROPERTY_ENABLED => $this->serviceEnabled,
];
}
public function init(string $tenantId, string $userId): self {
public function initialize(string $tenantId, string $userId): self {
$this->serviceTenantId = $tenantId;
$this->serviceUserId = $userId;
return $this;
}
public function jsonSerialize(): array {
return array_filter([
self::JSON_PROPERTY_TYPE => self::JSON_TYPE,
self::JSON_PROPERTY_PROVIDER => self::PROVIDER_IDENTIFIER,
self::JSON_PROPERTY_IDENTIFIER => self::SERVICE_IDENTIFIER,
self::JSON_PROPERTY_LABEL => self::SERVICE_LABEL,
self::JSON_PROPERTY_ENABLED => $this->serviceEnabled,
self::JSON_PROPERTY_CAPABILITIES => $this->serviceAbilities,
self::JSON_PROPERTY_LOCATION => null,
self::JSON_PROPERTY_IDENTITY => null,
self::JSON_PROPERTY_AUXILIARY => [],
], fn($v) => $v !== null);
}
public function capable(string $value): bool {
if (isset($this->serviceAbilities[$value])) {
return (bool)$this->serviceAbilities[$value];
@@ -112,12 +114,13 @@ class PersonalService implements IServiceBase, IServiceCollectionMutable, IServi
return $this->serviceAbilities;
}
public function in(): string{
return self::SERVICE_PROVIDER;
}
public function provider(): string
{
return self::PROVIDER_IDENTIFIER;
}
public function id(): string {
return self::SERVICE_ID;
public function identifier(): string {
return self::SERVICE_IDENTIFIER;
}
public function getLabel(): string {
@@ -128,7 +131,30 @@ class PersonalService implements IServiceBase, IServiceCollectionMutable, IServi
return (bool)$this->serviceEnabled;
}
public function collectionList(?IFilter $filter = null, ?ISort $sort = null): array {
public function setEnabled(bool $enabled): static
{
$this->serviceEnabled = $enabled;
return $this;
}
public function getLocation(): null
{
return null;
}
public function getIdentity(): null
{
return null;
}
public function getAuxiliary(): array
{
return [];
}
// Collection operations
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 ?? [];
@@ -142,49 +168,70 @@ class PersonalService implements IServiceBase, IServiceCollectionMutable, IServi
return new Sort($this->serviceAbilities[self::CAPABILITY_COLLECTION_LIST_SORT] ?? []);
}
public function collectionExtant(string|int $id): bool {
// determine if collection is cached
if (isset($this->serviceCollectionCache[$id])) {
return true;
public function collectionExtant(string|int $location, string|int ...$identifiers): array {
$resolvedIdentifiers = $identifiers !== [] ? $identifiers : [$location];
$response = [];
foreach ($resolvedIdentifiers as $identifier) {
if (isset($this->serviceCollectionCache[$identifier])) {
$response[$identifier] = true;
continue;
}
$exists = $this->store->collectionExtant($this->serviceTenantId, $this->serviceUserId, (string)$identifier);
$response[$identifier] = $exists;
if ($exists) {
$collection = $this->store->collectionFetch($this->serviceTenantId, $this->serviceUserId, (string)$identifier);
if ($collection !== null) {
$this->serviceCollectionCache[$identifier] = $collection;
}
}
}
// retrieve from store
return $this->store->collectionExtant($this->serviceTenantId, $this->serviceUserId, $id);
return $response;
}
public function collectionFetch(string|int $id): ?Collection {
public function collectionFetch(string|int $identifier): ?CollectionBaseInterface {
// determine if collection is cached
if (isset($this->serviceCollectionCache[$id])) {
return $this->serviceCollectionCache[$id];
if (isset($this->serviceCollectionCache[$identifier])) {
return $this->serviceCollectionCache[$identifier];
}
// retrieve from store
$collection = $this->store->collectionFetch($this->serviceTenantId, $this->serviceUserId, $id);
$collection = $this->store->collectionFetch($this->serviceTenantId, $this->serviceUserId, (string)$identifier);
if ($collection !== null) {
$this->serviceCollectionCache[$collection->id()] = $collection;
$collectionIdentifier = $collection->identifier();
if ($collectionIdentifier !== null) {
$this->serviceCollectionCache[(string) $collectionIdentifier] = $collection;
}
return $collection;
}
return null;
}
public function collectionFresh(): Collection {
return new Collection();
public function collectionFresh(): CollectionResource {
return new CollectionResource();
}
public function collectionCreate(string|int $location, ICollectionMutable $collection, array $options): Collection {
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;
}
// create collection in store
$result = $this->store->collectionCreate($this->serviceTenantId, $this->serviceUserId, $nativeCollection);
$this->serviceCollectionCache[$result->id()] = $result;
$resultIdentifier = $result->identifier();
if ($resultIdentifier !== null) {
$this->serviceCollectionCache[(string) $resultIdentifier] = $result;
}
return $result;
}
public function collectionModify(string|int $id, ICollectionMutable $collection): Collection {
public function collectionUpdate(string|int $id, CollectionMutableInterface $collection): CollectionBaseInterface {
// validate id
if (!is_string($id)) {
throw new InvalidParameterException("Invalid: Collection identifier '$id' is not valid");
@@ -194,18 +241,25 @@ class PersonalService implements IServiceBase, IServiceCollectionMutable, IServi
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();
$nativeCollection->jsonDeserialize($collection->jsonSerialize());
if (!($collection instanceof CollectionResource)) {
$nativeCollection = new CollectionResource();
$data = $collection->jsonSerialize();
$data[CollectionResource::JSON_PROPERTY_IDENTIFIER] = $id;
$nativeCollection->jsonDeserialize($data);
} else {
$nativeCollection = clone $collection;
if ($nativeCollection->identifier() === null) {
$data = $nativeCollection->jsonSerialize();
$data[CollectionResource::JSON_PROPERTY_IDENTIFIER] = $id;
$nativeCollection->jsonDeserialize($data);
}
}
// modify collection in store
$result = $this->store->collectionModify($this->serviceTenantId, $this->serviceUserId, $nativeCollection);
return $result;
}
public function collectionDestroy(string|int $id): bool {
public function collectionDelete(string|int $id, bool $force = false, bool $recursive = false): bool {
// validate id
if (!is_string($id)) {
throw new InvalidParameterException("Invalid: Collection identifier '$id' is not valid");
@@ -222,6 +276,8 @@ class PersonalService implements IServiceBase, IServiceCollectionMutable, IServi
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)) {
@@ -236,7 +292,6 @@ class PersonalService implements IServiceBase, IServiceCollectionMutable, IServi
return $entries ?? [];
}
public function entityListFilter(): Filter {
return new Filter($this->serviceAbilities[self::CAPABILITY_ENTITY_LIST_FILTER] ?? []);
}
@@ -247,10 +302,13 @@ class PersonalService implements IServiceBase, IServiceCollectionMutable, IServi
public function entityListRange(RangeType $type): IRange {
// validate type
if ($type !== RangeType::TALLY) {
throw new InvalidParameterException("Invalid: Entity range of type '{$type->value}' is not valid");
if ($type === RangeType::TALLY) {
return new RangeTally();
}
return new RangeTally();
if ($type === RangeType::DATE) {
return new RangeDate();
}
throw new InvalidParameterException("Invalid: Entity range of type '{$type->value}' is not valid");
}
public function entityExtant(string|int $collection, string|int ...$identifiers): array {
@@ -266,7 +324,7 @@ class PersonalService implements IServiceBase, IServiceCollectionMutable, IServi
return $this->store->entityExtant($collection, ...$identifiers);
}
public function entityDelta(string|int $collection, string $signature, string $detail = 'ids'): array {
public function entityDelta(string|int $collection, string $signature, string $detail = 'ids'): Delta {
// validate id
if (!is_string($collection)) {
throw new InvalidParameterException("Invalid: Collection identifier '$collection' is not valid");
@@ -276,7 +334,14 @@ class PersonalService implements IServiceBase, IServiceCollectionMutable, IServi
throw new InvalidParameterException("Invalid: Collection identifier '$collection' does not exist or does not belong to user '{$this->serviceUserId}'");
}
// retrieve entity delta from store
return $this->store->chronicleReminisce($this->serviceTenantId, $this->serviceUserId,$collection, $signature);
$delta = $this->store->chronicleReminisce($this->serviceTenantId, $collection, $signature);
return new Delta(
new DeltaCollection($delta['additions'] ?? []),
new DeltaCollection($delta['modifications'] ?? []),
new DeltaCollection($delta['deletions'] ?? []),
$delta['signature'] ?? ''
);
}
public function entityFetch(string|int $collection, string|int ...$identifiers): array {
@@ -293,11 +358,11 @@ class PersonalService implements IServiceBase, IServiceCollectionMutable, IServi
return $entries ?? [];
}
public function entityFresh(): Entity {
return new Entity();
public function entityFresh(): EntityResource {
return new EntityResource();
}
public function entityCreate(string|int $collection, IEntityMutable $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");
@@ -307,7 +372,7 @@ class PersonalService implements IServiceBase, IServiceCollectionMutable, IServi
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 {
@@ -319,7 +384,7 @@ class PersonalService implements IServiceBase, IServiceCollectionMutable, IServi
return $result;
}
public function entityModify(string|int $collection, string|int $identifier, IEntityMutable $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");
@@ -352,7 +417,7 @@ class PersonalService implements IServiceBase, IServiceCollectionMutable, IServi
return $result;
}
public function entityDestroy(string|int $collection, string|int $identifier): IEntityBase {
public function entityDelete(string|int $collection, string|int $identifier): EntityMutableInterface {
// validate collection identifier
if (!is_string($collection)) {
throw new InvalidParameterException("Invalid: Collection identifier '$collection' is not valid");