refactor: documents interfaces
Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
This commit is contained in:
@@ -0,0 +1,264 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
|
||||
* SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
*/
|
||||
|
||||
namespace KTXF\Documents\Service;
|
||||
|
||||
use Generator;
|
||||
use KTXF\Documents\Collection\CollectionBaseInterface;
|
||||
use KTXF\Documents\Entity\EntityBaseInterface;
|
||||
use KTXF\Resource\Delta\Delta;
|
||||
use KTXF\Resource\Filter\IFilter;
|
||||
use KTXF\Resource\Identifier\EntityIdentifierInterface;
|
||||
use KTXF\Resource\Provider\ResourceServiceBaseInterface;
|
||||
use KTXF\Resource\Range\IRange;
|
||||
use KTXF\Resource\Range\RangeType;
|
||||
use KTXF\Resource\Sort\ISort;
|
||||
|
||||
/**
|
||||
* Service Base Interface
|
||||
*
|
||||
* 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';
|
||||
public const CAPABILITY_ENTITY_READ = 'EntityRead';
|
||||
// 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 = 'document:service';
|
||||
|
||||
/**
|
||||
* Lists all collections in this service
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string|int|null $location Optional parent collection identifier to list within (null for root)
|
||||
* @param IFilter|null $filter Optional filter criteria
|
||||
* @param ISort|null $sort Optional sort order
|
||||
*
|
||||
* @return array<string|int,CollectionBaseInterface> Collections indexed by identifier
|
||||
*/
|
||||
public function collectionList(string|int|null $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|null $location Optional parent collection identifier (null for root)
|
||||
* @param string|int ...$identifiers Collection identifiers to check
|
||||
*
|
||||
* @return array<string|int,bool> Map of identifier => exists
|
||||
*/
|
||||
public function collectionExtant(string|int|null $location, string|int ...$identifiers): array;
|
||||
|
||||
/**
|
||||
* Fetches a single collection
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string|int $identifier Collection identifier
|
||||
*
|
||||
* @return CollectionBaseInterface|null Collection or null if not found
|
||||
*/
|
||||
public function collectionFetch(string|int $identifier): ?CollectionBaseInterface;
|
||||
|
||||
/**
|
||||
* Lists entities in a collection
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string|int|null $collection Collection identifier (null for root)
|
||||
* @param IFilter|null $filter Optional filter criteria
|
||||
* @param ISort|null $sort Optional sort order
|
||||
* @param IRange|null $range Optional pagination
|
||||
* @param array|null $properties Optional entity properties to fetch
|
||||
*
|
||||
* @return array<string|int,EntityBaseInterface> Entities indexed by identifier
|
||||
*/
|
||||
public function entityListBulk(string|int|null $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array;
|
||||
|
||||
/**
|
||||
* Lists entities in a collection
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string|int|null $collection Collection identifier (null for root)
|
||||
* @param IFilter|null $filter Optional filter criteria
|
||||
* @param ISort|null $sort Optional sort order
|
||||
* @param IRange|null $range Optional pagination
|
||||
* @param array|null $properties Optional entity properties to fetch
|
||||
*
|
||||
* @return Generator Yields entities one by one as EntityBaseInterface
|
||||
*/
|
||||
public function entityListStream(string|int|null $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): Generator;
|
||||
|
||||
/**
|
||||
* Creates a filter builder for entities
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @return IFilter
|
||||
*/
|
||||
public function entityListFilter(): IFilter;
|
||||
|
||||
/**
|
||||
* Creates a sort builder for entities
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @return ISort
|
||||
*/
|
||||
public function entityListSort(): ISort;
|
||||
|
||||
/**
|
||||
* Creates a range builder for entities
|
||||
*
|
||||
* @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 signature
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string|int|null $collection Collection identifier (null for root)
|
||||
* @param string $signature Token from previous delta
|
||||
*
|
||||
* @return Delta
|
||||
*/
|
||||
public function entityDelta(string|int|null $collection, string $signature): Delta;
|
||||
|
||||
/**
|
||||
* Checks if entities exist
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string|int|null $collection Collection identifier (null for root)
|
||||
* @param string|int ...$identifiers Entity identifiers to check
|
||||
*
|
||||
* @return array<string|int,bool> Map of identifier => exists
|
||||
*/
|
||||
public function entityExtant(string|int|null $collection, string|int ...$identifiers): array;
|
||||
|
||||
/**
|
||||
* Fetches one or more entities as an array
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param EntityIdentifierInterface ...$identifiers Entity identifiers to fetch
|
||||
*
|
||||
* @return array<string|int,EntityBaseInterface> Entities indexed by identifier
|
||||
*/
|
||||
public function entityFetchBulk(EntityIdentifierInterface ...$identifiers): array;
|
||||
|
||||
/**
|
||||
* Fetches one or more entities as a stream
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param EntityIdentifierInterface ...$identifiers Entity identifiers to fetch
|
||||
*
|
||||
* @return Generator<string|int,EntityBaseInterface> Yields entities one by one
|
||||
*/
|
||||
public function entityFetchStream(EntityIdentifierInterface ...$identifiers): Generator;
|
||||
|
||||
/**
|
||||
* Reads the full content of an entity
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param EntityIdentifierInterface $target Target entity identifier
|
||||
*
|
||||
* @return string|null Entity content or null if not found
|
||||
*/
|
||||
public function entityRead(EntityIdentifierInterface $target): ?string;
|
||||
|
||||
/**
|
||||
* Opens a read stream for the content of an entity
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param EntityIdentifierInterface $target Target entity identifier
|
||||
*
|
||||
* @return resource|null Read stream or null if not found
|
||||
*/
|
||||
public function entityReadStream(EntityIdentifierInterface $target);
|
||||
|
||||
/**
|
||||
* Reads a chunk of the content of an entity
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param EntityIdentifierInterface $target Target entity identifier
|
||||
* @param int $offset Byte offset to start reading from
|
||||
* @param int $length Number of bytes to read
|
||||
*
|
||||
* @return string|null Content chunk or null if not found
|
||||
*/
|
||||
public function entityReadChunk(EntityIdentifierInterface $target, int $offset, int $length): ?string;
|
||||
|
||||
}
|
||||
@@ -0,0 +1,102 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
|
||||
* SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
*/
|
||||
|
||||
namespace KTXF\Documents\Service;
|
||||
|
||||
use KTXF\Documents\Collection\CollectionBaseInterface;
|
||||
use KTXF\Documents\Collection\CollectionMutableInterface;
|
||||
use KTXF\Documents\Collection\CollectionPropertiesBaseInterface;
|
||||
use KTXF\Resource\Identifier\CollectionIdentifierInterface;
|
||||
|
||||
/**
|
||||
* 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';
|
||||
public const CAPABILITY_COLLECTION_MOVE = 'CollectionMove';
|
||||
public const CAPABILITY_COLLECTION_COPY = 'CollectionCopy';
|
||||
|
||||
/**
|
||||
* 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 CollectionIdentifierInterface|null $target Target collection identifier (parent, null for root)
|
||||
* @param CollectionPropertiesBaseInterface $properties Collection properties
|
||||
* @param array $options Protocol-specific options
|
||||
*
|
||||
* @return CollectionBaseInterface Created collection with assigned ID
|
||||
*/
|
||||
public function collectionCreate(CollectionIdentifierInterface|null $target, CollectionPropertiesBaseInterface $properties, array $options = []): CollectionBaseInterface;
|
||||
|
||||
/**
|
||||
* Updates an existing collection
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param CollectionIdentifierInterface $target Target collection identifier
|
||||
* @param CollectionPropertiesBaseInterface $properties Updated collection data
|
||||
*
|
||||
* @return CollectionBaseInterface Updated collection
|
||||
*/
|
||||
public function collectionUpdate(CollectionIdentifierInterface $target, CollectionPropertiesBaseInterface $properties): CollectionBaseInterface;
|
||||
|
||||
/**
|
||||
* Deletes a collection
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param CollectionIdentifierInterface $target Target collection identifier
|
||||
* @param bool $force Force deletion even if not empty
|
||||
*
|
||||
* @return CollectionBaseInterface|true Collection object on soft delete, true on hard delete
|
||||
*/
|
||||
public function collectionDelete(CollectionIdentifierInterface $target, bool $force = false): CollectionBaseInterface | true;
|
||||
|
||||
/**
|
||||
* Moves a collection to a new parent
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param CollectionIdentifierInterface|null $target Target parent collection identifier (null for root)
|
||||
* @param CollectionIdentifierInterface $source Source collection identifier
|
||||
*
|
||||
* @return CollectionBaseInterface Moved collection
|
||||
*/
|
||||
public function collectionMove(CollectionIdentifierInterface|null $target, CollectionIdentifierInterface $source): CollectionBaseInterface;
|
||||
|
||||
/**
|
||||
* Copies a collection to a new parent
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param CollectionIdentifierInterface|null $target Target parent collection identifier (null for root)
|
||||
* @param CollectionIdentifierInterface $source Source collection identifier
|
||||
*
|
||||
* @return CollectionBaseInterface Copied collection
|
||||
*/
|
||||
public function collectionCopy(CollectionIdentifierInterface|null $target, CollectionIdentifierInterface $source): CollectionBaseInterface;
|
||||
|
||||
}
|
||||
@@ -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\Documents\Service;
|
||||
|
||||
use KTXF\Resource\Provider\ResourceServiceConfigureInterface;
|
||||
|
||||
/**
|
||||
* Service Configurable Interface
|
||||
*
|
||||
* Extends base service interface with setter methods for mutable properties
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*/
|
||||
interface ServiceConfigurableInterface extends ResourceServiceConfigureInterface {
|
||||
|
||||
}
|
||||
@@ -0,0 +1,151 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
|
||||
* SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
*/
|
||||
|
||||
namespace KTXF\Documents\Service;
|
||||
|
||||
use KTXF\Documents\Entity\EntityBaseInterface;
|
||||
use KTXF\Documents\Entity\EntityMutableInterface;
|
||||
use KTXF\Documents\Entity\EntityPropertiesMutableInterface;
|
||||
use KTXF\Resource\Identifier\CollectionIdentifierInterface;
|
||||
use KTXF\Resource\Identifier\EntityIdentifierInterface;
|
||||
|
||||
/**
|
||||
* Service Entity Mutable Interface
|
||||
*
|
||||
* Optional interface for services that support entity CRUD operations
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*/
|
||||
interface ServiceEntityMutableInterface {
|
||||
|
||||
public const CAPABILITY_ENTITY_CREATE = 'EntityCreate';
|
||||
public const CAPABILITY_ENTITY_MODIFY = 'EntityModify';
|
||||
public const CAPABILITY_ENTITY_DELETE = 'EntityDelete';
|
||||
public const CAPABILITY_ENTITY_COPY = 'EntityCopy';
|
||||
public const CAPABILITY_ENTITY_MOVE = 'EntityMove';
|
||||
public const CAPABILITY_ENTITY_WRITE = 'EntityWrite';
|
||||
|
||||
/**
|
||||
* 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 CollectionIdentifierInterface $target Target collection identifier
|
||||
* @param EntityPropertiesMutableInterface $properties Entity properties
|
||||
* @param array $options Additional options
|
||||
*
|
||||
* @return EntityBaseInterface Created entity
|
||||
*/
|
||||
public function entityCreate(CollectionIdentifierInterface $target, EntityPropertiesMutableInterface $properties, array $options = []): EntityBaseInterface;
|
||||
|
||||
/**
|
||||
* Modifies an existing entity
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param EntityIdentifierInterface $target Target entity identifier
|
||||
* @param EntityPropertiesMutableInterface $properties Entity properties to update
|
||||
*
|
||||
* @return EntityBaseInterface Modified entity
|
||||
*/
|
||||
public function entityModify(EntityIdentifierInterface $target, EntityPropertiesMutableInterface $properties): EntityBaseInterface;
|
||||
|
||||
/**
|
||||
* Deletes entities
|
||||
*
|
||||
* @since 2026.04.01
|
||||
*
|
||||
* @param EntityIdentifierInterface ...$targets Source entities to delete
|
||||
*
|
||||
* @return array<string, array{
|
||||
* disposition: 'deleted'|'error',
|
||||
* destination: ?CollectionIdentifierInterface,
|
||||
* mutation: EntityIdentifierInterface
|
||||
* }> Results keyed by source entity identifier
|
||||
*/
|
||||
public function entityDelete(EntityIdentifierInterface ...$targets): array;
|
||||
|
||||
/**
|
||||
* Moves entities to another collection
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param CollectionIdentifierInterface $target Target collection identifier
|
||||
* @param EntityIdentifierInterface ...$sources Source entities to move
|
||||
*
|
||||
* @return array<string, array{
|
||||
* disposition: 'moved'|'error',
|
||||
* destination: ?CollectionIdentifierInterface,
|
||||
* mutation: EntityIdentifierInterface
|
||||
* }> Results keyed by source entity identifier
|
||||
*/
|
||||
public function entityMove(CollectionIdentifierInterface $target, EntityIdentifierInterface ...$sources): array;
|
||||
|
||||
/**
|
||||
* Copies entities to another collection
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param CollectionIdentifierInterface $target Target collection identifier
|
||||
* @param EntityIdentifierInterface ...$sources Source entities to copy
|
||||
*
|
||||
* @return array<string, array{
|
||||
* disposition: 'copied'|'error',
|
||||
* destination: ?CollectionIdentifierInterface,
|
||||
* mutation: EntityIdentifierInterface
|
||||
* }> Results keyed by source entity identifier
|
||||
*/
|
||||
public function entityCopy(CollectionIdentifierInterface $target, EntityIdentifierInterface ...$sources): array;
|
||||
|
||||
/**
|
||||
* Writes the full content of an entity
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param EntityIdentifierInterface $target Target entity identifier
|
||||
* @param string $data Content to write
|
||||
*
|
||||
* @return int Number of bytes written
|
||||
*/
|
||||
public function entityWrite(EntityIdentifierInterface $target, string $data): int;
|
||||
|
||||
/**
|
||||
* Writes a chunk of content to an entity
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param EntityIdentifierInterface $target Target entity identifier
|
||||
* @param int $offset Byte offset to start writing at
|
||||
* @param string $data Content chunk to write
|
||||
*
|
||||
* @return int Number of bytes written
|
||||
*/
|
||||
public function entityWriteChunk(EntityIdentifierInterface $target, int $offset, string $data): int;
|
||||
|
||||
/**
|
||||
* Opens a write stream for the content of an entity
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param EntityIdentifierInterface $target Target entity identifier
|
||||
*
|
||||
* @return resource|null Write stream or null if not found
|
||||
*/
|
||||
public function entityWriteStream(EntityIdentifierInterface $target);
|
||||
|
||||
}
|
||||
@@ -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\Documents\Service;
|
||||
|
||||
use KTXF\Resource\Provider\ResourceServiceMutateInterface;
|
||||
|
||||
/**
|
||||
* Service Mutable Interface
|
||||
*
|
||||
* Extends base service interface with setter methods for mutable properties
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*/
|
||||
interface ServiceMutableInterface extends ResourceServiceMutateInterface {
|
||||
|
||||
}
|
||||
Reference in New Issue
Block a user