* SPDX-License-Identifier: AGPL-3.0-or-later */ namespace KTXF\Files\Service; use KTXF\Files\Node\INodeEntityBase; use KTXF\Files\Node\INodeEntityMutable; 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'; public const CAPABILITY_ENTITY_WRITE = 'EntityWrite'; public const CAPABILITY_ENTITY_WRITE_STREAM = 'EntityWriteStream'; public const CAPABILITY_ENTITY_WRITE_CHUNK = 'EntityWriteChunk'; /** * Creates a new, empty entity node * * @since 2025.11.01 */ public function entityFresh(): INodeEntityMutable; /** * Creates a new entity in the specified collection * * @since 2025.11.01 * * @param string|int|null $collection Collection identifier, null for root * @param INodeEntityMutable $entity The entity to create * @param array $options Additional options * * @throws \KTXF\Resource\Exceptions\InvalidArgumentException * @throws \KTXF\Resource\Exceptions\UnsupportedException * @throws \KTXF\Resource\Exceptions\UnauthorizedException */ public function entityCreate(string|int|null $collection, INodeEntityMutable $entity, array $options = []): INodeEntityBase; /** * Modifies an existing entity in the specified collection * * @since 2025.11.01 * * @param string|int|null $collection Collection identifier * @param string|int $identifier Entity identifier * @param INodeEntityMutable $entity The entity with modifications * * @throws \KTXF\Resource\Exceptions\InvalidArgumentException * @throws \KTXF\Resource\Exceptions\UnsupportedException * @throws \KTXF\Resource\Exceptions\UnauthorizedException */ public function entityModify(string|int|null $collection, string|int $identifier, INodeEntityMutable $entity): INodeEntityBase; /** * Destroys an existing entity in the specified collection * * @since 2025.11.01 * * @param string|int|null $collection Collection identifier * @param string|int $identifier Entity identifier * * @throws \KTXF\Resource\Exceptions\InvalidArgumentException * @throws \KTXF\Resource\Exceptions\UnsupportedException * @throws \KTXF\Resource\Exceptions\UnauthorizedException */ public function entityDestroy(string|int|null $collection, string|int $identifier): bool; /** * Copies an existing entity to a new collection * * @since 2025.11.01 * * @param string|int|null $collection Source collection identifier * @param string|int $identifier Entity identifier * @param string|int|null $destination Destination collection identifier, null for root * * @throws \KTXF\Resource\Exceptions\InvalidArgumentException * @throws \KTXF\Resource\Exceptions\UnsupportedException * @throws \KTXF\Resource\Exceptions\UnauthorizedException */ public function entityCopy(string|int|null $collection, string|int $identifier, string|int|null $destination): INodeEntityBase; /** * Moves an existing entity to a new collection * * @since 2025.11.01 * * @param string|int|null $collection Source collection identifier * @param string|int $identifier Entity identifier * @param string|int|null $destination Destination collection identifier, null for root * * @throws \KTXF\Resource\Exceptions\InvalidArgumentException * @throws \KTXF\Resource\Exceptions\UnsupportedException * @throws \KTXF\Resource\Exceptions\UnauthorizedException */ public function entityMove(string|int|null $collection, string|int $identifier, string|int|null $destination): INodeEntityBase; /** * Writes the entire content of an entity from a string * * @since 2025.11.01 * * @param string|int|null $collection Collection identifier * @param string|int $identifier Entity identifier * @param string $data Content to write * * @return int Number of bytes written * * @throws \KTXF\Resource\Exceptions\InvalidArgumentException * @throws \KTXF\Resource\Exceptions\UnsupportedException * @throws \KTXF\Resource\Exceptions\UnauthorizedException */ public function entityWrite(string|int|null $collection, string|int $identifier, string $data): int; /** * Opens a stream to write the content of an entity * * @since 2025.11.01 * * @param string|int|null $collection Collection identifier * @param string|int $identifier Entity identifier * * @return resource Stream resource for writing * * @throws \KTXF\Resource\Exceptions\InvalidArgumentException * @throws \KTXF\Resource\Exceptions\UnsupportedException * @throws \KTXF\Resource\Exceptions\UnauthorizedException */ public function entityWriteStream(string|int|null $collection, string|int $identifier); /** * Writes a chunk of content to an entity at a specific position * * @since 2025.11.01 * * @param string|int|null $collection Collection identifier * @param string|int $identifier Entity identifier * @param int $offset Starting byte position (0-indexed) * @param string $data Chunk content to write * * @return int Number of bytes written * * @throws \KTXF\Resource\Exceptions\InvalidArgumentException * @throws \KTXF\Resource\Exceptions\UnsupportedException * @throws \KTXF\Resource\Exceptions\UnauthorizedException */ public function entityWriteChunk(string|int|null $collection, string|int $identifier, int $offset, string $data): int; }