Rework Stream readers and Sets to track stream properties

src/Model/Data/IStream.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Kanopi\Components\Model\Data;
+
+interface IStream {
+	/**
+	 * @return IStreamProperties
+	 */
+	function properties(): IStreamProperties;
+
+	/**
+	 * @return string
+	 */
+	function stream(): string;
+}

src/Model/Data/IStreamCollection.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Kanopi\Components\Model\Data;
+
+interface IStreamCollection {
+	/**
+	 * Iterable collection read from the stream
+	 *
+	 * @return iterable
+	 */
+	function collection(): iterable;
+
+	/**
+	 * The original stream source for the collection
+	 *
+	 * @return IStream
+	 */
+	function stream(): IStream;
+}

src/Model/Data/IStreamProperties.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Kanopi\Components\Model\Data;
+
+interface IStreamProperties {
+	/**
+	 * Last modified timestamp of the stream
+	 *
+	 * @return int
+	 */
+	function lastModifiedTimestamp(): int;
+
+	/**
+	 * Count/length of the stream
+	 *
+	 * @return int
+	 */
+	function length(): int;
+
+	/**
+	 * Timestamp of the stream read event
+	 *
+	 * @return int
+	 */
+	function readTimestamp(): int;
+
+	/**
+	 * URI of the stream
+	 *
+	 * @return string
+	 */
+	function uri(): string;
+}

src/Model/Data/Stream.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Kanopi\Components\Model\Data;
+
+class Stream implements IStream {
+	/**
+	 * @var IStreamProperties
+	 */
+	protected IStreamProperties $_properties;
+
+	/**
+	 * @var string
+	 */
+	protected string $_stream;
+
+	public function __construct(
+		string $_stream,
+		IStreamProperties $_properties
+	) {
+
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	function properties(): IStreamProperties {
+		return $this->_properties;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	function stream(): string {
+		return $this->_stream;
+	}
+}

src/Model/Data/StreamCollection.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Kanopi\Components\Model\Data;
+
+class StreamCollection implements IStreamCollection {
+	/**
+	 * @var IStream
+	 */
+	protected IStream $_stream;
+
+	/**
+	 * @var iterable
+	 */
+	protected iterable $_collection;
+
+	public function __construct(
+		iterable $_collection,
+		IStream $_stream
+	) {
+		$this->_collection = $_collection;
+		$this->_stream     = $_stream;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	function collection(): iterable {
+		return $this->_collection;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	function stream(): IStream {
+		return $this->_stream;
+	}
+}

src/Model/Data/StreamProperties.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace Kanopi\Components\Model\Data;
+
+class StreamProperties implements IStreamProperties {
+	/**
+	 * @var int
+	 */
+	protected int $_lastModifiedTimestamp;
+
+	/**
+	 * @var int
+	 */
+	protected int $_length;
+
+	/**
+	 * @var int
+	 */
+	protected int $_readTimestamp;
+
+	/**
+	 * @var string
+	 */
+	protected string $_uri;
+
+	/**
+	 * @param string $_uri
+	 * @param int    $_lastModifiedTimestamp
+	 * @param int    $_length
+	 * @param int    $_readTimestamp
+	 */
+	public function __construct(
+		string $_uri,
+		int $_lastModifiedTimestamp,
+		int $_length,
+		int $_readTimestamp
+	) {
+		$this->_length                = $_length;
+		$this->_lastModifiedTimestamp = $_lastModifiedTimestamp;
+		$this->_readTimestamp         = $_readTimestamp;
+		$this->_uri                   = $_uri;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	function lastModifiedTimestamp(): int {
+		return $this->_lastModifiedTimestamp;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	function length(): int {
+		return $this->_length;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	function readTimestamp(): int {
+		return $this->_readTimestamp;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	function uri(): string {
+		return $this->_uri;
+	}
+}

src/Repositories/ISetStream.php

@@ -1,21 +1,23 @@
 <?php
 /**
- * Reads an input stream into an iterable set
+ * Reads an input stream into an iterable collection
  */
 
 namespace Kanopi\Components\Repositories;
 
+use Kanopi\Components\Model\Data\IStream;
+use Kanopi\Components\Model\Data\IStreamCollection;
 use Kanopi\Components\Model\Exception\SetStreamException;
 
 interface ISetStream {
 	/**
 	 * Read an input stream value from a requested stream location
 	 *
-	 * @param string $_input_stream
+	 * @param IStream $_input_stream
 	 *
 	 * @throws SetStreamException
 	 *
-	 * @return iterable
+	 * @return IStreamCollection
 	 */
-	function read( string $_input_stream ): iterable;
+	function read( IStream $_input_stream ): IStreamCollection;
 }

src/Repositories/IStreamReader.php

@@ -6,6 +6,7 @@
 namespace Kanopi\Components\Repositories;
 
 use InvalidArgumentException;
+use Kanopi\Components\Model\Data\IStream;
 
 interface IStreamReader {
 	/**
@@ -15,7 +16,7 @@ interface IStreamReader {
 	 *
 	 * @throws InvalidArgumentException
 	 *
-	 * @return string
+	 * @return IStream
 	 */
-	function read( string $_stream_path ): string;
+	function read( string $_stream_path ): IStream;
 }

src/Repositories/JsonSetStream.php

@@ -7,6 +7,9 @@
 
 use ArrayIterator;
 use EmptyIterator;
+use Kanopi\Components\Model\Data\IStream;
+use Kanopi\Components\Model\Data\IStreamCollection;
+use Kanopi\Components\Model\Data\StreamCollection;
 use Kanopi\Components\Model\Exception\SetStreamException;
 
 class JsonSetStream implements ISetStream {
@@ -42,15 +45,15 @@ protected function process( string $_input ): iterable {
 	/**
 	 * @inheritDoc
 	 */
-	public function read( string $_input_stream ): iterable {
-		$output     = $this->process( $_input_stream ?? '' );
+	public function read( IStream $_input_stream ): IStreamCollection {
+		$output     = $this->process( $_input_stream->stream() ?? '' );
 		$error_code = max( 0, json_last_error() );
 
 		if ( 0 < $error_code ) {
 			throw new SetStreamException(
 				self::ERROR_REFERENCE[ $error_code ] ?? "Unknown JSON read error ($error_code)" );
 		}
 
-		return $output;
+		return new StreamCollection( $output, $_input_stream );
 	}
 }

src/Repositories/LocalFileReader.php

@@ -6,21 +6,34 @@
 namespace Kanopi\Components\Repositories;
 
 use InvalidArgumentException;
+use Kanopi\Components\Model\Data\IStream;
+use Kanopi\Components\Model\Data\Stream;
+use Kanopi\Components\Model\Data\StreamProperties;
 
 class LocalFileReader implements IStreamReader {
 	/**
 	 * @inheritDoc
 	 */
-	function read( string $_stream_path ): string {
-		if ( false === file_exists( $_stream_path ) ) {
+	function read( string $_stream_path ): IStream {
+		$lastModifiedTimestamp = filemtime( $_stream_path );
+		if ( false === $lastModifiedTimestamp ) {
 			throw new InvalidArgumentException(
 				"Import file not found at: $_stream_path",
 				'Import file does not exists' );
 		}
 
 		// phpcs:ignore -- File read is intentionally uncached, intended for singular read
 		$contents = file_get_contents( $_stream_path );
+		$readContents = !empty( $contents ) ? $contents : '';
 
-		return !empty( $contents ) ? $contents : '';
+		return new Stream(
+			$readContents,
+			new StreamProperties(
+				$_stream_path,
+				$lastModifiedTimestamp,
+				strlen( $readContents ),
+				time()
+			)
+		);
 	}
 }