From 1d706de6637454a639ec0f1fe7aa1c25e3988143 Mon Sep 17 00:00:00 2001 From: Sebastian Krupinski Date: Fri, 6 Mar 2026 22:50:08 -0500 Subject: [PATCH] feat: improve mail resource interface Signed-off-by: Sebastian Krupinski --- .../Mail/Service/ServiceMutableInterface.php | 3 +- .../Service/ServiceBaseInterface.php | 31 +++++++++++++------ .../Service/ServiceEntityMutableInterface.php | 11 +++++-- .../Provider/Node/NodeBaseAbstract.php | 4 ++- 4 files changed, 35 insertions(+), 14 deletions(-) diff --git a/shared/lib/Mail/Service/ServiceMutableInterface.php b/shared/lib/Mail/Service/ServiceMutableInterface.php index 5a539c7..531c366 100644 --- a/shared/lib/Mail/Service/ServiceMutableInterface.php +++ b/shared/lib/Mail/Service/ServiceMutableInterface.php @@ -10,6 +10,7 @@ declare(strict_types=1); namespace KTXF\Mail\Service; use KTXF\Mail\Object\AddressInterface; +use KTXF\Resource\Provider\ResourceServiceMutateInterface; /** * Mail Service Mutable Interface @@ -19,7 +20,7 @@ use KTXF\Mail\Object\AddressInterface; * * @since 2025.05.01 */ -interface ServiceMutableInterface extends ServiceBaseInterface { +interface ServiceMutableInterface extends ServiceBaseInterface, ResourceServiceMutateInterface { /** * Sets the primary mailing address for this service diff --git a/shared/lib/Resource/Documents/Service/ServiceBaseInterface.php b/shared/lib/Resource/Documents/Service/ServiceBaseInterface.php index c29637f..eb1a293 100644 --- a/shared/lib/Resource/Documents/Service/ServiceBaseInterface.php +++ b/shared/lib/Resource/Documents/Service/ServiceBaseInterface.php @@ -68,12 +68,13 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { * * @since 2025.05.01 * + * @param string|int|null $location Optional parent collection ID to list within * @param IFilter|null $filter Optional filter criteria * @param ISort|null $sort Optional sort order * * @return array Collections indexed by ID */ - public function collectionList(string|int $location, ?IFilter $filter = null, ?ISort $sort = null): array; + public function collectionList(string|int|null $location, ?IFilter $filter = null, ?ISort $sort = null): array; /** * Creates a filter builder for collections @@ -102,7 +103,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { * * @return array Map of ID => exists */ - public function collectionExtant(string|int $location, string|int ...$identifiers): array; + public function collectionExtant(string|int|null $location, string|int ...$identifiers): array; /** * Fetches a single collection @@ -113,14 +114,14 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { * * @return CollectionBaseInterface|null Collection or null if not found */ - public function collectionFetch(string|int $identifier): ?CollectionBaseInterface; + public function collectionFetch(string|int|null $identifier): ?CollectionBaseInterface; /** * Lists messages in a collection * * @since 2025.05.01 * - * @param string|int $collection Collection ID + * @param string|int|null $collection Collection ID * @param IFilter|null $filter Optional filter criteria * @param ISort|null $sort Optional sort order * @param IRange|null $range Optional pagination @@ -128,7 +129,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { * * @return array Messages indexed by ID */ - public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array; + public function entityList(string|int|null $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array; /** * Creates a filter builder for messages @@ -164,13 +165,13 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { * * @since 2025.05.01 * - * @param string|int $collection Collection ID + * @param string|int|null $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; + public function entityDelta(string|int|null $collection, string $signature, string $detail = 'ids'): Delta; /** * Checks if messages exist @@ -182,7 +183,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { * * @return array Map of ID => exists */ - public function entityExtant(string|int $collection, string|int ...$identifiers): array; + public function entityExtant(string|int|null $collection, string|int ...$identifiers): array; /** * Fetches one or more entities @@ -194,6 +195,18 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { * * @return array Messages indexed by ID */ - public function entityFetch(string|int $collection, string|int ...$identifiers): array; + public function entityFetch(string|int|null $collection, string|int ...$identifiers): array; + + /** + * Reads the content of an entity + * + * @since 2025.05.01 + * + * @param string|int|null $collection Collection ID + * @param string|int $identifier Entity ID + * + * @return string|null Entity content or null if not found + */ + public function entityRead(string|int|null $collection, string|int $identifier): ?string; } diff --git a/shared/lib/Resource/Documents/Service/ServiceEntityMutableInterface.php b/shared/lib/Resource/Documents/Service/ServiceEntityMutableInterface.php index 09cdb49..bee92f5 100644 --- a/shared/lib/Resource/Documents/Service/ServiceEntityMutableInterface.php +++ b/shared/lib/Resource/Documents/Service/ServiceEntityMutableInterface.php @@ -49,7 +49,7 @@ interface ServiceEntityMutableInterface extends ServiceBaseInterface { * * @return EntityBaseInterface Created entity */ - public function entityCreate(string|int $collection, EntityMutableInterface $entity, array $options = []): EntityBaseInterface; + public function entityCreate(string|int|null $collection, EntityMutableInterface $entity, array $options = []): EntityBaseInterface; /** * Modifies an existing entity @@ -62,7 +62,8 @@ interface ServiceEntityMutableInterface extends ServiceBaseInterface { * * @return EntityBaseInterface Modified entity */ - public function entityUpdate(string|int $collection, string|int $identifier, EntityMutableInterface $entity): EntityBaseInterface; + public function entityUpdate(string|int|null $collection, string|int $identifier, EntityMutableInterface $entity): EntityBaseInterface; + /** * Deletes an existing entity in the specified collection * @@ -73,6 +74,10 @@ interface ServiceEntityMutableInterface extends ServiceBaseInterface { * * @return EntityBaseInterface Deleted entity */ - public function entityDelete(string|int $collection, string|int $identifier): EntityBaseInterface; + public function entityDelete(string|int|null $collection, string|int $identifier): EntityBaseInterface; + /** + * + */ + public function entityWrite(string|int|null $collection, string|int $identifier, string $data): int; } diff --git a/shared/lib/Resource/Provider/Node/NodeBaseAbstract.php b/shared/lib/Resource/Provider/Node/NodeBaseAbstract.php index 657e84e..d6460da 100644 --- a/shared/lib/Resource/Provider/Node/NodeBaseAbstract.php +++ b/shared/lib/Resource/Provider/Node/NodeBaseAbstract.php @@ -79,7 +79,9 @@ abstract class NodeBaseAbstract implements NodeBaseInterface { * @inheritDoc */ public function signature(): string|null { - return $this->data[static::JSON_PROPERTY_SIGNATURE] ?? null; + return isset($this->data[static::JSON_PROPERTY_SIGNATURE]) + ? (string)$this->data[static::JSON_PROPERTY_SIGNATURE] + : null; } /**