<?php

declare(strict_types=1);

namespace App\Framework\Filesystem;

/**
 * Interface für Stream-basierte Storage-Operationen
 *
 * Ermöglicht das Arbeiten mit großen Dateien ohne komplettes Laden in den Speicher.
 * Ideal für große Analytics-Dateien, Logs und Media-Files.
 */
interface StreamableStorage
{
    /**
     * Öffnet einen Read-Stream für eine Datei
     *
     * @return resource
     */
    public function readStream(string $path);

    /**
     * Öffnet einen Write-Stream für eine Datei
     *
     * @return resource
     */
    public function writeStream(string $path);

    /**
     * Öffnet einen Append-Stream für eine Datei
     *
     * @return resource
     */
    public function appendStream(string $path);

    /**
     * Schreibt von einem Stream in eine Datei
     *
     * @param resource $stream
     */
    public function putStream(string $path, $stream): void;

    /**
     * Kopiert eine Datei Stream-basiert (für große Dateien)
     */
    public function copyStream(string $source, string $destination): void;

    /**
     * Liest Datei Zeile für Zeile (Generator für Memory-Effizienz)
     *
     * @return \Generator<string>
     */
    public function readLines(string $path): \Generator;
}
