From 2625e717455dec44f09d25ca73c58fc2f2019e01 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Danijel=20Gali=C4=87?= Date: Wed, 16 Sep 2026 15:08:47 +0200 Subject: [PATCH 1/2] Add `Binary` class for low-level binary operations and refine array type annotations **Details:** - Introduced `Binary` class in the `Runtime` package for packing and unpacking binary data with FireHub API consistency: - Added static methods `pack` and `unpack`, leveraging PHP's native `pack` and `unpack` functions. - Ensures seamless integration with PHP runtime's binary representation operations. - Includes comprehensive PHPDoc for method parameters, return types, and behaviors. - Refined type annotations in `Arr\Mutation` for enhanced PHPStan type inference: - Adjusted `@phpstan-param-out` array annotations to include `int` as a possible array key (`array`). - Suppressed `@phpstan-ignore paramOut.type` for methods `push` and `unshift` to address static analysis concerns. This update extends FireHub's runtime capabilities with granular binary data utilities while improving type accuracy in array mutation operations. --- CHANGELOG.md | 8 +++++ README.md | 2 +- src/Arr/Mutation.php | 8 ++--- src/Binary.php | 86 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 99 insertions(+), 5 deletions(-) create mode 100644 src/Binary.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 738ba05..b6cfaa1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [[v0.3.1](https://github.com/The-FireHub-Project/Runtime/compare/v0.3.0...v0.3.1)] – 2026-09-16 + +### Added +* Add `Binary` class for low-level binary operations by @dieselxxx + +### Changed +* refine array type annotations by @dieselxxx + ## [[v0.3.0](https://github.com/The-FireHub-Project/Runtime/compare/v0.2.6...v0.3.0)] – 2026-09-16 ### Added diff --git a/README.md b/README.md index 8a4b493..ec20b88 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ /> version diff --git a/src/Arr/Mutation.php b/src/Arr/Mutation.php index 5a0ff92..0a510ab 100644 --- a/src/Arr/Mutation.php +++ b/src/Arr/Mutation.php @@ -74,7 +74,7 @@ public static function pop (array &$array):mixed { * @param TPushedValue ...$values [optional]

* The values to push onto the end of the array. *

- * @phpstan-param-out array $array + * @phpstan-param-out array $array * * @return int The new number of elements in the array. * @@ -83,7 +83,7 @@ public static function pop (array &$array):mixed { */ public static function push (array &$array, mixed ...$values):int { - return array_push($array, ...$values); + return array_push($array, ...$values); // @phpstan-ignore paramOut.type } @@ -133,7 +133,7 @@ public static function shift (array &$array):mixed { * @param TUnshiftValue ...$values [optional]

* The values to prepend. *

- * @phpstan-param-out array $array + * @phpstan-param-out array $array * * @return int The new number of elements in the array. * @@ -141,7 +141,7 @@ public static function shift (array &$array):mixed { */ public static function unshift (array &$array, mixed ...$values):int { - return array_unshift($array, ...$values); + return array_unshift($array, ...$values); // @phpstan-ignore paramOut.type } diff --git a/src/Binary.php b/src/Binary.php new file mode 100644 index 0000000..ba47951 --- /dev/null +++ b/src/Binary.php @@ -0,0 +1,86 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=7.4 + * @package Runtime + */ + +namespace FireHub\Runtime; + +use FireHub\Core\Boundary\Runtime\NativeRuntime; + +use function pack; +use function unpack; + +/** + * ### Binary data operations + * + * Provides low-level operations for packing values into binary strings and unpacking binary strings into values + * according to format definitions supported by the PHP runtime. + * + * Binary acts as a runtime boundary over native binary representation operations, providing a consistent FireHub + * API while preserving the behavior and semantics of the underlying PHP runtime. + * @since 1.0.0 + */ +final class Binary extends NativeRuntime { + + /** + * ### Pack data into a binary string + * + * Packs the specified values into a binary string according to the provided format definition. + * @since 1.0.0 + * + * @see https://www.php.net/manual/en/function.pack.php + * + * @param non-empty-string $format

+ * The format used to pack the values. + *

+ * + * @param mixed ...$values

+ * The values to pack into the binary string. + *

+ * + * @return string Returns a binary string containing data. + */ + public static function pack (string $format, mixed ...$values):string { + + return pack($format, ...$values); + + } + + /** + * ### Unpack data from binary string + * + * Unpacks values from the specified binary string according to the provided format definition. + * @since 1.0.0 + * + * @see https://www.php.net/manual/en/function.unpack.php + * + * @param non-empty-string $format

+ * The format used to unpack the binary data. + *

+ * + * @param string $data

+ * The packed data. + *

+ * + * @param non-negative-int $offset

+ * The offset to begin unpacking from. + *

+ * + * @return array|false Returns an associative array containing unpacked elements of binary + * string, or false on failure. + */ + public static function unpack (string $format, string $data, int $offset = 0):array|false { + + return unpack($format, $data, $offset); + + } + +} \ No newline at end of file From 03d080334d7a792b5dd49f309e14a9c1ec080b0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Danijel=20Gali=C4=87?= <56673130+dieselxxx@users.noreply.github.com> Date: Wed, 16 Sep 2026 15:10:06 +0200 Subject: [PATCH 2/2] Update README.md --- README.md | 111 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 70 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index ec20b88..f266bbe 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ PHP Runtime Foundation
 release @@ -22,25 +22,46 @@ /> -[![PHPStan](https://github.com/The-FireHub-Project/Runtime/actions/workflows/PHPStan.yml/badge.svg?branch=develop)](https://github.com/The-FireHub-Project/Runtime/actions/workflows/PHPStan.yml) -[![PHPUnit](https://github.com/The-FireHub-Project/Runtime/actions/workflows/PHPUnit.yml/badge.svg?branch=develop)](https://github.com/The-FireHub-Project/Runtime/actions/workflows/PHPUnit.yml) -[![Codecov](https://codecov.io/gh/The-FireHub-Project/Runtime/branch/develop/graph/badge.svg?token=XW2YEONF51)](https://app.codecov.io/gh/The-FireHub-Project/Runtime/tree/develop) -

- + + GitHub created at + GitHub last commit (branch) - + GitHub activity (branch) - + + GitHub contributors + GitHub commit difference between two branches + + GitHub top language + + GitHub repo size + + GitHub code size

@@ -54,47 +75,55 @@ Its role is to provide a consistent execution foundation between native PHP capa --- -## FireHub Icon Development Branch +## FireHub Icon Repository Purpose -⚠️ **This is the `develop` branch** +This repository provides a lightweight PHP runtime abstraction layer that wraps native PHP functionality into clean, consistent, and deterministic APIs. -- Unstable -- APIs may change without notice -- Not intended for production use +Its purpose is to reduce boilerplate and standardize common execution patterns across the FireHub ecosystem by offering ergonomic helper classes for arrays, strings, files, environment access, and other low-level runtime operations. -## FireHub Icon Branch Purpose +It is strictly focused on execution-level concerns and does not contain domain logic, business rules, or framework-level orchestration. It exists to improve developer productivity while preserving native PHP behavior and ensuring zero framework coupling. -The `develop` branch is the **primary integration branch** for all ongoing development. +## FireHub Icon Security -It serves as the staging area where: -- Feature branches are merged -- Bug fixes are integrated -- Experimental work is stabilized -- Code is prepared for upcoming releases +For security reporting and guidelines, please refer to our [SECURITY.md](https://github.com/The-FireHub-Project/.github/blob/master/.github/SECURITY.md) file. -All **release branches** are created **from `develop`**. +## FireHub Icon Community -## Stability Guarantee +![GitHub watchers](https://img.shields.io/github/watchers/The-FireHub-Project/Runtime?style=social) +![GitHub Repo stars](https://img.shields.io/github/stars/The-FireHub-Project/Runtime?style=social) +![GitHub forks](https://img.shields.io/github/forks/The-FireHub-Project/Runtime?style=social) -❌ No backward compatibility guarantee -❌ APIs may change without notice -❌ Behavior may be incomplete or inconsistent -❌ Breaking changes are expected +- Be sure to review the [Code of Conduct](https://github.com/The-FireHub-Project/.github/blob/master/.github/CODE_OF_CONDUCT.md). +- Read a [Contributing](https://github.com/The-FireHub-Project/.github/blob/master/.github/CONTRIBUTING.md) file to see how you can contribute to this project. +- Read our [Security policy](https://github.com/The-FireHub-Project/.github/blob/master/.github/SECURITY.md) file to see how you can report a vulnerability. +- Review the project [Governance model](https://github.com/The-FireHub-Project/.github/blob/master/.github/GOVERNANCE.md), including roles, decision-making, RFC process, and releases. -This branch is intended **only for contributors and advanced testers**. +## FireHub Icon Support -## FireHub Icon Composer Usage (Not Recommended) +

+ + GitHub in-progress issues + + GitHub total issues + + GitHub opened pull requests +

-For internal testing only: +For help with FireHub products, please refer to the following resources: -```json -{ - "require": { - "the-firehub-project/runtime": "dev-develop" - } -} -``` -⚠️ Never use dev-develop in production. +- **General questions & discussions**: [GitHub Discussions](https://github.com/orgs/The-FireHub-Project/discussions) +- **Bug reports & issues**: [Support](https://github.com/The-FireHub-Project/Runtime/issues) +- **Documentation & guides**: [FireHub Docs](https://the-firehub-project.github.io) +- **Commercial support** (Pro/Enterprise): contact your account manager ## FireHub Icon Authors and Contributors