Release/v0.5.1

CHANGELOG.md

@@ -5,7 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-# [[v0.5-0](https://github.com/The-FireHub-Project/Runtime/compare/v0.4.3...v0.5.0)] – 2026-11-04
+# [[v0.5.1](https://github.com/The-FireHub-Project/Runtime/compare/v0.5.0...v0.5.1)] – 2026-11-04
+
+### Added
+* Add comprehensive stream utilities in `Runtime` by @dieselxxx
+
+# [[v0.5.0](https://github.com/The-FireHub-Project/Runtime/compare/v0.4.3...v0.5.0)] – 2026-11-04
 
 ### Added
 * Add comprehensive stream utilities in `Runtime` by @dieselxxx

src/Stream/Enum/OpenMode.php

@@ -0,0 +1,168 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Runtime
+ */
+
+namespace FireHub\Runtime\Stream\Enum;
+
+/**
+ * ### Stream Opening Modes
+ *
+ * Defines the supported modes for opening native PHP streams.
+ *
+ * Binary modes are recommended for consistent behavior across platforms.
+ * @since 1.0.0
+ */
+enum OpenMode:string {
+
+    /**
+     * ### Opens a stream for reading only
+     *
+     * The stream must exist. The pointer is positioned at the beginning.
+     * @since 1.0.0
+     */
+    case READ = 'r';
+
+    /**
+     * ### Opens a stream for reading and writing
+     *
+     * The stream must exist. The pointer is positioned at the beginning.
+     * @since 1.0.0
+     */
+    case READ_WRITE = 'r+';
+
+    /**
+     * ### Opens a stream for writing only
+     *
+     * Creates the file if it does not exist or truncates it if it exists.
+     * @since 1.0.0
+     */
+    case WRITE = 'w';
+
+    /**
+     * ### Opens a stream for reading and writing
+     *
+     * Creates the file if it does not exist or truncates it if it exists.
+     * @since 1.0.0
+     */
+    case WRITE_READ = 'w+';
+
+    /**
+     * ### Opens a stream for appending
+     *
+     * Creates the file if it does not exist.
+     * Writes are always performed at the end of the file.
+     * @since 1.0.0
+     */
+    case APPEND = 'a';
+
+    /**
+     * ### Opens a stream for reading and appending
+     *
+     * Creates the file if it does not exist.
+     * Writes are always performed at the end of the file.
+     * @since 1.0.0
+     */
+    case APPEND_READ = 'a+';
+
+    /**
+     * ### Creates a new stream for writing
+     *
+     * Fails if the file already exists.
+     * @since 1.0.0
+     */
+    case CREATE = 'x';
+
+    /**
+     * ### Creates a new stream for reading and writing
+     *
+     * Fails if the file already exists.
+     * @since 1.0.0
+     */
+    case CREATE_READ = 'x+';
+
+    /**
+     * ### Opens a stream for writing without truncation
+     *
+     * Creates the file if it does not exist.
+     * @since 1.0.0
+     */
+    case CREATE_OR_OPEN = 'c';
+
+    /**
+     * ### Opens a stream for reading and writing without truncation
+     *
+     * Creates the file if it does not exist.
+     * @since 1.0.0
+     */
+    case CREATE_OR_OPEN_READ = 'c+';
+
+    /**
+     * ### Opens a binary stream for reading only
+     * @since 1.0.0
+     */
+    case READ_BINARY = 'rb';
+
+    /**
+     * ### Opens a binary stream for reading and writing
+     * @since 1.0.0
+     */
+    case READ_WRITE_BINARY = 'r+b';
+
+    /**
+     * ### Opens a binary stream for writing only
+     * @since 1.0.0
+     */
+    case WRITE_BINARY = 'wb';
+
+    /**
+     * ### Opens a binary stream for reading and writing
+     * @since 1.0.0
+     */
+    case WRITE_READ_BINARY = 'w+b';
+
+    /**
+     * ### Opens a binary stream for appending
+     * @since 1.0.0
+     */
+    case APPEND_BINARY = 'ab';
+
+    /**
+     * ### Opens a binary stream for reading and appending
+     * @since 1.0.0
+     */
+    case APPEND_READ_BINARY = 'a+b';
+
+    /**
+     * ### Creates a new binary stream for writing
+     * @since 1.0.0
+     */
+    case CREATE_BINARY = 'xb';
+
+    /**
+     * ### Creates a new binary stream for reading and writing
+     * @since 1.0.0
+     */
+    case CREATE_READ_BINARY = 'x+b';
+
+    /**
+     * ### Opens a binary stream for writing without truncation
+     * @since 1.0.0
+     */
+    case CREATE_OR_OPEN_BINARY = 'cb';
+
+    /**
+     * ### Opens a binary stream for reading and writing without truncation
+     * @since 1.0.0
+     */
+    case CREATE_OR_OPEN_READ_BINARY = 'c+b';
+
+}

src/Stream/Handle.php

@@ -0,0 +1,73 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.2
+ * @package Runtime
+ */
+
+namespace FireHub\Runtime\Stream;
+
+use FireHub\Core\Boundary\Runtime\NativeRuntime;
+use FireHub\Runtime\Stream\Enum\OpenMode;
+
+use function fopen;
+use function fclose;
+
+/**
+ * ### PHP Runtime Stream Handle Utilities
+ *
+ * Provides low-level wrappers for opening and closing native PHP streams.
+ *
+ * Preserves native PHP stream behavior.
+ * @since 1.0.0
+ */
+final readonly class Handle extends NativeRuntime {
+
+    /**
+     * ### Opens a stream resource
+     * @since 1.0.0
+     *
+     * @param non-empty-string $path <p>
+     * File path or supported stream URI.
+     * </p>
+     * @param \FireHub\Runtime\Stream\Enum\OpenMode $mode [optional] <p>
+     * Stream opening mode.
+     * </p>
+     * @param bool $use_include_path [optional] <p>
+     * Whether to search the configured include path.
+     * </p>
+     * @param null|resource $context [optional] <p>
+     * Stream context resource.
+     * </p>
+     *
+     * @return resource|false Opened stream resource, or false on failure.
+     */
+    public static function open (string $path, OpenMode $mode, bool $use_include_path = false, mixed $context = null):mixed {
+
+        return fopen($path, $mode->value, $use_include_path, $context);
+
+    }
+
+    /**
+     * ### Closes an open stream
+     * @since 1.0.0
+     *
+     * @param resource $stream <p>
+     * Stream resource to close.
+     * </p>
+     *
+     * @return bool True on success, false on failure.
+     */
+    public static function close (mixed $stream):bool {
+
+        return fclose($stream);
+
+    }
+
+}

src/Stream/Lock.php

@@ -0,0 +1,63 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.2
+ * @package Runtime
+ */
+
+namespace FireHub\Runtime\Stream;
+
+use FireHub\Core\Boundary\Runtime\NativeRuntime;
+use FireHub\Core\Type\IO\LockMode;
+
+use function flock;
+
+/**
+ * ### PHP Runtime Stream Lock Utilities
+ *
+ * Provides low-level wrappers for acquiring and releasing advisory locks on native PHP streams.
+ *
+ * Locking behavior depends on the underlying stream wrapper and operating system.
+ * @since 1.0.0
+ */
+final readonly class Lock extends NativeRuntime {
+
+    /**
+     * ### Performs a stream locking operation
+     *
+     * Acquires or releases an advisory lock on a stream.
+     * @since 1.0.0
+     *
+     * @param resource $stream <p>
+     * Stream resource.
+     * </p>
+     * @param \FireHub\Core\Type\IO\LockMode $mode <p>
+     * Locking operation.
+     * </p>
+     * @param bool $non_blocking [optional] <p>
+     * Whether to apply the non-blocking modifier.
+     * </p>
+     * @param null|bool $would_block [optional] <p>
+     * Receives whether the lock attempt would block.
+     * </p>
+     * @param-out int $would_block
+     *
+     * @return bool True on success, false on failure.
+     */
+    public static function operation (mixed $stream, LockMode $mode, bool $non_blocking = false, ?bool &$would_block = null):bool {
+
+        return flock(
+            $stream,
+            $mode->value | ($non_blocking ? LOCK_NB : 0),
+            $would_block
+        );
+
+    }
+
+}

src/Stream/Metadata.php

@@ -15,6 +15,7 @@
 
 use FireHub\Core\Boundary\Runtime\NativeRuntime;
 
+use function fstat;
 use function stream_get_meta_data;
 use function stream_get_transports;
 
@@ -67,4 +68,24 @@ public static function transports ():array {
 
     }
 
+    /**
+     * ### Gets stream resource statistics
+     *
+     * Retrieves information about the resource underlying the stream.
+     *
+     * The returned array may contain a device, inode, mode, size, timestamps, and other filesystem-related information.
+     * @since 1.0.0
+     *
+     * @param resource $stream <p>
+     * Stream resource.
+     * </p>
+     *
+     * @return array<string|int, int>|false Stream statistics, or false on failure.
+     */
+    public static function statistics (mixed $stream):array|false {
+
+        return fstat($stream);
+
+    }
+
 }