@@ -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/Encoding.php b/src/Encoding.php
new file mode 100644
index 0000000..39c3731
--- /dev/null
+++ b/src/Encoding.php
@@ -0,0 +1,164 @@
+
+ * @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;
+
+use FireHub\Core\Boundary\Runtime\NativeRuntime;
+
+use function base64_encode;
+use function base64_decode;
+use function bin2hex;
+use function hex2bin;
+use function quoted_printable_encode;
+use function quoted_printable_decode;
+use function convert_uuencode;
+use function convert_uudecode;
+
+/**
+ * ### Binary-to-text encoding runtime utilities
+ *
+ * Provides direct wrappers around PHP's native binary-to-text encoding and decoding functions, preserving their
+ * native return values.
+ * @since 1.0.0
+ */
+final readonly class Encoding extends NativeRuntime {
+
+ /**
+ * ### Encode data using Base64
+ * @since 1.0.0
+ *
+ * @param string $data + * Data to encode. + *
+ * + * @return string Base64-encoded data. + */ + public static function base64Encode (string $data):string { + + return base64_encode($data); + + } + + /** + * ### Decode Base64-encoded data + * @since 1.0.0 + * + * @param string $data+ * Encoded data. + *
+ * + * @return string|false Decoded data, or false on failure. + */ + public static function base64Decode (string $data):string|false { + + return base64_decode($data, true); + + } + + /** + * ### Encode binary data as hexadecimal + * @since 1.0.0 + * + * @param string $data+ * Binary data. + *
+ * + * @return string Hexadecimal representation. + */ + public static function hexEncode (string $data):string { + + return bin2hex($data); + + } + + /** + * ### Decode hexadecimal data + * @since 1.0.0 + * + * @param string $data+ * Hexadecimal representation. + *
+ * + * @return string|false Decoded data, or false on invalid input. + */ + public static function hexDecode (string $data):string|false { + + return hex2bin($data); + + } + + /** + * ### Encode data using quoted-printable + * @since 1.0.0 + * + * @param string $data+ * Data to encode. + *
+ * + * @return string Quoted-printable encoded data. + */ + public static function quotedPrintableEncode (string $data):string { + + return quoted_printable_encode($data); + + } + + /** + * ### Decode quoted-printable data + * @since 1.0.0 + * + * @param string $data+ * Encoded data. + *
+ * + * @return string Decoded data. + */ + public static function quotedPrintableDecode (string $data):string { + + return quoted_printable_decode($data); + + } + + /** + * ### Encode data using uuencoding + * @since 1.0.0 + * + * @param string $data+ * Data to encode. + *
+ * + * @return string Uuencoded data. + */ + public static function uuEncode (string $data):string { + + return convert_uuencode($data); + + } + + /** + * ### Decode uuencoded data + * @since 1.0.0 + * + * @param string $data+ * Encoded data. + *
+ * + * @return string|false Decoded data, or false on failure. + */ + public static function uuDecode (string $data):string|false { + + return convert_uudecode($data); + + } + +} diff --git a/tests/Unit/EncodingTest.php b/tests/Unit/EncodingTest.php new file mode 100644 index 0000000..ebb066d --- /dev/null +++ b/tests/Unit/EncodingTest.php @@ -0,0 +1,159 @@ + + * @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\Tests + */ + +namespace FireHub\Tests\Runtime\Unit; + +use FireHub\Testing\FireHubTestCase; +use FireHub\Runtime\Encoding; +use PHPUnit\Framework\Attributes\ { + CoversClass, DataProviderExternal, Depends, Group, Small, TestWith +}; + +/** + * ### Test binary-to-text encoding runtime utilities + * @since 1.0.0 + */ +#[Small] +#[Group('src')] +#[CoversClass(Encoding::class)] +final class EncodingTest extends FireHubTestCase { + + /** + * @since 1.0.0 + * + * @param string $expected + * @param string $data + * + * @return void + */ + #[TestWith(['', ''])] + #[TestWith(['ZmlyZWh1Yg==', 'firehub'])] + #[TestWith(['AP8=', "\x00\xFF"])] + public function testBase64Encode (string $expected, string $data):void { + + self::assertSame($expected, Encoding::base64Encode($data)); + + } + + /** + * @since 1.0.0 + * + * @param string $expected + * @param string $data + * + * @return void + */ + #[TestWith(['', ''])] + #[TestWith(['firehub', 'ZmlyZWh1Yg=='])] + #[TestWith(["\x00\xFF", 'AP8='])] + public function testBase64Decode (string $expected, string $data):void { + + self::assertSame($expected, Encoding::base64Decode($data)); + + } + + /** + * @since 1.0.0 + * + * @return void + */ + public function testBase64DecodeStrictness ():void { + + self::assertFalse(Encoding::base64Decode('Zmly!ZWh1Yg==')); + + } + + /** + * @since 1.0.0 + * + * @param string $expected + * @param string $data + * + * @return void + */ + #[TestWith(['', ''])] + #[TestWith(['66697265687562', 'firehub'])] + #[TestWith(['00ff', "\x00\xFF"])] + public function testHexEncode (string $expected, string $data):void { + + self::assertSame($expected, Encoding::hexEncode($data)); + + } + + /** + * @since 1.0.0 + * + * @param string $expected + * @param string $data + * + * @return void + */ + #[TestWith(['', ''])] + #[TestWith(['firehub', '66697265687562'])] + #[TestWith(["\x00\xFF", '00FF'])] + public function testHexDecode (string $expected, string $data):void { + + self::assertSame($expected, Encoding::hexDecode($data)); + + } + + /** + * @since 1.0.0 + * + * @param string $expected + * @param string $data + * + * @return void + */ + #[TestWith(['firehub', 'firehub'])] + #[TestWith(['=00=FF', "\x00\xFF"])] + public function testQuotedPrintableEncode (string $expected, string $data):void { + + self::assertSame($expected, Encoding::quotedPrintableEncode($data)); + + } + + /** + * @since 1.0.0 + * + * @param string $expected + * @param string $data + * + * @return void + */ + #[TestWith(['firehub', 'firehub'])] + #[TestWith(["\x00\xFF", '=00=FF'])] + #[TestWith(['Hello World', "Hello=\r\n World"])] + public function testQuotedPrintableDecode (string $expected, string $data):void { + + self::assertSame($expected, Encoding::quotedPrintableDecode($data)); + + } + + /** + * @since 1.0.0 + * + * @return void + */ + public function testUuEncodeDecode ():void { + + $data = "FireHub\x00\xFF"; + + $encoded = Encoding::uuEncode($data); + + self::assertSame(convert_uuencode($data), $encoded); + self::assertSame($data, Encoding::uuDecode($encoded)); + + } + +} \ No newline at end of file
