<?php

namespace interfaces;

use attachments\helpers\attachment;
use attachments\helpers\attachment_content;
use objects\object_attachments_o;

interface attachments_i
{
    /**
     * List attachments for a given entity.
     * @param string $type The type of the entity parent. (E.g. users_o, groups_o, etc.)
     * @param int $object_id The ID of the entity.
     * @param array $options Optional parameters for filtering or modifying the retrieval.
     * @return attachment[] An array of attachment objects.
     */
    public function list(string $type, int $object_id, array $options = []): array;
    /**
     * Get an attachment by its ID.
     * @param int $attachment_id The ID of the attachment to be retrieved.
     * @return array|null An associative array representing the attachment, or null if not found.
     */
    public function get(int $attachment_id): ?object_attachments_o;
    /**
     * Add an attachment to a given entity.
     * @param string $type The type of the entity parent. (E.g. users_o, groups_o, etc.)
     * @param int $object_id The ID of the entity.
     * @param attachment_content $attachment_content The content of the attachment to be added.
     * @return int|bool The ID of the newly created attachment on success, or false on failure.
     * @see attachment_content
     */
    public function create(string $type, int $object_id, attachment_content $attachment_content): int|bool;
    /**
     * Delete an attachment by its ID.
     * @param int $attachment_id The ID of the attachment to be deleted.
     * @return bool True on success, false on failure.
     */
    public function delete(int $attachment_id): bool;
    /**
     * Update an existing attachment.
     * @param int $attachment_id The ID of the attachment to be updated.
     * @param attachment_content $attachment_content The new content for the attachment.
     * @return bool True on success, false on failure.
     * @see attachment_content
     */
    public function update(int $attachment_id, attachment_content $attachment_content): bool;
}