server/shared/lib/Files/Service/IServiceEntityMutable.php

<?php

declare(strict_types=1);

/**
 * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
 * 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;

}