@@ -22,25 +22,46 @@
/>
-[](https://github.com/The-FireHub-Project/Runtime/actions/workflows/PHPStan.yml)
-[](https://github.com/The-FireHub-Project/Runtime/actions/workflows/PHPUnit.yml)
-[](https://app.codecov.io/gh/The-FireHub-Project/Runtime/tree/develop)
-
-
+
+ 
&labelColor=31373e)
&labelColor=31373e)
Development Branch
+## 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.
-## 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.
+## 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`**.
+## Community
-## Stability Guarantee
+
+
+
-❌ 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**.
+## Support
-## Composer Usage (Not Recommended)
+
-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
## Authors and Contributors
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( [ '.', '..',
