server/shared/lib/Documents/Service/ServiceEntityMutableInterface.php

<?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);

}