From 7cfc7aa9a3e664f1a525f82fa151667daee82d31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Danijel=20Gali=C4=87?= Date: Mon, 31 Aug 2026 12:27:35 +0200 Subject: [PATCH 1/3] Refine PHPDoc return types across `Decimal` operations for enhanced type safety **Details:** - Updated multiple methods across `DecimalEngine`, `Arithmetic`, `Divide`, `Multiply`, and `Round` to use `numeric-string` return type in PHPDoc annotations. - Added `@var` annotations to enforce `numeric-string` type for intermediate variables and return values. - Suppressed false-positive errors in PHPStan with `@phpstan-ignore` on return types where static analysis mismatches occurred. - Improved inline documentation to ensure clarity and better IDE support. - Adjusted test assertions, replacing `assertSame` with `assertEqualsCanonicalizing` for flexible comparison in folder tests. This revision bolsters type accuracy while maintaining code clarity, paving the way for greater confidence in future static analysis and IDE integration. --- CHANGELOG.md | 5 +++++ src/Math/Decimal/Arithmetic.php | 17 +++++++++------- src/Math/Decimal/Divide.php | 30 +++++++++++++++------------- src/Math/Decimal/Multiply.php | 7 ++++--- src/Math/Decimal/Round.php | 7 ++++--- src/Math/DecimalEngine.php | 8 +++++--- tests/Unit/FileSystem/FolderTest.php | 2 +- 7 files changed, 45 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6173595..87e6bb6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [[v0.2.1](https://github.com/The-FireHub-Project/Runtime/compare/v0.2.0...v0.2.1)] – 2026-08-31 + +### Added +* Improved PHP docs by @dieselxxx + ## [[v0.2.0](https://github.com/The-FireHub-Project/Runtime/compare/v0.1.5...v0.2.0)] – 2026-08-31 ### Added diff --git a/src/Math/Decimal/Arithmetic.php b/src/Math/Decimal/Arithmetic.php index 13003b4..73914c9 100644 --- a/src/Math/Decimal/Arithmetic.php +++ b/src/Math/Decimal/Arithmetic.php @@ -40,7 +40,7 @@ trait Arithmetic { * * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If either decimal value is not a valid decimal number. * - * @return string The sum of the two decimal values. + * @return numeric-string The sum of the two decimal values. */ public static function add (string $left, string $right):string { @@ -56,7 +56,8 @@ public static function add (string $left, string $right):string { $right_fraction ); - return $left_sign === '-' && $result !== '0' + /** @var numeric-string $result */ + return $left_sign === '-' && $result !== '0' // @phpstan-ignore return.type ? '-'.$result : $result; @@ -80,7 +81,8 @@ public static function add (string $left, string $right):string { $right_fraction ); - return $left_sign === '-' && $result !== '0' + /** @var numeric-string $result */ + return $left_sign === '-' && $result !== '0' // @phpstan-ignore return.type ? '-'.$result : $result; @@ -93,7 +95,8 @@ public static function add (string $left, string $right):string { $left_fraction ); - return $right_sign === '-' && $result !== '0' + /** @var numeric-string $result */ + return $right_sign === '-' && $result !== '0' // @phpstan-ignore return.type ? '-'.$result : $result; @@ -116,7 +119,7 @@ public static function add (string $left, string $right):string { * * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If either decimal value is not a valid decimal number. * - * @return string The difference between the two decimal values. + * @return numeric-string The difference between the two decimal values. */ public static function subtract (string $left, string $right):string { @@ -157,7 +160,7 @@ public static function subtract (string $left, string $right):string { * * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number. * - * @return string The sum of the two positive decimal values. + * @return numeric-string The sum of the two positive decimal values. */ private static function addPositive (string $left_integer, string $left_fraction, string $right_integer, string $right_fraction):string { @@ -227,7 +230,7 @@ private static function addPositive (string $left_integer, string $left_fraction * * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number. * - * @return string The difference between the two positive decimal values. + * @return numeric-string The difference between the two positive decimal values. */ private static function subtractPositive (string $left_integer, string $left_fraction, string $right_integer, string $right_fraction):string { diff --git a/src/Math/Decimal/Divide.php b/src/Math/Decimal/Divide.php index ffdc7e1..fe38fd1 100644 --- a/src/Math/Decimal/Divide.php +++ b/src/Math/Decimal/Divide.php @@ -26,6 +26,11 @@ trait Divide { /** * ### Divides one decimal value by another + * @since 1.0.0 + * + * @uses \FireHub\Runtime\Math\DecimalEngine::normalize() To normalize the decimal values. + * @uses \FireHub\Runtime\Math\DecimalEngine::dividePositive() To divide the positive decimal values. + * * @param non-empty-string $left

* The dividend. *

@@ -36,15 +41,11 @@ trait Divide { * The number of decimal places to calculate. *

* - * @return string The quotient of the two decimal values. - *@throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If either decimal value is invalid. + * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If either decimal value is invalid. * @throws \FireHub\Runtime\Exception\InvalidScaleNumberException If the scale is less than zero. * @throws DivisionByZeroError If the divisor is zero. * - * @since 1.0.0 - * - * @uses \FireHub\Runtime\Math\DecimalEngine::normalize() To normalize the decimal values. - * @uses \FireHub\Runtime\Math\DecimalEngine::dividePositive() To divide the positive decimal values. + * @return numeric-string The quotient of the two decimal values. * */ public static function divide (string $left, string $right, int $scale = 18):string { @@ -55,11 +56,9 @@ public static function divide (string $left, string $right, int $scale = 18):str if ($scale < 0) throw new InvalidScaleNumberException('Scale must be greater than or equal to zero.'); - if ($right_integer === '0' && $right_fraction === '') - throw new DivisionByZeroError; + if ($right_integer === '0' && $right_fraction === '') throw new DivisionByZeroError; - if ($left_integer === '0' && $left_fraction === '') - return '0'; + if ($left_integer === '0' && $left_fraction === '') return '0'; $result = self::dividePositive( $left_integer, @@ -69,7 +68,8 @@ public static function divide (string $left, string $right, int $scale = 18):str $scale ); - if ($left_sign !== $right_sign && $result !== '0') return '-'.$result; + /** @var numeric-string $result */ + if ($left_sign !== $right_sign && $result !== '0') return '-'.$result; // @phpstan-ignore return.type return $result; @@ -105,7 +105,7 @@ public static function divide (string $left, string $right, int $scale = 18):str * * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number. * - * @return string The quotient. + * @return numeric-string The quotient. */ private static function dividePositive (string $left_integer, string $left_fraction, string $right_integer, string $right_fraction, int $scale):string { @@ -162,7 +162,8 @@ private static function dividePositive (string $left_integer, string $left_fract } - $quotient = Runtime\Str\SB\Transform::trim($quotient, Side::LEFT, '0') ?: '0'; + /** @var numeric-string $quotient */ + $quotient = Runtime\Str\SB\Transform::trim($quotient, Side::LEFT, '0') ?: '0'; // @phpstan-ignore varTag.nativeType $fraction = ''; for ($i = 0; $i < $scale; ++$i) { @@ -200,7 +201,8 @@ private static function dividePositive (string $left_integer, string $left_fract if ($fraction === '') return $quotient; - return $quotient.'.'.$fraction; + /** @var numeric-string */ + return $quotient.'.'.$fraction; // @phpstan-ignore varTag.nativeType } diff --git a/src/Math/Decimal/Multiply.php b/src/Math/Decimal/Multiply.php index a944eba..ba39222 100644 --- a/src/Math/Decimal/Multiply.php +++ b/src/Math/Decimal/Multiply.php @@ -39,7 +39,7 @@ trait Multiply { * * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If either decimal value is not a valid decimal number. * - * @return string The product of the two decimal values. + * @return numeric-string The product of the two decimal values. */ public static function multiply (string $left, string $right):string { @@ -57,7 +57,8 @@ public static function multiply (string $left, string $right):string { $right_fraction ); - if ($left_sign !== $right_sign && $result !== '0') return '-'.$result; + /** @var numeric-string $result */ + if ($left_sign !== $right_sign && $result !== '0') return '-'.$result; // @phpstan-ignore return.type return $result; @@ -89,7 +90,7 @@ public static function multiply (string $left, string $right):string { * * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number. * - * @return string The product of the two positive decimal values. + * @return numeric-string The product of the two positive decimal values. */ private static function multiplyPositive (string $left_integer, string $left_fraction, string $right_integer, string $right_fraction):string { diff --git a/src/Math/Decimal/Round.php b/src/Math/Decimal/Round.php index 3839864..9b1031a 100644 --- a/src/Math/Decimal/Round.php +++ b/src/Math/Decimal/Round.php @@ -48,7 +48,7 @@ trait Round { * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number. * @throws \FireHub\Runtime\Exception\InvalidPrecisionException If the precision is less than zero. * - * @return string The rounded decimal value. + * @return numeric-string The rounded decimal value. */ public static function round (string $value, int $precision = 0, RoundMode $mode = RoundMode::HALF_AWAY_FROM_ZERO):string { @@ -57,7 +57,7 @@ public static function round (string $value, int $precision = 0, RoundMode $mode if ($precision < 0) throw new InvalidPrecisionException('Precision must be greater than or equal to zero.'); if (Runtime\Str\SB\Inspection::length($fraction) <= $precision) - return $sign === '-' && ($integer !== '0' || $fraction !== '') + return $sign === '-' && ($integer !== '0' || $fraction !== '') // @phpstan-ignore return.type ? '-'.$integer.($fraction !== '' ? '.'.$fraction : '') : $integer.($fraction !== '' ? '.'.$fraction : ''); @@ -97,7 +97,8 @@ public static function round (string $value, int $precision = 0, RoundMode $mode } else $result = $integer; - return $sign === '-' && $result !== '0' + /** @var numeric-string $result */ + return $sign === '-' && $result !== '0' // @phpstan-ignore return.type ? '-'.$result : $result; diff --git a/src/Math/DecimalEngine.php b/src/Math/DecimalEngine.php index fb909ed..dbd13fb 100644 --- a/src/Math/DecimalEngine.php +++ b/src/Math/DecimalEngine.php @@ -108,7 +108,7 @@ private static function comparePositive (string $left_integer, string $left_frac * * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number. * - * @return array{'+'|'-', non-empty-string, string} Returns the sign, normalized integer part, and normalized + * @return array{'+'|'-', numeric-string, string} Returns the sign, normalized integer part, and normalized * fractional part. */ private static function normalize (string $value):array { @@ -136,6 +136,7 @@ private static function normalize (string $value):array { if ($integer === '0' && $fraction === '') return ['+', '0', '']; + /** @var array{'+'|'-', numeric-string, string} */ return [$sign, $integer, $fraction]; } @@ -159,7 +160,7 @@ private static function normalize (string $value):array { * * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number. * - * @return string The normalized decimal result. + * @return numeric-string The normalized decimal result. */ private static function normalizeResult (string $value, int $scale):string { @@ -173,7 +174,8 @@ private static function normalizeResult (string $value, int $scale):string { .'.' .Runtime\Str\SB\Access::part($value, $position); - return self::normalize($value)[1] + /** @var numeric-string */ + return self::normalize($value)[1] // @phpstan-ignore varTag.type .(self::normalize($value)[2] !== '' ? '.'.self::normalize($value)[2] : '' diff --git a/tests/Unit/FileSystem/FolderTest.php b/tests/Unit/FileSystem/FolderTest.php index e0271e0..8dc08c3 100644 --- a/tests/Unit/FileSystem/FolderTest.php +++ b/tests/Unit/FileSystem/FolderTest.php @@ -156,7 +156,7 @@ public function testMatch (PathSearchFlag ...$flags):void { #[DependsExternal(FileTest::class, 'testPutContent')] public function testList (?Order $order = null):void { - self::assertSame( + self::assertEqualsCanonicalizing( [ '.', '..', From 096f84155211aa553c061b751cf3f6ac3793257a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Danijel=20Gali=C4=87?= <56673130+dieselxxx@users.noreply.github.com> Date: Mon, 31 Aug 2026 12:28:08 +0200 Subject: [PATCH 2/3] Update version badge from 0.2.0 to 0.2.1 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 67855ce..6552d30 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ /> version From 22e0bd552c69e3d9310a21e881b91703cf57603f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Danijel=20Gali=C4=87?= <56673130+dieselxxx@users.noreply.github.com> Date: Mon, 31 Aug 2026 12:28:56 +0200 Subject: [PATCH 3/3] Update README.md --- README.md | 111 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 70 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 6552d30..e752e81 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

@@ -52,47 +73,55 @@ It contains no domain logic, no business rules, and no framework coupling. Its r --- -## 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