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

refactor: people provider
All checks were successful
JS Unit Tests / test (pull_request) Successful in 16s
Details
Build Test / build (pull_request) Successful in 18s
Details
PHP Unit Tests / test (pull_request) Successful in 56s
Details

Browse Source 
Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
This commit is contained in:
Sebastian Krupinski
2026-02-25 00:13:51 -05:00
parent 7799787ffb
commit e48ee82530
41 changed files with 1091 additions and 984 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
shared/lib/Chrono/Collection/CollectionBaseInterface.php
View File

@@ -12,9 +12,9 @@ namespace KTXF\Chrono\Collection;
use KTXF\Resource\Provider\Node\NodeBaseInterface;
/**
* Chrono Collection Base Interface
* Collection Base Interface
*
* Interface represents a collection in a chrono service
* Interface represents a collection in a service
*
* @since 2025.05.01
*/

31
shared/lib/People/Collection/CollectionBaseAbstract.php Normal file
View File

@@ -0,0 +1,31 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Collection;
use KTXF\Resource\Provider\Node\NodeBaseAbstract;
/**
* Abstract Collection Base Class
*
* Provides common implementation for collections
*
* @since 2025.05.01
*/
abstract class CollectionBase extends NodeBaseAbstract implements CollectionBaseInterface {
protected CollectionPropertiesBaseAbstract $properties;
/**
* @inheritDoc
*/
public function getProperties(): CollectionPropertiesBaseInterface {
return $this->properties;
}
}

30
shared/lib/People/Collection/CollectionBaseInterface.php Normal file
View File

@@ -0,0 +1,30 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Collection;
use KTXF\Resource\Provider\Node\NodeBaseInterface;
/**
* Collection Base Interface
*
* Interface represents a collection in a service
*
* @since 2025.05.01
*/
interface CollectionBaseInterface extends NodeBaseInterface {
/**
* Gets the collection properties
*
* @since 2025.05.01
*/
public function getProperties(): CollectionPropertiesBaseInterface|CollectionPropertiesMutableInterface;
}

50
shared/lib/People/Collection/CollectionMutableAbstract.php Normal file
View File

@@ -0,0 +1,50 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Collection;
use KTXF\Resource\Provider\Node\NodeMutableAbstract;
use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
/**
* Abstract Collection Mutable Class
*
* Provides common implementation for mutable collections
*
* @since 2025.05.01
*/
abstract class CollectionMutableAbstract extends NodeMutableAbstract implements CollectionMutableInterface {
protected CollectionPropertiesMutableAbstract $properties;
/**
* @inheritDoc
*/
public function getProperties(): CollectionPropertiesMutableInterface {
return $this->properties;
}
/**
* @inheritDoc
*/
public function setProperties(NodePropertiesMutableInterface $value): static {
if (!$value instanceof CollectionPropertiesMutableInterface) {
throw new \InvalidArgumentException('Properties must implement CollectionPropertiesMutableInterface');
}
// Copy all property values
$this->properties->setLabel($value->getLabel());
$this->properties->setDescription($value->getDescription());
$this->properties->setPriority($value->getPriority());
$this->properties->setVisibility($value->getVisibility());
$this->properties->setColor($value->getColor());
return $this;
}
}

32
shared/lib/People/Collection/CollectionMutableInterface.php Normal file
View File

@@ -0,0 +1,32 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Collection;
use KTXF\Resource\Provider\Node\NodeMutableInterface;
/**
* Collection Mutable Interface
*
* Interface for altering collection properties in a service
*
* @since 2025.05.01
*
* @method static setProperties(CollectionPropertiesMutableInterface $value)
*/
interface CollectionMutableInterface extends CollectionBaseInterface, NodeMutableInterface {
/**
* Gets the collection properties (mutable)
*
* @since 2025.05.01
*/
public function getProperties(): CollectionPropertiesMutableInterface;
}

26
shared/lib/People/Collection/CollectionPermissions.php
View File

@@ -1,26 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Collection;
use JsonSerializable;
enum CollectionPermissions: string implements JsonSerializable {
case View = 'view';
case Create = 'create';
case Modify = 'modify';
case Destroy = 'destroy';
case Share = 'share';
public function jsonSerialize(): string {
return $this->value;
}
}

74
shared/lib/People/Collection/CollectionPropertiesBaseAbstract.php Normal file
View File

@@ -0,0 +1,74 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Collection;
use KTXF\Resource\Provider\Node\NodePropertiesBaseAbstract;
/**
* Abstract Collection Properties Base Class
*
* Provides common implementation for collection properties
*
* @since 2025.05.01
*/
abstract class CollectionPropertiesBaseAbstract extends NodePropertiesBaseAbstract implements CollectionPropertiesBaseInterface {
public const JSON_TYPE = CollectionPropertiesBaseInterface::JSON_TYPE;
/**
* @inheritDoc
*/
public function content(): array {
$content = $this->data[self::JSON_PROPERTY_CONTENT] ?? null;
if (is_array($content)) {
return array_map(function ($item) {
return new CollectionContent($item);
}, $content);
} else {
return [];
}
}
/**
* @inheritDoc
*/
public function getLabel(): string {
return $this->data[self::JSON_PROPERTY_LABEL] ?? '';
}
/**
* @inheritDoc
*/
public function getDescription(): ?string {
return $this->data[self::JSON_PROPERTY_DESCRIPTION] ?? null;
}
/**
* @inheritDoc
*/
public function getPriority(): ?int {
return $this->data[self::JSON_PROPERTY_PRIORITY] ?? null;
}
/**
* @inheritDoc
*/
public function getVisibility(): ?bool {
return $this->data[self::JSON_PROPERTY_VISIBILITY] ?? null;
}
/**
* @inheritDoc
*/
public function getColor(): ?string {
return $this->data[self::JSON_PROPERTY_COLOR] ?? null;
}
}

70
shared/lib/People/Collection/CollectionPropertiesBaseInterface.php Normal file
View File

@@ -0,0 +1,70 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Collection;
use KTXF\Resource\Provider\Node\NodePropertiesBaseInterface;
use PhpParser\Node\Expr\Array_;
interface CollectionPropertiesBaseInterface extends NodePropertiesBaseInterface {
public const JSON_TYPE = 'people:collection';
public const JSON_PROPERTY_CONTENT = 'content';
public const JSON_PROPERTY_LABEL = 'label';
public const JSON_PROPERTY_DESCRIPTION = 'description';
public const JSON_PROPERTY_PRIORITY = 'priority';
public const JSON_PROPERTY_VISIBILITY = 'visibility';
public const JSON_PROPERTY_COLOR = 'color';
/**
* 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)
*
* @since 2025.05.01
*/
public function getLabel(): string;
/**
* Gets the human friendly description of this collection
*
* @since 2025.05.01
*/
public function getDescription(): ?string;
/**
* Gets the priority of this collection
*
* @since 2025.05.01
*/
public function getPriority(): ?int;
/**
* Gets the visibility of this collection
*
* @since 2025.05.01
*/
public function getVisibility(): ?bool;
/**
* Gets the color of this collection
*
* @since 2025.05.01
*/
public function getColor(): ?string;
}

72
shared/lib/People/Collection/CollectionPropertiesMutableAbstract.php Normal file
View File

@@ -0,0 +1,72 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Collection;
/**
* Abstract Collection Properties Mutable Class
*/
abstract class CollectionPropertiesMutableAbstract extends CollectionPropertiesBaseAbstract implements CollectionPropertiesMutableInterface {
public const JSON_TYPE = CollectionPropertiesBaseInterface::JSON_TYPE;
/**
* @inheritDoc
*/
public function jsonDeserialize(array|string $data): static {
if (is_string($data)) {
$data = json_decode($data, true);
}
$this->data = $data;
return $this;
}
/**
* @inheritDoc
*/
public function setLabel(string $value): static {
$this->data[self::JSON_PROPERTY_LABEL] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setDescription(?string $value): static {
$this->data[self::JSON_PROPERTY_DESCRIPTION] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setPriority(?int $value): static {
$this->data[self::JSON_PROPERTY_PRIORITY] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setVisibility(?bool $value): static {
$this->data[self::JSON_PROPERTY_VISIBILITY] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setColor(?string $value): static {
$this->data[self::JSON_PROPERTY_COLOR] = $value;
return $this;
}
}

25
shared/lib/People/Collection/ICollectionMutable.php → shared/lib/People/Collection/CollectionPropertiesMutableInterface.php
View File

@@ -9,50 +9,45 @@ declare(strict_types=1);
namespace KTXF\People\Collection;
use KTXF\Json\JsonDeserializable;
use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
interface ICollectionMutable extends ICollectionBase, JsonDeserializable {
interface CollectionPropertiesMutableInterface extends NodePropertiesMutableInterface {
public const JSON_TYPE = CollectionPropertiesBaseInterface::JSON_TYPE;
/**
* Sets the active status of this collection
* Sets the human friendly name of this collection (e.g. Personal Calendar)
*
* @since 2025.05.01
*/
public function setEnabled(bool $value): self;
/**
* Sets the human friendly name of this collection (e.g. Personal Contacts)
*
* @since 2025.05.01
*/
public function setLabel(string $value): self;
public function setLabel(string $value): static;
/**
* Sets the human friendly description of this collection
*
* @since 2025.05.01
*/
public function setDescription(?string $value): self;
public function setDescription(?string $value): static;
/**
* Sets the priority of this collection
*
* @since 2025.05.01
*/
public function setPriority(?int $value): self;
public function setPriority(?int $value): static;
/**
* Sets the visibility of this collection
*
* @since 2025.05.01
*/
public function setVisibility(?bool $value): self;
public function setVisibility(?bool $value): static;
/**
* Sets the color of this collection
*
* @since 2025.05.01
*/
public function setColor(?string $value): self;
public function setColor(?string $value): static;
}

24
shared/lib/People/Collection/CollectionRoles.php
View File

@@ -1,24 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Collection;
use JsonSerializable;
enum CollectionRoles: string implements JsonSerializable {
case System = 'system';
case Individual = 'individual';
case Recent = 'recent';
public function jsonSerialize(): string {
return $this->value;
}
}

160
shared/lib/People/Collection/ICollectionBase.php
View File

@@ -1,160 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Collection;
use DateTimeImmutable;
use JsonSerializable;
interface ICollectionBase extends JsonSerializable {
public const JSON_TYPE = 'people.collection';
public const JSON_PROPERTY_TYPE = '@type';
public const JSON_PROPERTY_PROVIDER = 'provider';
public const JSON_PROPERTY_SERVICE = 'service';
public const JSON_PROPERTY_IN = 'in';
public const JSON_PROPERTY_ID = 'id';
public const JSON_PROPERTY_LABEL = 'label';
public const JSON_PROPERTY_DESCRIPTION = 'description';
public const JSON_PROPERTY_PRIORITY = 'priority';
public const JSON_PROPERTY_VISIBILITY = 'visibility';
public const JSON_PROPERTY_COLOR = 'color';
public const JSON_PROPERTY_CREATED = 'created';
public const JSON_PROPERTY_MODIFIED = 'modified';
public const JSON_PROPERTY_ENABLED = 'enabled';
public const JSON_PROPERTY_SIGNATURE = 'signature';
public const JSON_PROPERTY_PERMISSIONS = 'permissions';
public const JSON_PROPERTY_ROLES = 'roles';
public const JSON_PROPERTY_CONTENTS = 'contents';
/**
* Unique identifier of the service this collection belongs to
*
* @since 2025.05.01
*/
public function in(): string|int|null;
/**
* Unique arbitrary text string identifying this service (e.g. 1 or collection1 or anything else)
*
* @since 2025.05.01
*/
public function id(): string|int;
/**
* Gets the creation date of this collection
*/
public function created(): ?DateTimeImmutable;
/**
* Gets the modification date of this collection
*/
public function modified(): ?DateTimeImmutable;
/**
* Lists all supported attributes
*
* @since 2025.05.01
*
* @return array<string,array<string,bool>>
*/
public function attributes(): array;
/**
* Gets the signature of this collection
*
* @since 2025.05.01
*/
public function signature(): ?string;
/**
* Gets the role(s) of this collection
*
* @since 2025.05.01
*/
public function roles(): array;
/**
* Checks if this collection supports the given role
*
* @since 2025.05.01
*/
public function role(CollectionRoles $value): bool;
/**
* Gets the content types of this collection
*
* @since 2025.05.01
*/
public function contents(): array;
/**
* Checks if this collection contains the given content type
*
* @since 2025.05.01
*/
public function contains(CollectionContent $value): bool;
/**
* Gets the active status of this collection
*
* @since 2025.05.01
*/
public function getEnabled(): bool;
/**
* Gets the active status of this collection
*
* @since 2025.05.01
*/
public function getPermissions(): array;
/**
* Checks if this collection has the given permission
*
* @since 2025.05.01
*/
public function hasPermission(CollectionPermissions $permission): bool;
/**
* Gets the human friendly name of this collection (e.g. Personal Contacts)
*
* @since 2025.05.01
*/
public function getLabel(): ?string;
/**
* Gets the human friendly description of this collection
*
* @since 2025.05.01
*/
public function getDescription(): ?string;
/**
* Gets the priority of this collection
*
* @since 2025.05.01
*/
public function getPriority(): ?int;
/**
* Gets the visibility of this collection
*
* @since 2025.05.01
*/
public function getVisibility(): ?bool;
/**
* Gets the color of this collection
*
* @since 2025.05.01
*/
public function getColor(): ?string;
}

31
shared/lib/People/Entity/EntityBaseAbstract.php Normal file
View File

@@ -0,0 +1,31 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Entity;
use KTXF\Resource\Provider\Node\NodeBaseAbstract;
/**
* Abstract Entity Base Class
*
* Provides common implementation for entities
*
* @since 2025.05.01
*/
abstract class EntityBaseAbstract extends NodeBaseAbstract implements EntityBaseInterface {
protected EntityPropertiesBaseAbstract $properties;
/**
* @inheritDoc
*/
public function getProperties(): EntityPropertiesBaseInterface {
return $this->properties;
}
}

25
shared/lib/People/Entity/EntityBaseInterface.php Normal file
View File

@@ -0,0 +1,25 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Entity;
use KTXF\Resource\Provider\Node\NodeBaseInterface;
interface EntityBaseInterface extends NodeBaseInterface {
public const JSON_TYPE = 'people:entity';
/**
* Gets the entity properties
*
* @since 2025.05.01
*/
public function getProperties(): EntityPropertiesBaseInterface|EntityPropertiesMutableInterface;
}

47
shared/lib/People/Entity/EntityMutableAbstract.php Normal file
View File

@@ -0,0 +1,47 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Entity;
use KTXF\Resource\Provider\Node\NodeMutableAbstract;
use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
/**
* Abstract Entity Mutable Class
*
* Provides common implementation for mutable entities
*
* @since 2025.05.01
*/
abstract class EntityMutableAbstract extends NodeMutableAbstract implements EntityMutableInterface {
public const JSON_TYPE = EntityMutableInterface::JSON_TYPE;
protected EntityPropertiesMutableAbstract $properties;
/**
* @inheritDoc
*/
public function getProperties(): EntityPropertiesMutableInterface {
return $this->properties;
}
/**
* @inheritDoc
*/
public function setProperties(NodePropertiesMutableInterface $value): static {
if (!$value instanceof EntityPropertiesMutableInterface) {
throw new \InvalidArgumentException('Properties must implement EntityPropertiesMutableInterface');
}
$this->properties->setDataRaw($value->getDataRaw());
return $this;
}
}

28
shared/lib/People/Entity/EntityMutableInterface.php Normal file
View File

@@ -0,0 +1,28 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Entity;
use KTXF\Resource\Provider\Node\NodeMutableInterface;
/**
* @method static setProperties(EntityPropertiesMutableInterface $value)
*/
interface EntityMutableInterface extends EntityBaseInterface, NodeMutableInterface {
public const JSON_TYPE = EntityBaseInterface::JSON_TYPE;
/**
* Gets the entity properties (mutable)
*
* @since 2025.05.01
*/
public function getProperties(): EntityPropertiesMutableInterface;
}

25
shared/lib/People/Entity/EntityPermissions.php
View File

@@ -1,25 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Entity;
use JsonSerializable;
enum EntityPermissions: string implements JsonSerializable {
case View = 'view';
case Modify = 'modify';
case Delete = 'delete';
case Share = 'share';
public function jsonSerialize(): string {
return $this->value;
}
}

21
shared/lib/People/Entity/EntityPropertiesBaseAbstract.php Normal file
View File

@@ -0,0 +1,21 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Entity;
use KTXF\Resource\Provider\Node\NodePropertiesBaseAbstract;
abstract class EntityPropertiesBaseAbstract extends NodePropertiesBaseAbstract implements EntityPropertiesBaseInterface {
public const JSON_TYPE = EntityPropertiesBaseInterface::JSON_TYPE;
public function getDataRaw(): array|string|null {
return $this->data[self::JSON_PROPERTY_DATA] ?? null;
}
}

21
shared/lib/People/Entity/EntityPropertiesBaseInterface.php Normal file
View File

@@ -0,0 +1,21 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Entity;
use KTXF\Resource\Provider\Node\NodePropertiesBaseInterface;
interface EntityPropertiesBaseInterface extends NodePropertiesBaseInterface {
public const JSON_TYPE = 'people:entity';
public const JSON_PROPERTY_DATA = 'data';
public function getDataRaw(): array|string|null;
}

30
shared/lib/People/Entity/EntityPropertiesMutableAbstract.php Normal file
View File

@@ -0,0 +1,30 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Entity;
abstract class EntityPropertiesMutableAbstract extends EntityPropertiesBaseAbstract implements EntityPropertiesMutableInterface {
public const JSON_TYPE = EntityPropertiesBaseInterface::JSON_TYPE;
public function jsonDeserialize(array|string $data): static {
if (is_string($data)) {
$data = json_decode($data, true);
}
$this->data = $data;
return $this;
}
public function setDataRaw(array|string|null $value): static {
$this->data[self::JSON_PROPERTY_DATA] = $value;
return $this;
}
}

20
shared/lib/People/Entity/EntityPropertiesMutableInterface.php Normal file
View File

@@ -0,0 +1,20 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Entity;
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;
}

94
shared/lib/People/Entity/IEntityBase.php
View File

@@ -1,94 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Entity;
use DateTimeImmutable;
use KTXF\People\Entity\Individual\IndividualObject;
interface IEntityBase extends \JsonSerializable {
public const JSON_TYPE = 'people.entity';
public const JSON_PROPERTY_TYPE = '@type';
public const JSON_PROPERTY_IN = 'in';
public const JSON_PROPERTY_ID = 'id';
public const JSON_PROPERTY_DATA = 'data';
public const JSON_PROPERTY_CREATED = 'created';
public const JSON_PROPERTY_MODIFIED = 'modified';
public const JSON_PROPERTY_SIGNATURE = 'signature';
/**
* Unique arbitrary text string identifying the collection this entity belongs to (e.g. 1 or Collection1 or anything else)
*
* @since 2025.05.01
*/
public function in(): string|int;
/**
* Unique arbitrary text string identifying this service (e.g. 1 or Entity or anything else)
*
* @since 2025.05.01
*/
public function id(): string|int;
/**
* Gets the creation date of this entity
*/
public function created(): ?DateTimeImmutable;
/**
* Gets the modification date of this entity
*/
public function modified(): ?DateTimeImmutable;
/**
* Gets the signature of this entity
*
* @since 2025.05.01
*/
public function signature(): ?string;
/**
* Gets the priority of this entity
*
* @since 2025.05.01
*/
public function getPriority(): ?int;
/**
* Gets the visibility of this entity
*
* @since 2025.05.01
*/
public function getVisibility(): ?bool;
/**
* Gets the color of this entity
*
* @since 2025.05.01
*/
public function getColor(): ?string;
/**
* Gets the object as a class instance.
*
* @since 2025.05.01
*/
public function getDataObject(): IndividualObject|null;
/**
* Gets the raw data as an associative array or JSON string.
*
* @since 2025.05.01
*
* @return array|string|null
*/
public function getDataJson(): array|string|null;
}

52
shared/lib/People/Entity/IEntityMutable.php
View File

@@ -1,52 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Entity;
use KTXF\Json\JsonDeserializable;
use KTXF\People\Entity\Individual\IndividualObject;
interface IEntityMutable extends IEntityBase, JsonDeserializable {
/**
* Sets the priority of this entity
*
* @since 2025.05.01
*/
public function setPriority(?int $value): static;
/**
* Sets the visibility of this entity
*
* @since 2025.05.01
*/
public function setVisibility(?bool $value): static;
/**
* Sets the color of this entity
*
* @since 2025.05.01
*/
public function setColor(?string $value): static;
/**
* Sets the object as a class instance.
*
* @since 2025.05.01
*/
public function setDataObject(IndividualObject $value): static;
/**
* Sets the object data from a json string
*
* @since 2025.05.01
*/
public function setDataJson(array|string $value): static;
}

96
shared/lib/People/Provider/IProviderBase.php
View File

@@ -1,96 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Provider;
use JsonSerializable;
use KTXF\People\Service\IServiceBase;
interface IProviderBase extends JsonSerializable {
public const CAPABILITY_SERVICE_LIST = 'ServiceList';
public const CAPABILITY_SERVICE_FETCH = 'ServiceFetch';
public const CAPABILITY_SERVICE_EXTANT = 'ServiceExtant';
public const JSON_TYPE = 'people.provider';
public const JSON_PROPERTY_TYPE = '@type';
public const JSON_PROPERTY_ID = 'id';
public const JSON_PROPERTY_LABEL = 'label';
public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
/**
* Confirms if specific capability is supported (e.g. 'ServiceList')
*
* @since 2025.05.01
*/
public function capable(string $value): bool;
/**
* Lists all supported capabilities
*
* @since 2025.05.01
*
* @return array<string,bool>
*/
public function capabilities(): array;
/**
* An arbitrary unique text string identifying this provider (e.g. UUID or 'system' or anything else)
*
* @since 2025.05.01
*/
public function id(): string;
/**
* The localized human friendly name of this provider (e.g. System Contacts Provider)
*
* @since 2025.05.01
*/
public function label(): string;
/**
* Retrieve collection of services for a specific user
*
* @since 2025.05.01
*
* @param string $tenantId tenant identifier
* @param string $userId user identifier
* @param array $filter filter criteria
*
* @return array<string,IServiceBase> collection of service objects
*/
public function serviceList(string $tenantId, string $userId, array $filter): array;
/**
* Determine if any services are configured for a specific user
*
* @since 2025.05.01
*
* @param string $tenantId tenant identifier
* @param string $userId user identifier
* @param int|string ...$identifiers variadic collection of service identifiers
*
* @return array<string,bool> collection of service identifiers with boolean values indicating if the service is available
*/
public function serviceExtant(string $tenantId, string $userId, int|string ...$identifiers): array;
/**
* Retrieve a service with a specific identifier
*
* @since 2025.05.01
*
* @param string $tenantId tenant identifier
* @param string $userId user identifier
* @param string|int $identifier service identifier
*
* @return IServiceBase|null returns service object or null if non found
*/
public function serviceFetch(string $tenantId, string $userId, string|int $identifier): ?IServiceBase;
}

69
shared/lib/People/Provider/IProviderServiceMutate.php
View File

@@ -1,69 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Provider;
use KTXF\Json\JsonDeserializable;
use KTXF\People\Service\IServiceBase;
interface IProviderServiceMutate extends JsonDeserializable {
public const CAPABILITY_SERVICE_FRESH = 'ServiceFresh';
public const CAPABILITY_SERVICE_CREATE = 'ServiceCreate';
public const CAPABILITY_SERVICE_UPDATE = 'ServiceUpdate';
public const CAPABILITY_SERVICE_DESTROY = 'ServiceDestroy';
/**
* construct and new blank service instance
*
* @since 2025.05.01
*
* @param string $userId user identifier
*
* @return IServiceBase
*/
public function serviceFresh(string $userId = ''): IServiceBase;
/**
* create a service configuration for a specific user
*
* @since 2025.05.01
*
* @param string $userId user identifier
* @param IServiceBase $service service instance
*
* @return string
*/
public function serviceCreate(string $userId, IServiceBase $service): string;
/**
* modify a service configuration for a specific user
*
* @since 2025.05.01
*
* @param string $userId user identifier
* @param IServiceBase $service service instance
*
* @return string
*/
public function serviceModify(string $userId, IServiceBase $service): string;
/**
* delete a service configuration for a specific user
*
* @since 2025.05.01
*
* @param string $userId user identifier
* @param IServiceBase $service service instance
*
* @return bool
*/
public function serviceDestroy(string $userId, IServiceBase $service): bool;
}

23
shared/lib/People/Provider/ProviderBaseInterface.php Normal file
View File

@@ -0,0 +1,23 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Provider;
use KTXF\Resource\Provider\ResourceProviderBaseInterface;
/**
* Provider Base Interface
*
* @since 2025.05.01
*/
interface ProviderBaseInterface extends ResourceProviderBaseInterface{
public const JSON_TYPE = 'people:provider';
}

28
shared/lib/People/Provider/ProviderServiceMutateInterface.php Normal file
View File

@@ -0,0 +1,28 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Provider;
use KTXF\Resource\Provider\ResourceProviderServiceMutateInterface;
/**
* Provider Service Mutate Interface
*
* Optional interface for providers that support service CRUD operations.
*
* @since 2025.05.01
*
* @method ServiceMutableInterface serviceFresh() Construct a new blank chrono service instance
* @method string serviceCreate(string $tenantId, ?string $userId, ServiceMutableInterface $service) Create a chrono service configuration
* @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 ResourceProviderServiceMutateInterface {
}

45
shared/lib/People/Provider/ProviderServiceTestInterface.php Normal file
View File

@@ -0,0 +1,45 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Provider;
use KTXF\Mail\Service\ServiceBaseInterface;
/**
* Provider Service Test Interface
*
* Optional interface for providers that support testing service connections
*
* @since 2025.05.01
*/
interface ProviderServiceTestInterface {
/**
* Test a service connection
*
* 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 array $options Provider-specific test options:
* - 'timeout' => int (seconds, default: 10)
* - 'verify_ssl' => bool (default: true)
* - 'test_send' => bool (attempt test send if capable, default: false)
* - 'test_receive' => bool (attempt mailbox access if capable, default: true)
*
* @return array Test results in the format:
* [
* 'success' => bool,
* 'message' => 'Connection successful' | 'Error message'
* ]
*/
public function serviceTest(ServiceBaseInterface $service, array $options = []): array;
}

221
shared/lib/People/Service/IServiceBase.php
View File

@@ -1,221 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Service;
use JsonSerializable;
use KTXF\People\Collection\ICollectionBase;
use KTXF\Resource\Filter\IFilter;
use KTXF\Resource\Range\IRange;
use KTXF\Resource\Range\RangeType;
use KTXF\Resource\Sort\ISort;
interface IServiceBase extends JsonSerializable {
public const CAPABILITY_COLLECTION_LIST = 'CollectionList';
public const CAPABILITY_COLLECTION_LIST_FILTER = 'CollectionListFilter';
public const CAPABILITY_COLLECTION_LIST_SORT = 'CollectionListSort';
public const CAPABILITY_COLLECTION_EXTANT = 'CollectionExtant';
public const CAPABILITY_COLLECTION_FETCH = 'CollectionFetch';
public const CAPABILITY_ENTITY_LIST = 'EntityList';
public const CAPABILITY_ENTITY_LIST_FILTER = 'EntityListFilter';
public const CAPABILITY_ENTITY_LIST_SORT = 'EntityListSort';
public const CAPABILITY_ENTITY_LIST_RANGE = 'EntityListRange';
public const CAPABILITY_ENTITY_DELTA = 'EntityDelta';
public const CAPABILITY_ENTITY_EXTANT = 'EntityExtant';
public const CAPABILITY_ENTITY_FETCH = 'EntityFetch';
public const JSON_TYPE = 'people.service';
public const JSON_PROPERTY_TYPE = '@type';
public const JSON_PROPERTY_PROVIDER = 'provider';
public const JSON_PROPERTY_ID = 'id';
public const JSON_PROPERTY_LABEL = 'label';
public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
public const JSON_PROPERTY_ENABLED = 'enabled';
/**
* Confirms if specific capability is supported
*
* @since 2025.05.01
*
* @param string $value required ability e.g. 'EntityList'
*
* @return bool
*/
public function capable(string $value): bool;
/**
* Lists all supported capabilities
*
* @since 2025.05.01
*
* @return array<string,bool>
*/
public function capabilities(): array;
/**
* Unique identifier of the provider this service belongs to
*
* @since 2025.05.01
*/
public function in(): string;
/**
* Unique arbitrary text string identifying this service (e.g. 1 or service1 or anything else)
*
* @since 2025.05.01
*/
public function id(): string|int;
/**
* Gets the localized human friendly name of this service (e.g. ACME Company Mail Service)
*
* @since 2025.05.01
*/
public function getLabel(): string;
/**
* Gets the active status of this service
*
* @since 2025.05.01
*/
public function getEnabled(): bool;
/**
* List of accessible collection
*
* @since 2025.05.01
*
* @return array<string|int,ICollectionBase>
*/
public function collectionList(?IFilter $filter = null, ?ISort $sort = null): array;
/**
* Fresh filter for collection list
*
* @since 2025.05.01
*
* @return IFilter
*/
public function collectionListFilter(): IFilter;
/**
* Fresh sort for collection list
*
* @since 2025.05.01
*
* @return ISort
*/
public function collectionListSort(): ISort;
/**
* Fetches details about a specific collection
*
* @since 2025.05.01
*
* @param string|int $id collection identifier
*/
public function collectionExtant(string|int $identifier): bool;
/**
* Fetches details about a specific collection
*
* @since 2025.05.01
*
* @param string|int $identifier collection identifier
*/
public function collectionFetch(string|int $identifier): ?ICollectionBase;
/**
* Lists all entities in a specific collection
*
* @since 2025.05.01
*
* @param string|int $collection collection identifier
*
* @return array<string|int,IEntityBase>
*/
public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $elements = null): array;
/**
* Fresh filter for entity list
*
* @since 2025.05.01
*
* @return Filter
*/
public function entityListFilter(): IFilter;
/**
* Fresh sort for entity list
*
* @since 2025.05.01
*
* @return ISort
*/
public function entityListSort(): ISort;
/**
* Fresh range for entity list
*
* @since 2025.05.01
*
* @param RangeType $type range type
*
* @return IRange
*/
public function entityListRange(RangeType $type): IRange;
/**
* Lists of all changes from a specific token
*
* @since 2025.05.01
*
* @param string|int $collection collection identifier
* @param string $signature token signature
* @param string $detail detail level ids | meta | full
*
* @return array
*
* [
* 'added' => array<string|int>,
* 'updated' => array<string|int>,
* 'deleted' => array<string|int>,
* 'signature' => string
* ]
*
*/
public function entityDelta(string|int $collection, string $signature, string $detail = 'ids'): array;
/**
* Confirms if specific entity exists in a collection
*
* @since 2025.05.01
*
* @param string|int $collection collection identifier
* @param string|int ...$identifiers list of entity identifiers
*
* @return array<string|int,bool>
*/
public function entityExtant(string|int $collection, string|int ...$identifiers): array;
/**
* Fetches details about a specific entities in a collection
*
* @since 2025.05.01
*
* @param string|int $collection collection identifier
* @param string|int ...$identifiers entity identifier
*
* @return array<string|int,IEntityBase>
*/
public function entityFetch(string|int $collection, string|int ...$identifiers): array;
}

79
shared/lib/People/Service/IServiceCollectionMutable.php
View File

@@ -1,79 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Service;
use KTXF\People\Collection\ICollectionBase;
use KTXF\People\Collection\ICollectionMutable;
interface IServiceCollectionMutable extends IServiceBase {
public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate';
public const CAPABILITY_COLLECTION_MODIFY = 'CollectionModify';
public const CAPABILITY_COLLECTION_DESTROY = 'CollectionDestroy';
public const CAPABILITY_COLLECTION_MOVE = 'CollectionMove';
/**
* Creates a new, empty collection object
*
* @since 2025.05.01
*
* @return ICollectionMutable
*/
public function collectionFresh(): ICollectionMutable;
/**
* Creates a new collection at the specified location
*
* @since 2025.05.01
*
* @param string|int $location The parent collection to create this collection in, or empty string for root
* @param ICollectionMutable $collection The collection to create
* @param array $options Additional options for the collection creation
*
* @return ICollectionBase
*
* @throws \KTXF\Resource\Exceptions\InvalidArgumentException
* @throws \KTXF\Resource\Exceptions\UnsupportedException
* @throws \KTXF\Resource\Exceptions\UnauthorizedException
*/
public function collectionCreate(string|int $location, ICollectionMutable $collection, array $options): ICollectionBase;
/**
* Modifies an existing collection
*
* @since 2025.05.01
*
* @param string|int $identifier The ID of the collection to modify
* @param ICollectionMutable $collection The collection with modifications
*
* @return ICollectionBase
*
* @throws \KTXF\Resource\Exceptions\InvalidArgumentException
* @throws \KTXF\Resource\Exceptions\UnsupportedException
* @throws \KTXF\Resource\Exceptions\UnauthorizedException
*/
public function collectionModify(string|int $identifier, ICollectionMutable $collection): ICollectionBase;
/**
* Destroys an existing collection
*
* @since 2025.05.01
*
* @param string|int $identifier The ID of the collection to destroy
*
* @return bool
*
* @throws \KTXF\Resource\Exceptions\InvalidArgumentException
* @throws \KTXF\Resource\Exceptions\UnsupportedException
* @throws \KTXF\Resource\Exceptions\UnauthorizedException
*/
public function collectionDestroy(string|int $identifier): bool;
}

82
shared/lib/People/Service/IServiceEntityMutable.php
View File

@@ -1,82 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Service;
use KTXF\People\Entity\IEntityBase;
use KTXF\People\Entity\IEntityMutable;
interface IServiceEntityMutable extends IServiceBase {
public const CAPABILITY_ENTITY_CREATE = 'EntityCreate';
public const CAPABILITY_ENTITY_MODIFY = 'EntityModify';
public const CAPABILITY_ENTITY_DESTROY = 'EntityDestroy';
public const CAPABILITY_ENTITY_COPY = 'EntityCopy';
public const CAPABILITY_ENTITY_MOVE = 'EntityMove';
/**
* Creates a fresh entity of the specified type
*
* @since 2025.05.01
*
* @return IEntityMutable
*/
public function entityFresh(): IEntityMutable;
/**
* Creates a new entity in the specified collection
*
* @since 2025.05.01
*
* @param string|int $collection The collection to create this entity in
* @param IEntityMutable $entity The entity to create
* @param array $options Additional options for the entity creation
*
* @return IEntityMutable
*
* @throws \KTXF\Resource\Exceptions\InvalidArgumentException
* @throws \KTXF\Resource\Exceptions\UnsupportedException
* @throws \KTXF\Resource\Exceptions\UnauthorizedException
*/
public function entityCreate(string|int $collection, IEntityMutable $entity, array $options): IEntityMutable;
/**
* Modifies an existing entity in the specified collection
*
* @since 2025.05.01
*
* @param string|int $collection The collection containing the entity to modify
* @param string|int $identifier The ID of the entity to modify
* @param IEntityMutable $entity The entity with modifications
*
* @return IEntityMutable
*
* @throws \KTXF\Resource\Exceptions\InvalidArgumentException
* @throws \KTXF\Resource\Exceptions\UnsupportedException
* @throws \KTXF\Resource\Exceptions\UnauthorizedException
*/
public function entityModify(string|int $collection, string|int $identifier, IEntityMutable $entity): IEntityMutable;
/**
* Destroys an existing entity in the specified collection
*
* @since 2025.05.01
*
* @param string|int $collection The collection containing the entity to destroy
* @param string|int $identifier The ID of the entity to destroy
*
* @return bool
*
* @throws \KTXF\Resource\Exceptions\InvalidArgumentException
* @throws \KTXF\Resource\Exceptions\UnsupportedException
* @throws \KTXF\Resource\Exceptions\UnauthorizedException
*/
public function entityDestroy(string|int $collection, string|int $identifier): IEntityBase;
}

30
shared/lib/People/Service/IServiceMutable.php
View File

@@ -1,30 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Service;
use KTXF\Json\JsonDeserializable;
interface IServiceMutable extends IServiceBase, JsonDeserializable {
/**
* Sets the localized human friendly name of this service (e.g. ACME Company Mail Service)
*
* @since 2025.05.01
*/
public function setLabel(string $value): self;
/**
* Sets the active status of this service
*
* @since 2025.05.01
*/
public function setEnabled(bool $value): self;
}

199
shared/lib/People/Service/ServiceBaseInterface.php Normal file
View File

@@ -0,0 +1,199 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Service;
use KTXF\People\Collection\CollectionBaseInterface;
use KTXF\Resource\Delta\Delta;
use KTXF\Resource\Filter\IFilter;
use KTXF\Resource\Provider\ResourceServiceBaseInterface;
use KTXF\Resource\Range\IRange;
use KTXF\Resource\Range\RangeType;
use KTXF\Resource\Sort\ISort;
/**
* Service Base Interface
*
* Minimum interface for a service, providing read-only access to collections and entities.
*
* @since 2025.05.01
*/
interface ServiceBaseInterface extends ResourceServiceBaseInterface {
// Collection capabilities
public const CAPABILITY_COLLECTION_LIST = 'CollectionList';
public const CAPABILITY_COLLECTION_LIST_FILTER = 'CollectionListFilter';
public const CAPABILITY_COLLECTION_LIST_SORT = 'CollectionListSort';
public const CAPABILITY_COLLECTION_EXTANT = 'CollectionExtant';
public const CAPABILITY_COLLECTION_FETCH = 'CollectionFetch';
// Collection Filter
public const CAPABILITY_COLLECTION_FILTER_LABEL = 'label';
public const CAPABILITY_COLLECTION_FILTER_CONTENTS = 'contents';
// Collection Sort
public const CAPABILITY_COLLECTION_SORT_LABEL = 'label';
public const CAPABILITY_COLLECTION_SORT_RANK = 'rank';
// Entity capabilities
public const CAPABILITY_ENTITY_LIST = 'EntityList';
public const CAPABILITY_ENTITY_LIST_FILTER = 'EntityListFilter';
public const CAPABILITY_ENTITY_LIST_SORT = 'EntityListSort';
public const CAPABILITY_ENTITY_LIST_RANGE = 'EntityListRange';
public const CAPABILITY_ENTITY_DELTA = 'EntityDelta';
public const CAPABILITY_ENTITY_EXTANT = 'EntityExtant';
public const CAPABILITY_ENTITY_FETCH = 'EntityFetch';
// Filter capabilities
public const CAPABILITY_ENTITY_FILTER_ALL = '*';
public const CAPABILITY_ENTITY_FILTER_ID = 'id';
public const CAPABILITY_ENTITY_FILTER_URID = 'urid';
public const CAPABILITY_ENTITY_FILTER_LABEL = 'label';
// Sort capabilities
public const CAPABILITY_ENTITY_SORT_ID = 'id';
public const CAPABILITY_ENTITY_SORT_URID = 'urid';
public const CAPABILITY_ENTITY_SORT_LABEL = 'label';
public const CAPABILITY_ENTITY_SORT_PRIORITY = 'priority';
// Range capabilities
public const CAPABILITY_ENTITY_RANGE_TALLY = 'tally';
public const CAPABILITY_ENTITY_RANGE_TALLY_ABSOLUTE = 'absolute';
public const CAPABILITY_ENTITY_RANGE_TALLY_RELATIVE = 'relative';
public const JSON_TYPE = 'people:service';
/**
* Lists all collections in this service
*
* @since 2025.05.01
*
* @param IFilter|null $filter Optional filter criteria
* @param ISort|null $sort Optional sort order
*
* @return array<string|int,CollectionBaseInterface> Collections indexed by ID
*/
public function collectionList(string|int $location, ?IFilter $filter = null, ?ISort $sort = null): array;
/**
* Creates a filter builder for collections
*
* @since 2025.05.01
*
* @return IFilter
*/
public function collectionListFilter(): IFilter;
/**
* Creates a sort builder for collections
*
* @since 2025.05.01
*
* @return ISort
*/
public function collectionListSort(): ISort;
/**
* Checks if collections exist
*
* @since 2025.05.01
*
* @param string|int ...$identifiers Collection IDs to check
*
* @return array<string|int,bool> Map of ID => exists
*/
public function collectionExtant(string|int $location, string|int ...$identifiers): array;
/**
* Fetches a single collection
*
* @since 2025.05.01
*
* @param string|int $identifier Collection ID
*
* @return CollectionBaseInterface|null Collection or null if not found
*/
public function collectionFetch(string|int $identifier): ?CollectionBaseInterface;
/**
* Lists messages in a collection
*
* @since 2025.05.01
*
* @param string|int $collection Collection ID
* @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
*
* @return array<string|int,EntityBaseInterface> Messages indexed by ID
*/
public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array;
/**
* Creates a filter builder for messages
*
* @since 2025.05.01
*
* @return IFilter
*/
public function entityListFilter(): IFilter;
/**
* Creates a sort builder for messages
*
* @since 2025.05.01
*
* @return ISort
*/
public function entityListSort(): ISort;
/**
* Creates a range builder for messages
*
* @since 2025.05.01
*
* @param RangeType $type Range type (offset, cursor, etc.)
*
* @return IRange
*/
public function entityListRange(RangeType $type): IRange;
/**
* Gets incremental changes since last sync
*
* @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'
*
* @return array ['signature' => string, 'added' => array, 'modified' => array, 'removed' => array]
*/
public function entityDelta(string|int $collection, string $signature, string $detail = 'ids'): Delta;
/**
* Checks if messages exist
*
* @since 2025.05.01
*
* @param string|int $collection Collection ID
* @param string|int ...$identifiers Message IDs to check
*
* @return array<string|int,bool> Map of ID => exists
*/
public function entityExtant(string|int $collection, string|int ...$identifiers): array;
/**
* Fetches one or more entities
*
* @since 2025.05.01
*
* @param string|int $collection Collection ID
* @param string|int ...$identifiers Message IDs to fetch
*
* @return array<string|int,EntityBaseInterface> Messages indexed by ID
*/
public function entityFetch(string|int $collection, string|int ...$identifiers): array;
}

75
shared/lib/People/Service/ServiceCollectionMutableInterface.php Normal file
View File

@@ -0,0 +1,75 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Service;
use KTXF\People\Collection\CollectionBaseInterface;
use KTXF\People\Collection\CollectionMutableInterface;
/**
* Service Collection Mutable Interface
*
* Optional interface for services that support collection CRUD operations.
*
* @since 2025.05.01
*/
interface ServiceCollectionMutableInterface {
public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate';
public const CAPABILITY_COLLECTION_UPDATE = 'CollectionUpdate';
public const CAPABILITY_COLLECTION_DELETE = 'CollectionDelete';
/**
* Creates a fresh collection instance for configuration
*
* @since 2025.05.01
*
* @return CollectionMutableInterface Fresh collection object
*/
public function collectionFresh(): CollectionMutableInterface;
/**
* Creates a new collection
*
* @since 2025.05.01
*
* @param string|int|null $location Parent collection ID (null for root)
* @param CollectionMutableInterface $collection Collection to create
* @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;
/**
* Updates an existing collection
*
* @since 2025.05.01
*
* @param string|int $identifier Collection ID
* @param CollectionMutableInterface $collection Updated collection data
*
* @return CollectionBaseInterface Updated collection
*/
public function collectionUpdate(string|int $identifier, CollectionMutableInterface $collection): CollectionBaseInterface;
/**
* Deletes a collection
*
* @since 2025.05.01
*
* @param string|int $identifier Collection ID
* @param bool $force Force deletion even if not empty
* @param bool $recursive Recursively delete contents
*
* @return bool True if deleted
*/
public function collectionDelete(string|int $identifier, bool $force = false, bool $recursive = false): bool;
}

23
shared/lib/People/Service/ServiceConfigurableInterface.php Normal file
View File

@@ -0,0 +1,23 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Service;
use KTXF\Resource\Provider\ResourceServiceConfigureInterface;
/**
* Service Configurable Interface
*
* Optional interface for services that require configuration
*
* @since 2025.05.01
*/
interface ServiceConfigurableInterface extends ResourceServiceConfigureInterface {
}

76
shared/lib/People/Service/ServiceEntityMutableInterface.php Normal file
View File

@@ -0,0 +1,76 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Service;
use KTXF\People\Entity\EntityBaseInterface;
use KTXF\People\Entity\EntityMutableInterface;
/**
* Service Entity Mutable Interface
*
* 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_DELETE = 'EntityDelete';
public const CAPABILITY_ENTITY_COPY = 'EntityCopy';
public const CAPABILITY_ENTITY_MOVE = 'EntityMove';
/**
* Creates a fresh entity instance for composition
*
* @since 2025.05.01
*
* @return EntityMutableInterface Fresh entity object
*/
public function entityFresh(): EntityMutableInterface;
/**
* Creates/imports an entity into a collection
*
* @since 2025.05.01
*
* @param string|int $collection collection identifier
* @param EntityMutableInterface $entity Entity data
* @param array $options additional options
*
* @return EntityBaseInterface Created entity
*/
public function entityCreate(string|int $collection, EntityMutableInterface $entity, 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
*
* @return EntityBaseInterface Modified entity
*/
public function entityUpdate(string|int $collection, string|int $identifier, EntityMutableInterface $entity): EntityBaseInterface;
/**
* Deletes an existing entity in the specified collection
*
* @since 2025.05.01
*
* @param string|int $collection Collection identifier
* @param string|int $identifier Entity identifier to delete
*
* @return EntityBaseInterface Deleted entity
*/
public function entityDelete(string|int $collection, string|int $identifier): EntityBaseInterface;
}

21
shared/lib/People/Service/ServiceMutableInterface.php Normal file
View File

@@ -0,0 +1,21 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\People\Service;
/**
* Service Mutable Interface
*
* Marker interface for services that support mutable operations
*
* @since 2025.05.01
*/
interface ServiceMutableInterface {
}

2
shared/lib/Resource/Provider/ResourceProviderServiceMutateInterface.php
View File

@@ -11,7 +11,7 @@ namespace KTXF\Resource\Provider;
use KTXF\Json\JsonDeserializable;
interface ResourceProviderServiceMutateInterface extends ResourceProviderBaseInterface, JsonDeserializable {
interface ResourceProviderServiceMutateInterface extends JsonDeserializable {
/**
* construct and new blank service instance

5
shared/lib/Resource/Provider/ResourceServiceConfigureInterface.php
View File

@@ -12,12 +12,11 @@ namespace KTXF\Resource\Provider;
/**
* Resource Service Configurable Interface
*
* Extends base service interface with setter methods for mutable properties.
* Used for service configuration and updates.
* Optional interface for services that require configuration
*
* @since 2025.05.01
*/
interface ResourceServiceConfigureInterface extends ResourceServiceMutateInterface {
interface ResourceServiceConfigureInterface {
/**
* Sets the location/configuration of this service

7
shared/lib/Resource/Provider/ResourceServiceMutateInterface.php
View File

@@ -12,14 +12,13 @@ namespace KTXF\Resource\Provider;
use KTXF\Json\JsonDeserializable;
/**
* Resource Service Configurable Interface
* Resource Service Mutate Interface
*
* Extends base service interface with setter methods for mutable properties.
* Used for service configuration and updates.
* Optional interface for services that support mutable operations.
*
* @since 2025.05.01
*/
interface ResourceServiceMutateInterface extends ResourceServiceBaseInterface, JsonDeserializable {
interface ResourceServiceMutateInterface extends JsonDeserializable {
/**
* Sets the localized human-friendly name of this service (e.g. ACME Company Mail Service)