From 2bd95e05f16f642a3b1bffa5da1edc7d00a7497e Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 28 Jul 2026 13:28:52 +0200 Subject: [PATCH 1/7] Update README to reflect `architecture/foundation-support` branch and introduce Core/Foundation concepts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Details:** - Updated all badge links, URLs, and branch references in `README.md` to align with the new `architecture/foundation-support` branch. - Introduced detailed descriptions of Core/Foundation architectural layers, including dependency direction and separation of development responsibilities (Core → Foundation → Runtime). - Added milestones and pull request metadata to improve visibility of ongoing development efforts. - Expanded documentation to clarify goals for the Core layer: define stable architectural contracts while delegating developer-facing APIs to the Foundation layer. - Removed outdated or redundant sections for improved clarity and relevance. This update improves the consistency, readability, and alignment of the README with the FireHub project's evolving architecture and development practices. --- README.md | 121 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 86 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index a734470..44b5a2c 100644 --- a/README.md +++ b/README.md @@ -22,24 +22,24 @@ /> -[![PHPStan](https://github.com/The-FireHub-Project/Core-Standard/actions/workflows/PHPStan.yml/badge.svg?branch=develop)](https://github.com/The-FireHub-Project/Core-Standard/actions/workflows/PHPStan.yml) -[![PHPUnit](https://github.com/The-FireHub-Project/Core-Standard/actions/workflows/PHPUnit.yml/badge.svg?branch=develop)](https://github.com/The-FireHub-Project/Core-Standard/actions/workflows/PHPUnit.yml) -[![Codecov](https://codecov.io/gh/The-FireHub-Project/Core-Standard/branch/develop/graph/badge.svg?token=XW2YEONF51)](https://app.codecov.io/gh/The-FireHub-Project/Core-Standard/tree/develop) +[![PHPStan](https://github.com/The-FireHub-Project/Core-Standard/actions/workflows/PHPStan.yml/badge.svg?branch=architecture%2Ferror-exception-base)](https://github.com/The-FireHub-Project/Core-Standard/actions/workflows/PHPStan.yml) +[![PHPUnit](https://github.com/The-FireHub-Project/Core-Standard/actions/workflows/PHPUnit.yml/badge.svg?branch=architecture%2Ferror-exception-base)](https://github.com/The-FireHub-Project/Core-Standard/actions/workflows/PHPUnit.yml) +[![Codecov](https://codecov.io/gh/The-FireHub-Project/Core-Standard/branch/architecture%2Ferror-exception-base/graph/badge.svg?token=XW2YEONF51)](https://app.codecov.io/gh/The-FireHub-Project/Core-Standard/tree/architecture%2Ferror-exception-base)

- + GitHub last commit (branch) - + GitHub activity (branch) - + GitHub commit difference between two branches

@@ -49,47 +49,98 @@ Standard provides the base classes, kernel, domain layer, and minimal runtime ut --- -## FireHub Icon Development Branch +## FireHub Icon Foundation Support – Development Branch -⚠️ **This is the `develop` branch** +⚠️ **This is the `development` branch** - Unstable - APIs may change without notice - Not intended for production use +### Related + +- Milestone: **Development v1** +- Target Release: **v0.0.0** +- Repository: FireHub Core Standard + +### Pull request + +

+ + GitHub pull request title + + GitHub pull request author + + GitHub pull request created + + GitHub pull request comments +

+ +### Milestone + +

+ + GitHub milestone details +

+ ## FireHub Icon Branch Purpose -The `develop` branch is the **primary integration branch** for all ongoing development. +Define and introduce the Core architectural contracts required to support the FireHub Foundation layer. + +This branch establishes the contract boundary between Core and Foundation by introducing minimal, implementation-independent abstractions that allow high-level APIs to be built without violating dependency direction. + +The purpose is to prepare Core for future Foundation components such as Str, DateTime, Uuid, Uri, Path, and other developer-facing APIs. + +## FireHub Icon Architectural Goal + +Establish a clear architectural separation between contracts, execution logic, and high-level developer APIs. + +The goal is to ensure that: + +- Core remains the single source of architectural truth. +- Foundation provides high-level object-oriented implementations. +- Runtime remains responsible only for low-level execution. +- Applications consume expressive APIs without depending on internal implementation details. + +This branch defines the dependency model: -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 +Core +↓ +Foundation +↓ +Runtime -All **release branches** are created **from `develop`**. +where Core defines contracts, Foundation implements developer APIs, and Runtime provides execution primitives. -## Stability Guarantee +## FireHub Icon Core Concept -❌ No backward compatibility guarantee -❌ APIs may change without notice -❌ Behavior may be incomplete or inconsistent -❌ Breaking changes are expected +Introduce minimal Core contracts for fundamental high-level abstractions while keeping implementation details outside the Core layer. -This branch is intended **only for contributors and advanced testers**. +Core contracts represent stable architectural concepts and define only the behavior required by the ecosystem. -## FireHub Icon Composer Usage (Not Recommended) +Foundation implementations provide the complete developer experience through: -For internal testing only: +- Object-oriented APIs +- Immutable value-based objects where applicable +- Fluent interfaces +- Rich domain-oriented operations -```json -{ - "require": { - "the-firehub-project/core-standard": "dev-develop" - } -} -``` -⚠️ Never use dev-develop in production. +The Core layer defines what an abstraction is, while Foundation defines how developers use it. ## FireHub Icon Authors and Contributors @@ -106,4 +157,4 @@ Architecture guidelines, design principles, and ecosystem documentation are avai This software is licensed under the Apache-2.0 License. -For more details, read the full license [here](./LICENSE). +For more details, read the full license [here](./LICENSE). \ No newline at end of file From 5740ed409deeadba7bb98f8aa8222e68fd9060e7 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 28 Jul 2026 15:19:51 +0200 Subject: [PATCH 2/7] Add `Str` base value object type for immutable string semantics **Details:** - Introduced an abstract `Str` class in `Core-Standard/src/Type/Str.php` to define the foundational string-based Value Object type within the FireHub ecosystem. - Implements immutable string value semantics while serving as the base for domain-specific string extensions in higher-level layers (e.g., Foundation). - Provides a clear contract for string handling with its abstract `value(): string` method. - Aligns with the Core layer's goal of ensuring stable architectural contracts and PHP compatibility (`>=8.2`). This addition enhances the modularity and type safety of Core string operations, ensuring future extensibility and clear separation of responsibilities. --- src/Type/Str.php | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 src/Type/Str.php diff --git a/src/Type/Str.php b/src/Type/Str.php new file mode 100644 index 0000000..2947e19 --- /dev/null +++ b/src/Type/Str.php @@ -0,0 +1,41 @@ + + * @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 Core + */ + +namespace FireHub\Core\Type; + +/** + * ### Defines the base string Value Object type within the FireHub ecosystem + * + * This abstract class represents the foundation for all string-based Value Objects. + * + * It provides immutable string value semantics while allowing concrete implementations to extend the type with + * high-level string operations and domain-specific behavior. + * + * The class keeps the Core layer focused on defining the string value contract, while concrete implementations + * belong to higher-level layers such as Foundation. + * @since 1.0.0 + * + * @template TValue of string + * + * @extends \FireHub\Core\Type\ValueObject + */ +abstract readonly class Str extends ValueObject { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():string; + +} \ No newline at end of file From 1f4b519345b78a84f7280db7656d18d796a9c7de Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 30 Jul 2026 09:43:42 +0200 Subject: [PATCH 3/7] Enhance `ValueObject` comparison semantics and extend `Str` class with encoding support **Details:** - Added `Str::encoding()` and `Str::withEncoding()` methods in `Core-Standard/src/Type/Str.php` to provide string encoding introspection and mutation via an `Encoding` value object. Improves versatility for handling internationalization and character encoding scenarios. - Updated `ValueObject::equals()` in `Core-Standard/src/Type/ValueObject.php` to utilize `comparisonValue()` for equality checks, ensuring consistency in comparison logic across all Value Object subclasses. - Introduced protected `comparisonValue()` method in `ValueObject` to centralize comparison logic by delegating to the underlying value representation. - Adjusted `@uses` annotations in `ValueObject` doc comments for better clarity and alignment with new comparison logic. These updates enhance both the flexibility of the `Str` class for encoding management and the reliability of `ValueObject` comparison semantics, contributing to a more robust Core layer architecture. --- src/Type/Str.php | 22 ++++++++++++++++++++++ src/Type/ValueObject.php | 18 ++++++++++++++++-- 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/src/Type/Str.php b/src/Type/Str.php index 2947e19..b4357f5 100644 --- a/src/Type/Str.php +++ b/src/Type/Str.php @@ -13,6 +13,8 @@ namespace FireHub\Core\Type; +use FireHub\Core\Type\Str\Encoding; + /** * ### Defines the base string Value Object type within the FireHub ecosystem * @@ -38,4 +40,24 @@ */ abstract public function value ():string; + /** + * ### Returns the encoding of the string + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Str\Encoding The encoding of the string. + */ + abstract public function encoding ():Encoding; + + /** + * ### Returns a new instance with the specified encoding + * @since 1.0.0 + * + * @param \FireHub\Core\Type\Str\Encoding $encoding

+ * The encoding to set. + *

+ * + * @return static The new instance with provided encoding. + */ + abstract public function withEncoding (Encoding $encoding):static; + } \ No newline at end of file diff --git a/src/Type/ValueObject.php b/src/Type/ValueObject.php index ab375b0..67d7cb7 100644 --- a/src/Type/ValueObject.php +++ b/src/Type/ValueObject.php @@ -49,7 +49,7 @@ abstract public function value ():mixed; * class comparison and value equality semantics. * @since 1.0.0 * - * @uses \FireHub\Core\Type\ValueObject::value() To compare the VO values. + * @uses \FireHub\Core\Type\ValueObject::comparisonValue() To get the comparison value. * @uses \FireHub\Core\Type\ValueObject::sameAs() To compare the VO types. * * @param self $other

@@ -61,7 +61,7 @@ abstract public function value ():mixed; final public function equals (self $other):bool { return $this->sameAs($other) - && $this->value() === $other->value(); + && $this->comparisonValue() === $other->comparisonValue(); } @@ -83,6 +83,20 @@ final public function sameAs (self $other):bool { } + /** + * ### Returns the value to be used for comparison operations + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\ValueObject::value() To get the value. + * + * @return mixed The value to be compared. + */ + protected function comparisonValue ():mixed { + + return $this->value(); + + } + /** * ### Enforces an invariant condition for the Value Object * @since 1.0.0 From b22d9b00018081cc5b3780eaa59b351fae5787fe Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 7 Aug 2026 08:32:46 +0200 Subject: [PATCH 4/7] Implement `Stringable` support in `Str` and add `__toString()` method **Details:** - Extended `Str` base Value Object to implement PHP's native `Stringable` interface, ensuring compatibility with type hints requiring `Stringable` in PHP `>=8.0`. - Introduced the `__toString()` method in `Str` to provide a native string representation of its value. This method utilizes `value()` for consistent output. - Updated class imports and doc comments to reflect the addition of the `Stringable` dependency and enhanced functionality. These changes enhance the interoperability of the `Str` class with both internal and external PHP components, improving compatibility and usability within the FireHub ecosystem. --- src/Type/Str.php | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/src/Type/Str.php b/src/Type/Str.php index b4357f5..08d5f5f 100644 --- a/src/Type/Str.php +++ b/src/Type/Str.php @@ -14,6 +14,7 @@ namespace FireHub\Core\Type; use FireHub\Core\Type\Str\Encoding; +use Stringable; /** * ### Defines the base string Value Object type within the FireHub ecosystem @@ -31,7 +32,7 @@ * * @extends \FireHub\Core\Type\ValueObject */ -abstract readonly class Str extends ValueObject { +abstract readonly class Str extends ValueObject implements Stringable { /** * @inheritDoc @@ -60,4 +61,20 @@ abstract public function encoding ():Encoding; */ abstract public function withEncoding (Encoding $encoding):static; + /** + * ### Returns the string representation of the value + * + * Provides the native PHP string representation of the Value Object. + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\ValueObject::value() To get the string value. + * + * @return TValue The string representation of the value. + */ + public function __toString ():string { + + return $this->value(); + + } + } \ No newline at end of file From 5af01f3e67248bec69dd834dd613041136099e8b Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 7 Aug 2026 08:46:24 +0200 Subject: [PATCH 5/7] Refactor `Str` class by introducing `StringValue` as the new base, add `Char` type **Details:** - Extracted encoding-aware functionality from `Str` into a new `StringValue` abstract class in `Core-Standard/src/Type/StringValue.php`, preserving the immutable string value semantics. - Updated `Str` in `Core-Standard/src/Type/Str.php` to extend `StringValue`, simplifying its structure for domain-specific usage and aligning with Core's modular architecture. - Added `Char` abstract class in `Core-Standard/src/Type/Char.php` to define the base for character-based Value Objects. Ensures support for handling single characters with encoding awareness. - Updated class hierarchy to establish clear separation of concerns between general `StringValue` contracts and domain-specific `Str` and `Char` implementations. These changes enhance the modularity and extensibility of the Core layer, simplifying future extensions and reinforcing separation of architectural responsibilities. --- src/Type/Char.php | 32 ++++++++++++++++ src/Type/Str.php | 52 +------------------------- src/Type/StringValue.php | 80 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 114 insertions(+), 50 deletions(-) create mode 100644 src/Type/Char.php create mode 100644 src/Type/StringValue.php diff --git a/src/Type/Char.php b/src/Type/Char.php new file mode 100644 index 0000000..37ac187 --- /dev/null +++ b/src/Type/Char.php @@ -0,0 +1,32 @@ + + * @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 Core + */ + +namespace FireHub\Core\Type; + +/** + * ### Defines the base character Value Object type within the FireHub ecosystem + * + * This abstract class represents the foundation for all character-based Value Objects. + * + * It provides immutable character value semantics while ensuring that implementations represent a single valid + * character within a specific encoding. + * + * The class keeps the Core layer focused on defining the character value contract, while concrete implementations + * belong to higher-level layers such as Foundation. + * @since 1.0.0 + * + * @template TValue of non-empty-string + * + * @extends \FireHub\Core\Type\StringValue + */ +abstract readonly class Char extends StringValue {} \ No newline at end of file diff --git a/src/Type/Str.php b/src/Type/Str.php index 08d5f5f..bf4037a 100644 --- a/src/Type/Str.php +++ b/src/Type/Str.php @@ -13,9 +13,6 @@ namespace FireHub\Core\Type; -use FireHub\Core\Type\Str\Encoding; -use Stringable; - /** * ### Defines the base string Value Object type within the FireHub ecosystem * @@ -30,51 +27,6 @@ * * @template TValue of string * - * @extends \FireHub\Core\Type\ValueObject + * @extends \FireHub\Core\Type\StringValue */ -abstract readonly class Str extends ValueObject implements Stringable { - - /** - * @inheritDoc - * - * @since 1.0.0 - */ - abstract public function value ():string; - - /** - * ### Returns the encoding of the string - * @since 1.0.0 - * - * @return \FireHub\Core\Type\Str\Encoding The encoding of the string. - */ - abstract public function encoding ():Encoding; - - /** - * ### Returns a new instance with the specified encoding - * @since 1.0.0 - * - * @param \FireHub\Core\Type\Str\Encoding $encoding

- * The encoding to set. - *

- * - * @return static The new instance with provided encoding. - */ - abstract public function withEncoding (Encoding $encoding):static; - - /** - * ### Returns the string representation of the value - * - * Provides the native PHP string representation of the Value Object. - * @since 1.0.0 - * - * @uses \FireHub\Core\Type\ValueObject::value() To get the string value. - * - * @return TValue The string representation of the value. - */ - public function __toString ():string { - - return $this->value(); - - } - -} \ No newline at end of file +abstract readonly class Str extends StringValue {} \ No newline at end of file diff --git a/src/Type/StringValue.php b/src/Type/StringValue.php new file mode 100644 index 0000000..fd1b833 --- /dev/null +++ b/src/Type/StringValue.php @@ -0,0 +1,80 @@ + + * @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 Core + */ + +namespace FireHub\Core\Type; + +use FireHub\Core\Type\Str\Encoding; +use Stringable; + +/** + * ### Defines the base string value object type within the FireHub ecosystem + * + * This abstract class represents the foundation for all string-based Value Objects. + * + * It provides immutable string value semantics with encoding awareness while allowing concrete implementations + * to define specific string constraints and domain-specific behavior. + * + * The class keeps the Core layer focused on defining the common string value contract, while concrete + * implementations belong to higher-level layers such as Foundation. + * @since 1.0.0 + * + * @template TValue of string + * + * @extends \FireHub\Core\Type\ValueObject + */ +abstract readonly class StringValue extends ValueObject implements Stringable { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():string; + + /** + * ### Returns the encoding of the string value + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Str\Encoding The encoding of the string value. + */ + abstract public function encoding ():Encoding; + + /** + * ### Returns a new instance with the specified encoding + * @since 1.0.0 + * + * @param \FireHub\Core\Type\Str\Encoding $encoding

+ * The encoding to set. + *

+ * + * @return static The new instance with provided encoding. + */ + abstract public function withEncoding (Encoding $encoding):static; + + /** + * ### Returns the string representation of the value + * + * Provides the native PHP string representation of the Value Object. + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\ValueObject::value() To get the string value. + * + * @return TValue The string representation of the value. + */ + public function __toString ():string { + + return $this->value(); + + } + +} \ No newline at end of file From 1196d70f40085cc94d7cfe522367ba58044758e0 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 7 Aug 2026 14:24:43 +0200 Subject: [PATCH 6/7] Add `toChars` method to `Str` for converting strings to a list of `Char` objects **Details:** - Introduced an abstract `toChars(): array` method in the `Str` class within `Core-Standard/src/Type/Str.php`. - Provides a mechanism to split the immutable string value into a list of `Char` objects. - Enhances the extensibility of the `Str` class for character-level operations, aligning with the FireHub ecosystem's focus on modularity and type safety. This update lays the groundwork for fine-grained string manipulations, improving support for encoding-aware scenarios and future extensions. --- src/Type/Str.php | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/Type/Str.php b/src/Type/Str.php index bf4037a..84b6c38 100644 --- a/src/Type/Str.php +++ b/src/Type/Str.php @@ -29,4 +29,14 @@ * * @extends \FireHub\Core\Type\StringValue */ -abstract readonly class Str extends StringValue {} \ No newline at end of file +abstract readonly class Str extends StringValue { + + /** + * ### Converts the string to the list of Chars + * @since 1.0.0 + * + * @return list<\FireHub\Core\Type\Char> + */ + abstract public function toChars ():array; + +} \ No newline at end of file From 2a049b4dd732bab8768f83f0a423bc8afa895727 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 7 Aug 2026 14:45:18 +0200 Subject: [PATCH 7/7] Add `Boolean` base value object type for immutable boolean semantics **Details:** - Introduced an abstract `Boolean` class in `Core-Standard/src/Type/Boolean.php` to define the foundational boolean-based Value Object type within the FireHub ecosystem. - Implements immutable boolean value semantics while serving as the base for domain-specific boolean extensions in higher-level layers (e.g., Foundation). - Provides a clear contract for boolean handling with its abstract `value(): bool` method. - Aligns with the Core layer's focus on defining stable architectural contracts and PHP type safety (`>=8.2`). This addition strengthens the modularity, type safety, and extensibility of the Core layer, ensuring clarity and consistency for boolean-related operations within the FireHub project. --- src/Type/Boolean.php | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 src/Type/Boolean.php diff --git a/src/Type/Boolean.php b/src/Type/Boolean.php new file mode 100644 index 0000000..566ad4d --- /dev/null +++ b/src/Type/Boolean.php @@ -0,0 +1,41 @@ + + * @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 Core + */ + +namespace FireHub\Core\Type; + +/** + * ### Defines the base boolean Value Object type within the FireHub ecosystem + * + * This abstract class represents the foundation for all boolean-based Value Objects. + * + * It provides immutable boolean value semantics while allowing concrete implementations to extend the type with + * domain-specific behavior. + * + * The class keeps the Core layer focused on defining the boolean value contract, while concrete implementations + * belong to higher-level layers such as Foundation. + * @since 1.0.0 + * + * @template TValue of bool + * + * @extends \FireHub\Core\Type\ValueObject + */ +abstract readonly class Boolean extends ValueObject { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():bool; + +} \ No newline at end of file