From 74cb5f5b939d0e7de5437d6b56404d22ff16adc3 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 18 Jun 2026 08:52:29 +0200 Subject: [PATCH 1/3] Update README to reflect Core Value Object System and branch details --- README.md | 95 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 64 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 859267a..7f44dbe 100644 --- a/README.md +++ b/README.md @@ -23,19 +23,19 @@

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

@@ -45,47 +45,80 @@ Standard provides the base classes, kernel, domain layer, and minimal runtime ut --- -## FireHub Icon Development Branch +## FireHub Icon Core Value Object System – 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. +This branch defines the **Core Value Object System** for the FireHub ecosystem. -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 +It establishes the foundational rules for how immutable, strongly typed data structures are represented across: -All **release branches** are created **from `develop`**. +- Core Standard +- Core Professional +- Core Enterprise +- Runtime Foundation (consumers only) -## Stability Guarantee +## FireHub Icon Architectural Goal -❌ No backward compatibility guarantee -❌ APIs may change without notice -❌ Behavior may be incomplete or inconsistent -❌ Breaking changes are expected +Introduce a **unified Value Object model** that: -This branch is intended **only for contributors and advanced testers**. +- Eliminates primitive obsession +- Enforces immutability by design +- Provides consistent equality semantics +- Acts as a base language construct for the FireHub Core -## FireHub Icon Composer Usage (Not Recommended) +## FireHub Icon Core Concept -For internal testing only: +A Value Object in FireHub is: -```json -{ - "require": { - "the-firehub-project/core-standard": "dev-develop" - } -} -``` -⚠️ Never use dev-develop in production. +> An immutable, identity-less object defined entirely by its value. ## FireHub Icon Authors and Contributors From 84169658a00aab7ab88e785a9874770592ab37f7 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 18 Jun 2026 13:41:00 +0200 Subject: [PATCH 2/3] Update .gitignore to include build/tooling artifacts --- .gitignore | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 34a321b..e237f9d 100644 --- a/.gitignore +++ b/.gitignore @@ -15,4 +15,9 @@ Thumbs.db # Composer # ========================= /vendor/ -composer.lock \ No newline at end of file +composer.lock + +# ========================= +# Build / Tooling artifacts +# ========================= +/.build/ \ No newline at end of file From 6fea43dbff9f9fb4b6870b31d3a97e75c86797c2 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 19 Jun 2026 09:49:52 +0200 Subject: [PATCH 3/3] Introduce `ValueObject` base class to enforce immutability and value semantics Added an abstract `ValueObject` class to the Core module, providing a foundation for identity-less, immutable data structures. Includes methods for structural equality (`equals`), type strictness (`sameAs`), and invariant enforcement (`guard`). This addition establishes a consistent approach to modeling value objects across the FireHub ecosystem. --- src/type/firehub.ValueObject.php | 101 +++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 src/type/firehub.ValueObject.php diff --git a/src/type/firehub.ValueObject.php b/src/type/firehub.ValueObject.php new file mode 100644 index 0000000..617c680 --- /dev/null +++ b/src/type/firehub.ValueObject.php @@ -0,0 +1,101 @@ + + * @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; + +/** + * ### Base Value Object + * + * Defines the base abstraction for all Value Objects within the FireHub Core ecosystem. + * + * The ValueObject serves as a fundamental immutable contract for representing identity-less data structures based + * purely on their value semantics. It enforces consistency across the system by ensuring that all derived Value Objects + * follow strict immutability rules and structural equality behavior. + * @since 1.0.0 + * + * @template TValue + */ +abstract readonly class ValueObject { + + /** + * ### Returns the raw value of the Value Object + * + * Provides the underlying scalar or composite value represented by this Value Object. + * + * This value is used for structural comparison and domain-level equality checks. + * @since 1.0.0 + * + * @return TValue Raw VO value. + */ + abstract public function value ():mixed; + + /** + * ### Determines structural equality between two Value Objects + * + * Compares this Value Object with another instance of the same type using strict + * class comparison and value equality semantics. + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\ValueObject::sameAs() To compare the VO types. + * @uses \FireHub\Core\Type\ValueObject::value() To compare the VO values. + * + * @param self $other

+ * The Value Object to compare against. + *

+ * + * @return bool True if the VOs are equal, false otherwise. + */ + final public function equals (self $other):bool { + + return $this->sameAs($other) + && $this->value() === $other->value(); + + } + + /** + * ### Checks strict identity equality of a Value Object type + * + * Ensures both objects are of the same concrete class without comparing values. + * @since 1.0.0 + * + * @param \FireHub\Core\Type\ValueObject $other

+ * The Value Object to compare against. + *

+ * + * @return bool True if the objects are of the same type, false otherwise. + */ + final public function sameAs (self $other):bool { + + return static::class === $other::class; + + } + + /** + * ### Enforces an invariant condition for the Value Object + * @since 1.0.0 + * + * @param callable():bool $condition

+ * The validation condition to evaluate. + *

+ * @param callable():\Exception $exception

+ * Exception to be thrown when the condition fails. + *

+ * @return void + */ + final protected function guard (callable $condition, callable $exception):void { + + if ($condition() === false) throw $exception(); + + } + +} \ No newline at end of file