From 2bd95e05f16f642a3b1bffa5da1edc7d00a7497e Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 28 Jul 2026 13:28:52 +0200 Subject: [PATCH 001/118] 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 002/118] 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 003/118] 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 004/118] 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 005/118] 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 006/118] 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 007/118] 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 From e448f642ead07c1c91452dabf426c999134f352f Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 18 Aug 2026 10:06:07 +0200 Subject: [PATCH 008/118] Add base numeric Value Object classes for integer and decimal types --- src/Type/Number.php | 41 +++++++++++++++++++++++++++++++++ src/Type/Number/Decimal.php | 46 +++++++++++++++++++++++++++++++++++++ src/Type/Number/Integer.php | 46 +++++++++++++++++++++++++++++++++++++ 3 files changed, 133 insertions(+) create mode 100644 src/Type/Number.php create mode 100644 src/Type/Number/Decimal.php create mode 100644 src/Type/Number/Integer.php diff --git a/src/Type/Number.php b/src/Type/Number.php new file mode 100644 index 0000000..519564a --- /dev/null +++ b/src/Type/Number.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 numeric Value Object type within the FireHub ecosystem + * + * This abstract class represents the foundation for all numeric-based Value Objects. + * + * It provides immutable numeric value semantics while allowing concrete implementations to define specific numeric + * behavior for integer and floating-point values. + * + * The class keeps the Core layer focused on defining the numeric value contract, while concrete implementations belong + * to higher-level layers such as Foundation. + * @since 1.0.0 + * + * @template TValue of numeric|numeric-string + * + * @extends \FireHub\Core\Type\ValueObject + */ +abstract readonly class Number extends ValueObject { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():int|float|string; + +} \ No newline at end of file diff --git a/src/Type/Number/Decimal.php b/src/Type/Number/Decimal.php new file mode 100644 index 0000000..f9d319c --- /dev/null +++ b/src/Type/Number/Decimal.php @@ -0,0 +1,46 @@ + + * @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\Number; + +use FireHub\Core\Type\Number; + +/** + * ### Provides an immutable floating-point value object with a high-level developer API + * + * The Float class represents a floating-point value within the FireHub Foundation layer. + * + * It provides an expressive and object-oriented interface for working with floating-point values while preserving + * immutable value semantics inherited from the Core Value Object system. + * + * The class implements the Core numeric type contract and extends the base Number Value Object abstraction, allowing + * floating-point values to be used consistently across the FireHub ecosystem. + * + * This class is responsible for high-level floating-point operations and developer experience, while low-level numeric + * execution remains delegated to the Runtime layer. + * @since 1.0.0 + * + * @template TValue of numeric-string + * + * @extends \FireHub\Core\Type\Number + */ +abstract readonly class Decimal extends Number { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():string; + +} \ No newline at end of file diff --git a/src/Type/Number/Integer.php b/src/Type/Number/Integer.php new file mode 100644 index 0000000..aaed79c --- /dev/null +++ b/src/Type/Number/Integer.php @@ -0,0 +1,46 @@ + + * @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\Number; + +use FireHub\Core\Type\Number; + +/** + * ### Provides an immutable integer value object with a high-level developer API + * + * The Integer class represents an integer value within the FireHub Foundation layer. + * + * It provides an expressive and object-oriented interface for working with integer values while preserving immutable + * value semantics inherited from the Core Value Object system. + * + * The class implements the Core numeric type contract and extends the base Number Value Object abstraction, allowing + * integer values to be used consistently across the FireHub ecosystem. + * + * This class is responsible for high-level integer operations and developer experience, while low-level numeric + * execution remains delegated to the Runtime layer. + * @since 1.0.0 + * + * @template TValue of int + * + * @extends \FireHub\Core\Type\Number + */ +abstract readonly class Integer extends Number { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():int; + +} \ No newline at end of file From 84a0808a02a040b66bffa16a6eb1b3784b404e13 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 18 Aug 2026 10:09:12 +0200 Subject: [PATCH 009/118] Add base numeric Value Object classes for integer and decimal types --- src/Type/Number.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Type/Number.php b/src/Type/Number.php index 519564a..117cf94 100644 --- a/src/Type/Number.php +++ b/src/Type/Number.php @@ -19,7 +19,7 @@ * This abstract class represents the foundation for all numeric-based Value Objects. * * It provides immutable numeric value semantics while allowing concrete implementations to define specific numeric - * behavior for integer and floating-point values. + * behavior for different numeric representations, such as integers and decimal values. * * The class keeps the Core layer focused on defining the numeric value contract, while concrete implementations belong * to higher-level layers such as Foundation. From b73141bd447d9c84242e6191216496e1225df046 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 18 Aug 2026 15:52:24 +0200 Subject: [PATCH 010/118] Add Format and Real classes for numeric representation in FireHub Core --- src/Meta/Enum/Number/Format.php | 81 +++++++++++++++++++++++++++++++++ src/Type/Number/Real.php | 46 +++++++++++++++++++ 2 files changed, 127 insertions(+) create mode 100644 src/Meta/Enum/Number/Format.php create mode 100644 src/Type/Number/Real.php diff --git a/src/Meta/Enum/Number/Format.php b/src/Meta/Enum/Number/Format.php new file mode 100644 index 0000000..ad395ec --- /dev/null +++ b/src/Meta/Enum/Number/Format.php @@ -0,0 +1,81 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Number; + +/** + * ### Defines predefined numeric formatting conventions + * + * Provides commonly used numeric formatting conventions for interpreting decimal values. + * + * Each case defines the decimal and a thousand separators associated with the convention. + * @since 1.0.0 + */ +enum Format { + + /** + * ### Defines the international dot-decimal convention + * + * Uses a dot as the decimal separator and a comma as the thousand separator. + * @since 1.0.0 + */ + case DOT; + + /** + * ### Defines the comma-decimal convention + * + * Uses a comma as the decimal separator and a dot as the thousand separator. + * @since 1.0.0 + */ + case COMMA; + + /** + * ### Defines the SI-style convention + * + * Uses a dot as the decimal separator and a space as the thousand separator. + * @since 1.0.0 + */ + case SI; + + /** + * ### Returns the decimal separator + * @since 1.0.0 + * + * @return string The decimal separator. + */ + public function decimalSeparator ():string { + + return match ($this) { + self::DOT, self::SI => '.', + self::COMMA => ',', + }; + + } + + /** + * ### Returns a thousand separator + * @since 1.0.0 + * + * @return string The thousand separator. + */ + public function thousandsSeparator ():string { + + return match ($this) { + self::DOT => ',', + self::COMMA => '.', + self::SI => ' ', + }; + + } + +} \ No newline at end of file diff --git a/src/Type/Number/Real.php b/src/Type/Number/Real.php new file mode 100644 index 0000000..e7ed158 --- /dev/null +++ b/src/Type/Number/Real.php @@ -0,0 +1,46 @@ + + * @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\Number; + +use FireHub\Core\Type\Number; + +/** + * ### Defines an immutable real number value object within the FireHub ecosystem + * + * The Real class represents a real number value within the FireHub Core layer. + * + * It defines the contract for floating-point values while preserving immutable value semantics inherited from the Core + * Value Object system. + * + * The class extends the base Number Value Object abstraction, allowing real number values to be represented + * consistently across the FireHub ecosystem. + * + * This class is responsible for defining the real number type contract, while high-level operations and low-level + * floating-point execution are delegated to higher-level and Runtime layers respectively. + * @since 1.0.0 + * + * @template TValue of float + * + * @extends \FireHub\Core\Type\Number + */ +abstract readonly class Real extends Number { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():float; + +} \ No newline at end of file From 62f68b6d8eff11f5f80c5050c264e3d40eecd89e Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 20 Aug 2026 08:22:10 +0200 Subject: [PATCH 011/118] Remove `Decimal` abstract class from Core-Standard **Details:** - Deleted the `Decimal` abstract class in `Core-Standard/src/Type/Number/Decimal.php`, initially designed as an immutable floating-point value object. - The removal reflects a decision to streamline numeric type abstractions, reducing redundancy while aligning Core's scope with clearer architectural priorities. - Cleans up unused functionality and simplifies the Core layer's numeric type hierarchy. This change eliminates unnecessary complexity, ensuring a leaner and more focused Core architecture within the FireHub ecosystem. --- src/Type/Number/Decimal.php | 46 ------------------------------------- 1 file changed, 46 deletions(-) delete mode 100644 src/Type/Number/Decimal.php diff --git a/src/Type/Number/Decimal.php b/src/Type/Number/Decimal.php deleted file mode 100644 index f9d319c..0000000 --- a/src/Type/Number/Decimal.php +++ /dev/null @@ -1,46 +0,0 @@ - - * @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\Number; - -use FireHub\Core\Type\Number; - -/** - * ### Provides an immutable floating-point value object with a high-level developer API - * - * The Float class represents a floating-point value within the FireHub Foundation layer. - * - * It provides an expressive and object-oriented interface for working with floating-point values while preserving - * immutable value semantics inherited from the Core Value Object system. - * - * The class implements the Core numeric type contract and extends the base Number Value Object abstraction, allowing - * floating-point values to be used consistently across the FireHub ecosystem. - * - * This class is responsible for high-level floating-point operations and developer experience, while low-level numeric - * execution remains delegated to the Runtime layer. - * @since 1.0.0 - * - * @template TValue of numeric-string - * - * @extends \FireHub\Core\Type\Number - */ -abstract readonly class Decimal extends Number { - - /** - * @inheritDoc - * - * @since 1.0.0 - */ - abstract public function value ():string; - -} \ No newline at end of file From 9892d77f520a662e469ea6fc41322bd54202fea3 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 20 Aug 2026 08:47:23 +0200 Subject: [PATCH 012/118] Add `isTrue` and `isFalse` methods to `Boolean` base class **Details:** - Introduced abstract `isTrue(): bool` and `isFalse(): bool` methods in the `Boolean` class within `Core-Standard/src/Type/Boolean.php`. - Provides explicit contracts for checking boolean value states, improving clarity and semantic expressiveness in boolean handling. - Reinforces the immutability and type safety principles of the `Boolean` Value Object, aligning with the FireHub Core's design philosophy. This update enhances the usability and readability of the `Boolean` base class while paving the way for consistent boolean state-checking operations. --- src/Type/Boolean.php | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/Type/Boolean.php b/src/Type/Boolean.php index 566ad4d..9c43103 100644 --- a/src/Type/Boolean.php +++ b/src/Type/Boolean.php @@ -31,6 +31,22 @@ */ abstract readonly class Boolean extends ValueObject { + /** + * ### Checks if the value is true + * @since 1.0.0 + * + * @return bool Returns true if the value is true, false otherwise. + */ + abstract public function isTrue ():bool; + + /** + * ### Checks if the value is false + * @since 1.0.0 + * + * @return bool Returns true if the value is false, false otherwise. + */ + abstract public function isFalse ():bool; + /** * @inheritDoc * From 5e53c87cace21425ecb66d3e83d72b2fa595b8b9 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 20 Aug 2026 08:55:39 +0200 Subject: [PATCH 013/118] Refactor Boolean class methods for improved clarity and consistency --- src/Type/Boolean.php | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src/Type/Boolean.php b/src/Type/Boolean.php index 9c43103..05a8b07 100644 --- a/src/Type/Boolean.php +++ b/src/Type/Boolean.php @@ -35,17 +35,29 @@ * ### Checks if the value is true * @since 1.0.0 * + * @uses \FireHub\Core\Type\Boolean::value() To get the value. + * * @return bool Returns true if the value is true, false otherwise. */ - abstract public function isTrue ():bool; + public function isTrue ():bool { + + return $this->value()=== true; + + } /** * ### Checks if the value is false * @since 1.0.0 * + * @uses \FireHub\Core\Type\Boolean::isTrue() To check if the value is true. + * * @return bool Returns true if the value is false, false otherwise. */ - abstract public function isFalse ():bool; + public function isFalse ():bool { + + return $this->value() === false; + + } /** * @inheritDoc From f237eee281e58cce4f490d96e2b3aa04d126676b Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 20 Aug 2026 09:01:22 +0200 Subject: [PATCH 014/118] Add `codepoint` method to `Char` for Unicode code point retrieval **Details:** - Introduced an abstract `codepoint(): int` method in the `Char` class within `Core-Standard/src/Type/Char.php`. - Defines a contract for retrieving the Unicode code point of a character, returning a non-negative integer. - Enhances the extensibility of the `Char` class for character-level operations, aligning with the modular and type-safe design principles of the FireHub Core. This addition improves support for fine-grained character processing while maintaining the immutability and clarity of the `Char` Value Object. --- src/Type/Char.php | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/Type/Char.php b/src/Type/Char.php index 37ac187..96b801d 100644 --- a/src/Type/Char.php +++ b/src/Type/Char.php @@ -29,4 +29,14 @@ * * @extends \FireHub\Core\Type\StringValue */ -abstract readonly class Char extends StringValue {} \ No newline at end of file +abstract readonly class Char extends StringValue { + + /** + * ### Returns the Unicode code point for the character + * @since 1.0.0 + * + * @return non-negative-int The Unicode code point for the character. + */ + abstract public function codepoint ():int; + +} \ No newline at end of file From 9bacc0c7a2f6734c4222a29ab1b2cba78322c8ea Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 20 Aug 2026 09:32:15 +0200 Subject: [PATCH 015/118] Introduce `Codepoint` Value Object for Unicode support and update `Char` contract **Details:** - Added a new `Codepoint` class (`Core-Standard/src/Type/Char/Codepoint.php`) to represent immutable Unicode code points, incorporating validation for valid scalar values within the range of U+0000 to U+10FFFF (excluding surrogates). - Created an `InvalidCodepointException` class for handling invalid Unicode code point scenarios. - Updated the `Char` class (`Core-Standard/src/Type/Char.php`) to return a `Codepoint` object through its `codepoint()` method, enhancing the type safety and extensibility of the `Char` Value Object. - Removed unnecessary `final` keyword from the `Code` class definition to ensure alignment with extensibility policies. These changes provide robust Unicode handling within the Core layer while reinforcing the immutability and clarity principles of value object design in the FireHub ecosystem. --- src/Exception/Code.php | 2 +- .../Invariant/InvalidCodepointException.php | 22 ++++++ src/Type/Char.php | 6 +- src/Type/Char/Codepoint.php | 75 +++++++++++++++++++ 4 files changed, 102 insertions(+), 3 deletions(-) create mode 100644 src/Exception/Runtime/System/Invariant/InvalidCodepointException.php create mode 100644 src/Type/Char/Codepoint.php diff --git a/src/Exception/Code.php b/src/Exception/Code.php index 1ea5514..af9595e 100644 --- a/src/Exception/Code.php +++ b/src/Exception/Code.php @@ -24,7 +24,7 @@ * * @extends \FireHub\Core\Type\ValueObject */ -final readonly class Code extends ValueObject { +readonly class Code extends ValueObject { /** * ### Constructor diff --git a/src/Exception/Runtime/System/Invariant/InvalidCodepointException.php b/src/Exception/Runtime/System/Invariant/InvalidCodepointException.php new file mode 100644 index 0000000..ffbe848 --- /dev/null +++ b/src/Exception/Runtime/System/Invariant/InvalidCodepointException.php @@ -0,0 +1,22 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Exception\Runtime\System\Invariant; + +use FireHub\Core\Exception\Runtime\System\InvariantException; + +/** + * ### Represents an invalid codepoint provided to an operation that requires a valid codepoint + * @since 1.0.0 + */ +class InvalidCodepointException extends InvariantException {} \ No newline at end of file diff --git a/src/Type/Char.php b/src/Type/Char.php index 96b801d..5cca7f6 100644 --- a/src/Type/Char.php +++ b/src/Type/Char.php @@ -13,6 +13,8 @@ namespace FireHub\Core\Type; +use FireHub\Core\Type\Char\Codepoint; + /** * ### Defines the base character Value Object type within the FireHub ecosystem * @@ -35,8 +37,8 @@ * ### Returns the Unicode code point for the character * @since 1.0.0 * - * @return non-negative-int The Unicode code point for the character. + * @return \FireHub\Core\Type\Char\Codepoint The Unicode code point for the character. */ - abstract public function codepoint ():int; + abstract public function codepoint ():Codepoint; } \ No newline at end of file diff --git a/src/Type/Char/Codepoint.php b/src/Type/Char/Codepoint.php new file mode 100644 index 0000000..173c32a --- /dev/null +++ b/src/Type/Char/Codepoint.php @@ -0,0 +1,75 @@ + + * @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\Char; + +use FireHub\Core\Type\Number\Integer; +use FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodepointException; + +/** + * ### Defines a Unicode code point value object + * + * The Codepoint class represents a valid Unicode scalar value within the FireHub ecosystem. + * + * A Unicode code point is represented by an integer in the range from U+0000 to U+10FFFF, excluding the + * surrogate range U+D800 through U+DFFF. + * + * The class provides immutable value semantics for Unicode code points while allowing concrete implementations + * to define how the underlying value is stored and validated. + * @since 1.0.0 + * + * @template TValue of int + * + * @extends \FireHub\Core\Type\Number\Integer + */ +readonly class Codepoint extends Integer { + + /** + * ### Constructor + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\ValueObject::guard() As a guard. + * + * @param TValue $value

+ * The code point value. + *

+ * + * @throws \FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodepointException If the condition is not met. + * @throws \FireHub\Core\Exception\FireHubException If the condition is not met. + * @throws \FireHub\Core\Type\Exception\ValueObjectException If the exception is not a FireHubException. + * + * @return void + */ + public function __construct ( + private int $value + ) { + + $this->guard( + fn() => $value >= 0 && $value <= 0x10FFFF && ($value < 0xD800 || $value > 0xDFFF), + fn() => new InvalidCodepointException('Value must be a valid Unicode code point.') + ); + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():int { + + return $this->value; + + } + +} \ No newline at end of file From b9ab7edf96ad00431ae8b442facbb54e04ccaf2f Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 20 Aug 2026 10:23:09 +0200 Subject: [PATCH 016/118] Add numeric state-checking methods to `Number` and `Real` classes **Details:** - Added `isPositive(): bool`, `isNegative(): bool`, and `isZero(): bool` methods to the `Number` base class in `Core-Standard/src/Type/Number.php` for checking numeric states. - Introduced abstract methods `isFinite(): bool`, `isInfinite(): bool`, and `isNaN(): bool` to the `Real` class in `Core-Standard/src/Type/Number/Real.php`. - Enhances the extensibility and semantic clarity of numeric value objects, ensuring robust type-safe contracts for numeric state evaluations in the FireHub Core. These enhancements align with the FireHub ecosystem's focus on immutability, clarity, --- src/Type/Number.php | 42 ++++++++++++++++++++++++++++++++++++++++ src/Type/Number/Real.php | 24 +++++++++++++++++++++++ 2 files changed, 66 insertions(+) diff --git a/src/Type/Number.php b/src/Type/Number.php index 117cf94..6679647 100644 --- a/src/Type/Number.php +++ b/src/Type/Number.php @@ -31,6 +31,48 @@ */ abstract readonly class Number extends ValueObject { + /** + * ### Checks if the number is positive + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\Number::value() To get the value. + * + * @return bool Whether the number is positive. + */ + public function isPositive ():bool { + + return $this->value() > 0; + + } + + /** + * ### Checks if the number is negative + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\Number::value() To get the value. + * + * @return bool Whether the number is negative. + */ + public function isNegative ():bool { + + return $this->value() < 0; + + } + + /** + * ### Checks if the number is zero + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\Number::value() To get the value. + * + * @return bool Whether the number is zero. + */ + public function isZero ():bool { + + return (float)$this->value() === 0.0; + + } + /** * @inheritDoc * diff --git a/src/Type/Number/Real.php b/src/Type/Number/Real.php index e7ed158..f5ccf64 100644 --- a/src/Type/Number/Real.php +++ b/src/Type/Number/Real.php @@ -36,6 +36,30 @@ */ abstract readonly class Real extends Number { + /** + * ### Checks if the number is finite + * @since 1.0.0 + * + * @return bool Whether the number is finite. + */ + abstract public function isFinite ():bool; + + /** + * ### Checks if the number is infinite + * @since 1.0.0 + * + * @return bool Whether the number is infinite. + */ + abstract public function isInfinite ():bool; + + /** + * ### Checks if the number is NaN (Not a Number) + * @since 1.0.0 + * + * @return bool Whether the number is NaN. + */ + abstract public function isNaN ():bool; + /** * @inheritDoc * From 3588e1d67778a6ce0a69932a9f0a83b2c244d6e9 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 21 Aug 2026 09:06:42 +0200 Subject: [PATCH 017/118] Add `Format` Enum for Standardized Temporal Formats in FireHub Core **Details:** - Introduced `Format` enum (`Core-Standard/src/Meta/Enum/Temporal/Format.php`) to provide predefined date and time formatting standards in the FireHub ecosystem. - Includes reusable formats for ISO 8601, ATOM, RFC, HTTP, and other common temporal patterns, with support for microsecond precision where applicable. - Enhances consistency and semantic clarity for handling temporal values, offering reusable format templates across the ecosystem. - Supports custom PHP date/time strings while ensuring robust and type-safe temporal operations. This addition aligns with FireHub Core's design principles of clarity, reusability, and extensibility, improving standardization across temporal data operations. --- src/Meta/Enum/Temporal/Format.php | 193 ++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 src/Meta/Enum/Temporal/Format.php diff --git a/src/Meta/Enum/Temporal/Format.php b/src/Meta/Enum/Temporal/Format.php new file mode 100644 index 0000000..2fcee3a --- /dev/null +++ b/src/Meta/Enum/Temporal/Format.php @@ -0,0 +1,193 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Temporal; + +/** + * ### Provides predefined date and time formatting standards + * + * The TemporalFormat enum defines commonly used PHP date and time format patterns for parsing and formatting temporal + * values throughout the FireHub ecosystem. + * + * It provides reusable predefined formats for date, time, and combined date-time values while allowing temporal value + * objects to maintain support for arbitrary custom PHP format strings. + * @since 1.0.0 + */ +enum Format:string { + + /** + * ### ISO 8601 calendar date + * + * + * 2000-12-31 + * + * + * @since 1.0.0 + */ + case ISO_DATE = 'Y-m-d'; + + /** + * ### ISO time + * + * + * 23:59:50 + * + * + * @since 1.0.0 + */ + case ISO_TIME = 'H:i:s'; + + /** + * ### ISO time with microseconds + * + * + * 23:59:50.000000 + * + * + * @since 1.0.0 + */ + case ISO_TIME_MICROSECONDS = 'H:i:s.u'; + + /** + * ### ISO date and time + * + * + * 2000-12-31 23:59:50 + * + * + * @since 1.0.0 + */ + case ISO_DATE_TIME = 'Y-m-d H:i:s'; + + /** + * ### ISO date and time with microseconds + * + * + * 2000-12-31 23:59:50.000000 + * + * + * @since 1.0.0 + */ + case ISO_DATE_TIME_MICROSECONDS = 'Y-m-d H:i:s.u'; + + /** + * ### ATOM date and time + * + * + * 2000-12-31T23:59:50+01:00 + * + * + * @since 1.0.0 + */ + case ATOM = 'Y-m-d\TH:i:sP'; + + /** + * ### ATOM date and time with milliseconds + * + * + * 2000-12-31T23:59:50.000+01:00 + * + * + * @since 1.0.0 + */ + case ATOM_EXTENDED = 'Y-m-d\TH:i:s.vP'; + + /** + * ### ATOM date and time with microseconds + * + * + * 2000-12-31T23:59:50.000000+01:00 + * + * + * @since 1.0.0 + */ + case ATOM_MICROSECONDS = 'Y-m-d\TH:i:s.uP'; + + /** + * ### HTTP cookie date and time + * + * + * Sunday, 31-Dec-2000 23:59:50 CET + * + * + * @since 1.0.0 + */ + case COOKIE = 'l, d-M-Y H:i:s T'; + + /** + * ### ISO 8601 date and time with numeric timezone offset + * + * + * 2000-12-31T23:59:50+0100 + * + * + * @since 1.0.0 + */ + case ISO8601 = 'Y-m-d\TH:i:sO'; + + /** + * ### ISO 8601 expanded date and time + * + * + * +2000-12-31T23:59:50+01:00 + * + * + * @since 1.0.0 + */ + case ISO8601_EXPANDED = 'X-m-d\TH:i:sP'; + + /** + * ### RFC 822 date and time + * + * + * Sun, 31 Dec 00 23:59:50 +0100 + * + * + * @since 1.0.0 + */ + case RFC822 = 'D, d M y H:i:s O'; + + /** + * ### RFC 850 date and time + * + * + * Sunday, 31-Dec-00 23:59:50 CET + * + * + * @since 1.0.0 + */ + case RFC850 = 'l, d-M-y H:i:s T'; + + /** + * ### RFC 7231 HTTP date and time + * + * + * Sun, 31 Dec 2000 23:59:50 GMT + * + * + * @since 1.0.0 + */ + case RFC7231 = 'D, d M Y H:i:s \G\M\T'; + + /** + * ### RSS date and time + * + * + * Sun, 31 Dec 2000 23:59:50 +0100 + * + * + * @since 1.0.0 + */ + case RSS = 'D, d M Y H:i:s O'; + +} \ No newline at end of file From f15663f7c049f80dd13f87f760abb89fd69f4e06 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 21 Aug 2026 09:07:03 +0200 Subject: [PATCH 018/118] Add base Temporal Value Objects: `Time`, `Date`, and `DateTime` **Details:** - Introduced abstract `Time`, `Date`, and `DateTime` classes in `Core-Standard/src/Type/Temporal/` as foundational temporal Value Object types. - `Time` provides immutability and semantics for time-of-day values. - `Date` offers immutable support for calendar date values. - `DateTime` handles combined date and time values, ensuring robustness in temporal data handling. - Classes remain abstract, enabling higher-level layers to define concrete implementations for application-specific behaviors. - Updated `StringValue` class to refine the `@uses` annotation for string representations. This addition enhances the FireHub ecosystem by standardizing immutable temporal contracts, aligning with the core principles of reusability, clarity, and extensibility. --- src/Type/StringValue.php | 2 +- src/Type/Temporal/Date.php | 60 ++++++++++++++++++++++++++++++++++ src/Type/Temporal/DateTime.php | 60 ++++++++++++++++++++++++++++++++++ src/Type/Temporal/Time.php | 60 ++++++++++++++++++++++++++++++++++ 4 files changed, 181 insertions(+), 1 deletion(-) create mode 100644 src/Type/Temporal/Date.php create mode 100644 src/Type/Temporal/DateTime.php create mode 100644 src/Type/Temporal/Time.php diff --git a/src/Type/StringValue.php b/src/Type/StringValue.php index fd1b833..48bbe81 100644 --- a/src/Type/StringValue.php +++ b/src/Type/StringValue.php @@ -67,7 +67,7 @@ abstract public function withEncoding (Encoding $encoding):static; * 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. + * @uses \FireHub\Core\Type\StringValue::value() To get the string value. * * @return TValue The string representation of the value. */ diff --git a/src/Type/Temporal/Date.php b/src/Type/Temporal/Date.php new file mode 100644 index 0000000..1d862d6 --- /dev/null +++ b/src/Type/Temporal/Date.php @@ -0,0 +1,60 @@ + + * @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\Temporal; + +use FireHub\Core\Type\ValueObject; +use Stringable; + +/** + * ### Defines the base date Value Object type within the FireHub ecosystem + * + * This abstract class represents the foundation for date-based Value Objects. + * + * It provides immutable calendar date value semantics while allowing concrete implementations to define + * date-specific behavior in higher-level layers. + * + * The class keeps the Core layer focused on defining the fundamental date value contract, while concrete date + * operations and developer-facing functionality belong to higher-level layers such as Foundation. + * @since 1.0.0 + * + * @template TValue of non-empty-string + * + * @extends \FireHub\Core\Type\ValueObject + */ +abstract readonly class Date extends ValueObject implements Stringable { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():string; + + /** + * ### 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\Temporal\Date::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 diff --git a/src/Type/Temporal/DateTime.php b/src/Type/Temporal/DateTime.php new file mode 100644 index 0000000..cb324eb --- /dev/null +++ b/src/Type/Temporal/DateTime.php @@ -0,0 +1,60 @@ + + * @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\Temporal; + +use FireHub\Core\Type\ValueObject; +use Stringable; + +/** + * ### Defines the base date and time Value Object type within the FireHub ecosystem + * + * This abstract class represents the foundation for all date and time-based Value Objects. + * + * It provides immutable date and time value semantics while allowing concrete implementations to define specific + * behavior for representing and manipulating combined date and time values. + * + * The class keeps the Core layer focused on defining the date and time 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\ValueObject + */ +abstract readonly class DateTime extends ValueObject implements Stringable { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():string; + + /** + * ### 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\Temporal\Time::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 diff --git a/src/Type/Temporal/Time.php b/src/Type/Temporal/Time.php new file mode 100644 index 0000000..cb47649 --- /dev/null +++ b/src/Type/Temporal/Time.php @@ -0,0 +1,60 @@ + + * @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\Temporal; + +use FireHub\Core\Type\ValueObject; +use Stringable; + +/** + * ### Defines the base time Value Object type within the FireHub ecosystem + * + * This abstract class represents the foundation for all time-based Value Objects. + * + * It provides immutable time-of-day value semantics while allowing concrete implementations to define specific + * behavior for representing and manipulating time values. + * + * The class keeps the Core layer focused on defining the time 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\ValueObject + */ +abstract readonly class Time extends ValueObject implements Stringable { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():string; + + /** + * ### 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\Temporal\Time::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 5697899f64df300abecb08cb2adbe2ffa16d6851 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 21 Aug 2026 09:28:48 +0200 Subject: [PATCH 019/118] Add `Date`, `Time`, and `DateTime` value objects with associated exceptions and tests - **New Value Objects**: - Added `Date`, `Time`, and `DateTime` classes to encapsulate immutable representations of dates, times, and combined date-time values. - Each class provides high-level developer APIs for creating, parsing, and accessing normalized values while adhering to immutability principles. - All classes support customizable input formats using `Format` value objects or raw format strings. - **Custom Exceptions**: - Introduced `InvalidDateException`, `InvalidTimeException`, and `InvalidDateTimeException` to handle parsing errors for invalid values in `Date`, `Time`, and `DateTime`, respectively. - Exceptions include descriptive error messages to improve debugging and user feedback. - **Unit Tests**: - Added comprehensive tests for `DateTest`, `TimeTest`, and `DateTimeTest` to validate parsing, formatting, and value retrieval. - Tests include edge cases for invalid formats, non-empty strings, and mixed format inputs with expected outputs. This update expands the `Foundation` layer with robust support for temporal values, improving date and time handling capabilities while ensuring reliability through extensive testing.ability and semantic accuracy within the FireHub ecosystem. This update aligns with FireHub's design principles of clarity, reusability, and extensibility. --- src/Meta/Enum/{Temporal => Date}/Format.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename src/Meta/Enum/{Temporal => Date}/Format.php (98%) diff --git a/src/Meta/Enum/Temporal/Format.php b/src/Meta/Enum/Date/Format.php similarity index 98% rename from src/Meta/Enum/Temporal/Format.php rename to src/Meta/Enum/Date/Format.php index 2fcee3a..d8df994 100644 --- a/src/Meta/Enum/Temporal/Format.php +++ b/src/Meta/Enum/Date/Format.php @@ -11,7 +11,7 @@ * @package Core */ -namespace FireHub\Core\Meta\Enum\Temporal; +namespace FireHub\Core\Meta\Enum\Date; /** * ### Provides predefined date and time formatting standards From 777f09e1b55eab04cb19bd070b1abfbf7aa2c306 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 21 Aug 2026 10:06:29 +0200 Subject: [PATCH 020/118] Add `zone` and `withZone` methods to `DateTime` contract **Details:** - Introduced the `zone(): Zone` method to the `DateTime` class for retrieving the timezone of a date-time value. - Added the `withZone(Zone $encoding): static` method to allow returning a new instance with a specified timezone. - Updated imports to include `FireHub\Core\Type\Date\Zone`. These additions enhance the `DateTime` Value Object by enabling timezone-aware functionalities, aligning with FireHub's principles of immutability, clarity, and extensibility. --- src/Type/Temporal/DateTime.php | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/src/Type/Temporal/DateTime.php b/src/Type/Temporal/DateTime.php index cb324eb..84c8d59 100644 --- a/src/Type/Temporal/DateTime.php +++ b/src/Type/Temporal/DateTime.php @@ -14,6 +14,7 @@ namespace FireHub\Core\Type\Temporal; use FireHub\Core\Type\ValueObject; +use FireHub\Core\Type\Date\Zone; use Stringable; /** @@ -41,6 +42,26 @@ */ abstract public function value ():string; + /** + * ### Returns the timezone of the date and time value + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Date\Zone The timezone of the date and time value. + */ + abstract public function zone ():Zone; + + /** + * ### Returns a new instance with the specified timezone + * @since 1.0.0 + * + * @param \FireHub\Core\Type\Date\Zone $encoding

+ * The timezone to set. + *

+ * + * @return static The new instance with provided timezone. + */ + abstract public function withZone (Zone $encoding):static; + /** * ### Returns the string representation of the value * From cd12466af1a5f4b747c0510e481beb95eac81ac7 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 21 Aug 2026 10:48:29 +0200 Subject: [PATCH 021/118] Remove `Date`, `Time`, and `DateTime` abstract value objects from Core **Details:** - Deleted the `Date`, `Time`, and `DateTime` abstract classes from `Core-Standard/src/Type/Temporal/`, along with their accompanying contract definitions. - These abstractions are being retired to simplify the Core layer and delegate temporal representations to higher-level application layers. - The removal reflects a focus on reducing redundancy and streamlining the Core's responsibility within the broader FireHub ecosystem. This change aligns with FireHub's architectural priorities of maintaining clarity, modularity, and reducing unnecessary abstractions at the Core level. --- src/Type/Temporal/Date.php | 60 ------------------------- src/Type/Temporal/DateTime.php | 81 ---------------------------------- src/Type/Temporal/Time.php | 60 ------------------------- 3 files changed, 201 deletions(-) delete mode 100644 src/Type/Temporal/Date.php delete mode 100644 src/Type/Temporal/DateTime.php delete mode 100644 src/Type/Temporal/Time.php diff --git a/src/Type/Temporal/Date.php b/src/Type/Temporal/Date.php deleted file mode 100644 index 1d862d6..0000000 --- a/src/Type/Temporal/Date.php +++ /dev/null @@ -1,60 +0,0 @@ - - * @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\Temporal; - -use FireHub\Core\Type\ValueObject; -use Stringable; - -/** - * ### Defines the base date Value Object type within the FireHub ecosystem - * - * This abstract class represents the foundation for date-based Value Objects. - * - * It provides immutable calendar date value semantics while allowing concrete implementations to define - * date-specific behavior in higher-level layers. - * - * The class keeps the Core layer focused on defining the fundamental date value contract, while concrete date - * operations and developer-facing functionality belong to higher-level layers such as Foundation. - * @since 1.0.0 - * - * @template TValue of non-empty-string - * - * @extends \FireHub\Core\Type\ValueObject - */ -abstract readonly class Date extends ValueObject implements Stringable { - - /** - * @inheritDoc - * - * @since 1.0.0 - */ - abstract public function value ():string; - - /** - * ### 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\Temporal\Date::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 diff --git a/src/Type/Temporal/DateTime.php b/src/Type/Temporal/DateTime.php deleted file mode 100644 index 84c8d59..0000000 --- a/src/Type/Temporal/DateTime.php +++ /dev/null @@ -1,81 +0,0 @@ - - * @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\Temporal; - -use FireHub\Core\Type\ValueObject; -use FireHub\Core\Type\Date\Zone; -use Stringable; - -/** - * ### Defines the base date and time Value Object type within the FireHub ecosystem - * - * This abstract class represents the foundation for all date and time-based Value Objects. - * - * It provides immutable date and time value semantics while allowing concrete implementations to define specific - * behavior for representing and manipulating combined date and time values. - * - * The class keeps the Core layer focused on defining the date and time 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\ValueObject - */ -abstract readonly class DateTime extends ValueObject implements Stringable { - - /** - * @inheritDoc - * - * @since 1.0.0 - */ - abstract public function value ():string; - - /** - * ### Returns the timezone of the date and time value - * @since 1.0.0 - * - * @return \FireHub\Core\Type\Date\Zone The timezone of the date and time value. - */ - abstract public function zone ():Zone; - - /** - * ### Returns a new instance with the specified timezone - * @since 1.0.0 - * - * @param \FireHub\Core\Type\Date\Zone $encoding

- * The timezone to set. - *

- * - * @return static The new instance with provided timezone. - */ - abstract public function withZone (Zone $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\Temporal\Time::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 diff --git a/src/Type/Temporal/Time.php b/src/Type/Temporal/Time.php deleted file mode 100644 index cb47649..0000000 --- a/src/Type/Temporal/Time.php +++ /dev/null @@ -1,60 +0,0 @@ - - * @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\Temporal; - -use FireHub\Core\Type\ValueObject; -use Stringable; - -/** - * ### Defines the base time Value Object type within the FireHub ecosystem - * - * This abstract class represents the foundation for all time-based Value Objects. - * - * It provides immutable time-of-day value semantics while allowing concrete implementations to define specific - * behavior for representing and manipulating time values. - * - * The class keeps the Core layer focused on defining the time 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\ValueObject - */ -abstract readonly class Time extends ValueObject implements Stringable { - - /** - * @inheritDoc - * - * @since 1.0.0 - */ - abstract public function value ():string; - - /** - * ### 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\Temporal\Time::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 d47c9150ccac0d92c473534f468298425f7e14f8 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 21 Aug 2026 12:48:21 +0200 Subject: [PATCH 022/118] Reintroduce abstract `DateTime` Value Object in Core MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Details:** - Added the `DateTime` abstract class in `Core-Standard/src/Type/Temporal/` as a foundational type for date and time representations. - Implements immutable value semantics for combined date and time values, preserving the Core's focus on defining standard temporal contracts. - Introduced methods: - `value(): string` - Retrieves the string representation of the date-time value. - `zone(): Zone` - Returns the timezone of the date-time value. - `withZone(Zone $encoding): static` - Creates a new instance with a specified timezone. - `__toString(): string` - Provides the native string representation via `value()`. - Updated imports to include `FireHub\Core\Type\Date\Zone` and other dependencies. This reintroduction aligns with FireHub’s architecture by establishing a foundational `DateTime` contract in the Core, supporting broader temporal abstractions while adhering to clarity, modularity, and immutability principles. --- src/Type/Temporal/DateTime.php | 81 ++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 src/Type/Temporal/DateTime.php diff --git a/src/Type/Temporal/DateTime.php b/src/Type/Temporal/DateTime.php new file mode 100644 index 0000000..84c8d59 --- /dev/null +++ b/src/Type/Temporal/DateTime.php @@ -0,0 +1,81 @@ + + * @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\Temporal; + +use FireHub\Core\Type\ValueObject; +use FireHub\Core\Type\Date\Zone; +use Stringable; + +/** + * ### Defines the base date and time Value Object type within the FireHub ecosystem + * + * This abstract class represents the foundation for all date and time-based Value Objects. + * + * It provides immutable date and time value semantics while allowing concrete implementations to define specific + * behavior for representing and manipulating combined date and time values. + * + * The class keeps the Core layer focused on defining the date and time 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\ValueObject + */ +abstract readonly class DateTime extends ValueObject implements Stringable { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():string; + + /** + * ### Returns the timezone of the date and time value + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Date\Zone The timezone of the date and time value. + */ + abstract public function zone ():Zone; + + /** + * ### Returns a new instance with the specified timezone + * @since 1.0.0 + * + * @param \FireHub\Core\Type\Date\Zone $encoding

+ * The timezone to set. + *

+ * + * @return static The new instance with provided timezone. + */ + abstract public function withZone (Zone $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\Temporal\Time::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 1b8c22da2eb51aa8407ae0731469b76ecd1a5ac6 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 21 Aug 2026 12:57:03 +0200 Subject: [PATCH 023/118] Fix parameter name in `withZone` method of `DateTime` contract **Details:** - Renamed `$encoding` to `$zone` in the `withZone(Zone $encoding): static` method signature for better clarity and alignment with its purpose. - Updated the method's documentation to reflect the change. This improves semantic accuracy in the `DateTime` Value Object, ensuring clearer contracts and adherence to FireHub's design principles of clarity and precision. --- src/Type/Temporal/DateTime.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Type/Temporal/DateTime.php b/src/Type/Temporal/DateTime.php index 84c8d59..41c624a 100644 --- a/src/Type/Temporal/DateTime.php +++ b/src/Type/Temporal/DateTime.php @@ -54,13 +54,13 @@ abstract public function zone ():Zone; * ### Returns a new instance with the specified timezone * @since 1.0.0 * - * @param \FireHub\Core\Type\Date\Zone $encoding

+ * @param \FireHub\Core\Type\Date\Zone $zone

* The timezone to set. *

* * @return static The new instance with provided timezone. */ - abstract public function withZone (Zone $encoding):static; + abstract public function withZone (Zone $zone):static; /** * ### Returns the string representation of the value From 2e32f3e41154e0e62803dcf76fee962e07c86b8c Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 24 Aug 2026 15:56:47 +0200 Subject: [PATCH 024/118] Extract `zone` and `withZone` methods from `DateTime` to new `Timezone` Value Object **Details:** - Removed `zone` and `withZone` abstract methods from the `DateTime` class in `Core-Standard/src/Type/Temporal/DateTime.php`. - Deprecated the use of `FireHub\Core\Type\Date\Zone` within the `DateTime` contract. - Added a new abstract `Timezone` Value Object in `Core-Standard/src/Type/Temporal/Timezone.php` to centralize handling of timezone values. - Introduced the `value(): string` method for retrieving the string representation of the timezone. - Implemented the `__toString()` method for compatibility with native string operations. - Updated PHPDoc annotations in `DateTime` for consistency and removed deprecated references. This change modularizes timezone handling by introducing a dedicated `Timezone` Value Object, improving the clarity, reusability, and single-responsibility adherence of the temporal contracts in the FireHub Core. --- src/Type/Temporal/DateTime.php | 23 +------------- src/Type/Temporal/Timezone.php | 58 ++++++++++++++++++++++++++++++++++ 2 files changed, 59 insertions(+), 22 deletions(-) create mode 100644 src/Type/Temporal/Timezone.php diff --git a/src/Type/Temporal/DateTime.php b/src/Type/Temporal/DateTime.php index 41c624a..9fa0b5e 100644 --- a/src/Type/Temporal/DateTime.php +++ b/src/Type/Temporal/DateTime.php @@ -14,7 +14,6 @@ namespace FireHub\Core\Type\Temporal; use FireHub\Core\Type\ValueObject; -use FireHub\Core\Type\Date\Zone; use Stringable; /** @@ -42,33 +41,13 @@ */ abstract public function value ():string; - /** - * ### Returns the timezone of the date and time value - * @since 1.0.0 - * - * @return \FireHub\Core\Type\Date\Zone The timezone of the date and time value. - */ - abstract public function zone ():Zone; - - /** - * ### Returns a new instance with the specified timezone - * @since 1.0.0 - * - * @param \FireHub\Core\Type\Date\Zone $zone

- * The timezone to set. - *

- * - * @return static The new instance with provided timezone. - */ - abstract public function withZone (Zone $zone):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\Temporal\Time::value() To get the string value. + * @uses \FireHub\Core\Type\Temporal\DateTime::value() To get the string value. * * @return TValue The string representation of the value. */ diff --git a/src/Type/Temporal/Timezone.php b/src/Type/Temporal/Timezone.php new file mode 100644 index 0000000..ef65739 --- /dev/null +++ b/src/Type/Temporal/Timezone.php @@ -0,0 +1,58 @@ + + * @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\Temporal; + +use FireHub\Core\Type\ValueObject; +use Stringable; + +/** + * ### Represents a timezone value + * + * The Timezone value object represents either a named timezone identified by an IANA timezone identifier or a fixed + * UTC offset. + * + * A named timezone is represented by predefined {@see Zone} value, while a fixed timezone is represented by its UTC + * offset in seconds. + * @since 1.0.0 + * + * @template TValue of non-empty-string|\FireHub\Core\Type\Date\Zone::* + * + * @extends \FireHub\Core\Type\ValueObject + */ +abstract readonly class Timezone extends ValueObject implements Stringable { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():string; + + /** + * ### 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\Temporal\Timezone::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 5ee3d5900e90ac297f5832b70595d8276e457b52 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 25 Aug 2026 08:16:10 +0200 Subject: [PATCH 025/118] Update PHPDoc for `Timezone` to simplify `@template` annotation **Details:** - Removed the redundant reference to `\FireHub\Core\Type\Date\Zone::*` in the `@template` declaration within `Core-Standard/src/Type/Temporal/Timezone.php`. - Refined `TValue` to accept only `non-empty-string`, ensuring consistency and increased semantic clarity in the `Timezone` Value Object. This minor update enhances the accuracy and maintainability of type annotations, adhering to FireHub's principles of clarity and precision in code documentation. --- src/Type/Temporal/Timezone.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Type/Temporal/Timezone.php b/src/Type/Temporal/Timezone.php index ef65739..456a931 100644 --- a/src/Type/Temporal/Timezone.php +++ b/src/Type/Temporal/Timezone.php @@ -26,7 +26,7 @@ * offset in seconds. * @since 1.0.0 * - * @template TValue of non-empty-string|\FireHub\Core\Type\Date\Zone::* + * @template TValue of non-empty-string * * @extends \FireHub\Core\Type\ValueObject */ From cab6a3c3893664f8fec7615d3c9423f3979c5aa0 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 25 Aug 2026 09:23:55 +0200 Subject: [PATCH 026/118] Add `timezone` and `withTimezone` methods to `DateTime` contract **Details:** - Introduced `timezone(): Timezone` method to retrieve the timezone of the date-time value. - Added `withTimezone(Timezone $timezone): static` to return a new instance with a specified timezone. - Updated PHPDoc annotations for these methods, including detailed descriptions for improved clarity and usability. These changes enhance the `DateTime` Value Object by providing timezone-aware functionalities, aligning with FireHub's design principles of immutability, clarity, and extensibility. --- src/Type/Temporal/DateTime.php | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/src/Type/Temporal/DateTime.php b/src/Type/Temporal/DateTime.php index 9fa0b5e..b1c9331 100644 --- a/src/Type/Temporal/DateTime.php +++ b/src/Type/Temporal/DateTime.php @@ -34,6 +34,14 @@ */ abstract readonly class DateTime extends ValueObject implements Stringable { + /** + * ### Returns the timezone of the date and time value + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Temporal\Timezone The timezone of the date and time value. + */ + abstract public function timezone ():Timezone; + /** * @inheritDoc * @@ -41,6 +49,18 @@ */ abstract public function value ():string; + /** + * ### Returns a new instance with the specified timezone + * @since 1.0.0 + * + * @param \FireHub\Core\Type\Temporal\Timezone $timezone

+ * The timezone to set. + *

+ * + * @return static The new instance with provided timezone. + */ + abstract public function withTimezone (Timezone $timezone):static; + /** * ### Returns the string representation of the value * From 24b824d13ded7e0057e491ed1bf6dc5bb910e356 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 25 Aug 2026 09:33:46 +0200 Subject: [PATCH 027/118] Update PHPDoc for `DateTime::timezone` and `DateTime::withTimezone` contract - **Details**: - Refined return type for `timezone()` to `Timezone` in `DateTime` class for increased precision. - Updated parameter type for `withTimezone()` to enforce `Timezone`, ensuring stricter type safety. - Improved PHPDoc clarity, aligning annotations with FireHub's standards of precision and readability. This change improves the accuracy and maintainability of type annotations in the `DateTime` contract, adhering to FireHub's principles of clarity, precision, and semantic consistency. --- src/Type/Temporal/DateTime.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Type/Temporal/DateTime.php b/src/Type/Temporal/DateTime.php index b1c9331..a50447d 100644 --- a/src/Type/Temporal/DateTime.php +++ b/src/Type/Temporal/DateTime.php @@ -38,7 +38,7 @@ * ### Returns the timezone of the date and time value * @since 1.0.0 * - * @return \FireHub\Core\Type\Temporal\Timezone The timezone of the date and time value. + * @return \FireHub\Core\Type\Temporal\Timezone The timezone of the date and time value. */ abstract public function timezone ():Timezone; @@ -53,7 +53,7 @@ abstract public function value ():string; * ### Returns a new instance with the specified timezone * @since 1.0.0 * - * @param \FireHub\Core\Type\Temporal\Timezone $timezone

+ * @param \FireHub\Core\Type\Temporal\Timezone $timezone

* The timezone to set. *

* From 99f2e04d3cf8f55594cc060f9564f1fef4530298 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 25 Aug 2026 12:21:47 +0200 Subject: [PATCH 028/118] Add `Country` enum to define recognized world countries in the Geo model **Details**: - Introduced the `Country` enum in `Core-Standard/src/Type/Geo/Country.php` to represent globally recognized countries in the FireHub Core. - Implements the `M49` interface to provide ISO-compliant numeric codes for each country, ensuring alignment with international standards. - Added methods: - `code(): string` - Returns the corresponding numeric M49 code for each country. - `parent(): M49` - Maps countries to their respective sub-regions for hierarchical geographic classification. - PHP 8.1 native enum feature utilized with `strict_types` declaration for enhanced type safety. This addition provides a robust, immutable, and standard-compliant representation of countries for geographic operations, adhering to FireHub's principles of precision, clarity, and extensibility. --- src/Boundary/Type/Geo/M49.php | 48 + src/Type/Geo/Continent.php | 121 ++ src/Type/Geo/Continent/Geological.php | 58 + src/Type/Geo/Continent/Landmass.php | 48 + .../Geo/Continent/PhysiographicRegion.php | 53 + src/Type/Geo/Country.php | 1636 +++++++++++++++++ src/Type/Geo/IntermediateRegion.php | 99 + src/Type/Geo/Ocean.php | 51 + src/Type/Geo/Region.php | 88 + src/Type/Geo/SubRegion.php | 165 ++ src/Type/Geo/World.php | 58 + 11 files changed, 2425 insertions(+) create mode 100644 src/Boundary/Type/Geo/M49.php create mode 100644 src/Type/Geo/Continent.php create mode 100644 src/Type/Geo/Continent/Geological.php create mode 100644 src/Type/Geo/Continent/Landmass.php create mode 100644 src/Type/Geo/Continent/PhysiographicRegion.php create mode 100644 src/Type/Geo/Country.php create mode 100644 src/Type/Geo/IntermediateRegion.php create mode 100644 src/Type/Geo/Ocean.php create mode 100644 src/Type/Geo/Region.php create mode 100644 src/Type/Geo/SubRegion.php create mode 100644 src/Type/Geo/World.php diff --git a/src/Boundary/Type/Geo/M49.php b/src/Boundary/Type/Geo/M49.php new file mode 100644 index 0000000..213a337 --- /dev/null +++ b/src/Boundary/Type/Geo/M49.php @@ -0,0 +1,48 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\Geo; + +/** + * ### Defines the United Nations M49 geographic classification contract + * + * The M49 interface defines the common contract for geographic entities classified according to the United Nations + * M49 standard. + * + * It provides a consistent interface for accessing M49 geographic codes and hierarchical relationships between + * regions, subregions, intermediate regions, and countries. + * @since 1.0.0 + */ +interface M49 { + + /** + * ### Three-digit country code + * + * Three-digit country codes that are identical to those developed and maintained by the United Nations + * Statistics Division, with the advantage of script (writing system) independence, and hence useful for people + * or systems using non-Latin scripts. + * @since 1.0.0 + * + * @return numeric-string Three-digit country code. + */ + public function code ():string; + + /** + * ### Get parent region + * @since 1.0.0 + * + * @return null|self Parent region or null if the entity is a country. + */ + public function parent ():?self; + +} \ No newline at end of file diff --git a/src/Type/Geo/Continent.php b/src/Type/Geo/Continent.php new file mode 100644 index 0000000..ee8dc52 --- /dev/null +++ b/src/Type/Geo/Continent.php @@ -0,0 +1,121 @@ + + * @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.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +use FireHub\Core\Type\Geo\Continent\ { + Geological, Landmass, PhysiographicRegion +}; + +/** + * ### Defines the world's continents + * + * The Continent enum represents the recognized continents of the world within the FireHub Core geographic type + * system. + * + * It provides a strongly typed representation of continental geographic regions without coupling the Core layer + * to external geographic codes, databases, or runtime-specific implementations. + * @since 1.0.0 + */ +enum Continent:string { + + /** + * @since 1.0.0 + */ + case AFRICA = 'Africa'; + + /** + * @since 1.0.0 + */ + case ANTARCTICA = 'Antarctica'; + + /** + * @since 1.0.0 + */ + case ASIA = 'Asia'; + + /** + * @since 1.0.0 + */ + case AUSTRALIA = 'Australia'; + + /** + * @since 1.0.0 + */ + case EUROPE = 'Europe'; + + /** + * @since 1.0.0 + */ + case NORTH_AMERICA = 'North America'; + + /** + * @since 1.0.0 + */ + case SOUTH_AMERICA = 'South America'; + + /** + * ## Gets a continent as a geological continent + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Geo\Continent\Geological Geological continent. + */ + public function geological ():Geological { + + return match ($this) { + self::AFRICA => Geological::AFRICA, + self::ANTARCTICA => Geological::ANTARCTICA, + self::ASIA, self::EUROPE => Geological::EURASIA, + self::AUSTRALIA => Geological::AUSTRALIA, + self::NORTH_AMERICA => Geological::NORTH_AMERICA, + self::SOUTH_AMERICA => Geological::SOUTH_AMERICA + }; + + } + + /** + * ## Gets a continent as a physiographic region + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Geo\Continent\PhysiographicRegion Physiographic region. + */ + public function physiographicRegion ():PhysiographicRegion { + + return match ($this) { + self::AFRICA => PhysiographicRegion::AFRICA, + self::ANTARCTICA => PhysiographicRegion::ANTARCTICA, + self::ASIA, self::EUROPE => PhysiographicRegion::EURASIA, + self::AUSTRALIA => PhysiographicRegion::AUSTRALIA, + self::NORTH_AMERICA, self::SOUTH_AMERICA => PhysiographicRegion::AMERICA + }; + + } + + /** + * ## Gets a continent as a landmass + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Geo\Continent\Landmass Landmass. + */ + public function landmass ():Landmass { + + return match ($this) { + self::AFRICA, self::ASIA, self::EUROPE => Landmass::AFRO_EURASIA, + self::ANTARCTICA => Landmass::ANTARCTICA, + self::AUSTRALIA => Landmass::AUSTRALIA, + self::NORTH_AMERICA, self::SOUTH_AMERICA => Landmass::AMERICA + }; + + } + +} \ No newline at end of file diff --git a/src/Type/Geo/Continent/Geological.php b/src/Type/Geo/Continent/Geological.php new file mode 100644 index 0000000..fa1ec50 --- /dev/null +++ b/src/Type/Geo/Continent/Geological.php @@ -0,0 +1,58 @@ + + * @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.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo\Continent; + +/** + * ### Defines the geological continental divisions of the world + * + * The Geological enum represents major geological divisions used to classify continents and their underlying + * continental structures within the FireHub Core geographic type system. + * + * It provides a strongly typed representation of geological continental groupings independently of political, + * cultural, or administrative boundaries. + * @since 1.0.0 + */ +enum Geological:string { + + /** + * @since 1.0.0 + */ + case AFRICA = 'Africa'; + + /** + * @since 1.0.0 + */ + case ANTARCTICA = 'Antarctica'; + + /** + * @since 1.0.0 + */ + case AUSTRALIA = 'Australia'; + + /** + * @since 1.0.0 + */ + case EURASIA = 'Eurasia'; + + /** + * @since 1.0.0 + */ + case NORTH_AMERICA = 'North America'; + + /** + * @since 1.0.0 + */ + case SOUTH_AMERICA = 'South America'; + +} \ No newline at end of file diff --git a/src/Type/Geo/Continent/Landmass.php b/src/Type/Geo/Continent/Landmass.php new file mode 100644 index 0000000..26c55e0 --- /dev/null +++ b/src/Type/Geo/Continent/Landmass.php @@ -0,0 +1,48 @@ + + * @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.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo\Continent; + +/** + * ### Defines the major landmasses of the world + * + * The Landmass enum represents major continuous land areas used to classify continents according to their physical + * connection to other continental land areas within the FireHub Core geographic type system. + * + * It provides a strongly typed representation of landmass groupings independently of political, cultural, or + * administrative boundaries. + * @since 1.0.0 + */ +enum Landmass :string { + + /** + * @since 1.0.0 + */ + case AFRO_EURASIA = 'Afro-Eurasia'; + + /** + * @since 1.0.0 + */ + case AMERICA = 'America'; + + /** + * @since 1.0.0 + */ + case ANTARCTICA = 'Antarctica'; + + /** + * @since 1.0.0 + */ + case AUSTRALIA = 'Australia'; + +} \ No newline at end of file diff --git a/src/Type/Geo/Continent/PhysiographicRegion.php b/src/Type/Geo/Continent/PhysiographicRegion.php new file mode 100644 index 0000000..166175b --- /dev/null +++ b/src/Type/Geo/Continent/PhysiographicRegion.php @@ -0,0 +1,53 @@ + + * @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.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo\Continent; + +/** + * ### Defines the major physiographic regions of the world + * + * The PhysiographicRegion enum represents major physical geographic regions used to classify continents according to + * their shared physical and geographic characteristics within the FireHub Core geographic type system. + * + * It provides a strongly typed representation of physiographic regional groupings independently of political, + * cultural, or administrative boundaries. + * @since 1.0.0 + */ +enum PhysiographicRegion:string { + + /** + * @since 1.0.0 + */ + case AFRICA = 'Africa'; + + /** + * @since 1.0.0 + */ + case AMERICA = 'America'; + + /** + * @since 1.0.0 + */ + case ANTARCTICA = 'Antarctica'; + + /** + * @since 1.0.0 + */ + case AUSTRALIA = 'Australia'; + + /** + * @since 1.0.0 + */ + case EURASIA = 'Eurasia'; + +} \ No newline at end of file diff --git a/src/Type/Geo/Country.php b/src/Type/Geo/Country.php new file mode 100644 index 0000000..9038b93 --- /dev/null +++ b/src/Type/Geo/Country.php @@ -0,0 +1,1636 @@ + + * @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.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +use FireHub\Core\Boundary\Type\Geo\M49; + +/** + * ### Defines the world's countries + * + * The Country enum represents the recognized countries of the world within the FireHub Core geographic type + * system. + * + * It provides a strongly typed representation of countries independently of political, cultural, or administrative + * data that may change over time. + * @since 1.0.0 + */ +enum Country:string implements M49 { + + /** + * @since 1.0.0 + */ + case AFGHANISTAN = 'Afghanistan'; + + /** + * @since 1.0.0 + */ + case ALAND_ISLANDS = 'Åland Islands'; + + /** + * @since 1.0.0 + */ + case ALBANIA = 'Albania'; + + /** + * @since 1.0.0 + */ + case ALGERIA = 'Algeria'; + + /** + * @since 1.0.0 + */ + case AMERICAN_SAMOA = 'American Samoa'; + + /** + * @since 1.0.0 + */ + case ANDORRA = 'Andorra'; + + /** + * @since 1.0.0 + */ + case ANGOLA = 'Angola'; + + /** + * @since 1.0.0 + */ + case ANGUILLA = 'Anguilla'; + + /** + * @since 1.0.0 + */ + case ANTARCTICA = 'Antarctica'; + + /** + * @since 1.0.0 + */ + case ANTIGUA_AND_BARBUDA = 'Antigua and Barbuda'; + + /** + * @since 1.0.0 + */ + case ARGENTINA = 'Argentina'; + + /** + * @since 1.0.0 + */ + case ARMENIA = 'Armenia'; + + /** + * @since 1.0.0 + */ + case ARUBA = 'Aruba'; + + /** + * @since 1.0.0 + */ + case AUSTRALIA = 'Australia'; + + /** + * @since 1.0.0 + */ + case AUSTRIA = 'Austria'; + + /** + * @since 1.0.0 + */ + case AZERBAIJAN = 'Azerbaijan'; + + /** + * @since 1.0.0 + */ + case BAHAMAS = 'Bahamas'; + + /** + * @since 1.0.0 + */ + case BAHRAIN = 'Bahrain'; + + /** + * @since 1.0.0 + */ + case BANGLADESH = 'Bangladesh'; + + /** + * @since 1.0.0 + */ + case BARBADOS = 'Barbados'; + + /** + * @since 1.0.0 + */ + case BELARUS = 'Belarus'; + + /** + * @since 1.0.0 + */ + case BELGIUM = 'Belgium'; + + /** + * @since 1.0.0 + */ + case BELIZE = 'Belize'; + + /** + * @since 1.0.0 + */ + case BENIN = 'Benin'; + + /** + * @since 1.0.0 + */ + case BERMUDA = 'Bermuda'; + + /** + * @since 1.0.0 + */ + case BHUTAN = 'Bhutan'; + + /** + * @since 1.0.0 + */ + case BOLIVIA_PLURINATIONAL_STATE_OF = 'Bolivia, Plurinational State of'; + + /** + * @since 1.0.0 + */ + case BONAIRE_SINT_EUSTATIUS_AND_SABA = 'Bonaire, Sint Eustatius and Saba'; + + /** + * @since 1.0.0 + */ + case BOSNIA_AND_HERZEGOVINA = 'Bosnia and Herzegovina'; + + /** + * @since 1.0.0 + */ + case BOTSWANA = 'Botswana'; + + /** + * @since 1.0.0 + */ + case BOUVET_ISLAND = 'Bouvet Island'; + + /** + * @since 1.0.0 + */ + case BRAZIL = 'Brazil'; + + /** + * @since 1.0.0 + */ + case BRITISH_INDIAN_OCEAN_TERRITORY = 'British Indian Ocean Territory'; + + /** + * @since 1.0.0 + */ + case BRUNEI_DARUSSALAM = 'Brunei Darussalam'; + + /** + * @since 1.0.0 + */ + case BULGARIA = 'Bulgaria'; + + /** + * @since 1.0.0 + */ + case BURKINA_FASO = 'Burkina Faso'; + + /** + * @since 1.0.0 + */ + case BURUNDI = 'Burundi'; + + /** + * @since 1.0.0 + */ + case CABO_VERDE = 'Cabo Verde'; + + /** + * @since 1.0.0 + */ + case CAMBODIA = 'Cambodia'; + + /** + * @since 1.0.0 + */ + case CAMEROON = 'Cameroon'; + + /** + * @since 1.0.0 + */ + case CANADA = 'Canada'; + + /** + * @since 1.0.0 + */ + case CAYMAN_ISLANDS = 'Cayman Islands'; + + /** + * @since 1.0.0 + */ + case CENTRAL_AFRICAN_REPUBLIC = 'Central African Republic'; + + /** + * @since 1.0.0 + */ + case CHAD = 'Chad'; + + /** + * @since 1.0.0 + */ + case CHILE = 'Chile'; + + /** + * @since 1.0.0 + */ + case CHINA = 'China'; + + /** + * @since 1.0.0 + */ + case CHRISTMAS_ISLAND = 'Christmas Island'; + + /** + * @since 1.0.0 + */ + case COCOS_KEELING_ISLANDS = 'Cocos (Keeling) Islands'; + + /** + * @since 1.0.0 + */ + case COLOMBIA = 'Colombia'; + + /** + * @since 1.0.0 + */ + case COMOROS = 'Comoros'; + + /** + * @since 1.0.0 + */ + case CONGO = 'Congo'; + + /** + * @since 1.0.0 + */ + case CONGO_DEMOCRATIC_REPUBLIC_OF_THE = 'Congo, Democratic Republic of the'; + + /** + * @since 1.0.0 + */ + case COOK_ISLANDS = 'Cook Islands'; + + /** + * @since 1.0.0 + */ + case COSTA_RICA = 'Costa Rica'; + + /** + * @since 1.0.0 + */ + case COTE_D_IVOIRE = "Côte d'Ivoire"; + + /** + * @since 1.0.0 + */ + case CROATIA = 'Croatia'; + + /** + * @since 1.0.0 + */ + case CUBA = 'Cuba'; + + /** + * @since 1.0.0 + */ + case CURACAO = 'Curaçao'; + + /** + * @since 1.0.0 + */ + case CYPRUS = 'Cyprus'; + + /** + * @since 1.0.0 + */ + case CZECHIA = 'Czechia'; + + /** + * @since 1.0.0 + */ + case DENMARK = 'Denmark'; + + /** + * @since 1.0.0 + */ + case DJIBOUTI = 'Djibouti'; + + /** + * @since 1.0.0 + */ + case DOMINICA = 'Dominica'; + + /** + * @since 1.0.0 + */ + case DOMINICAN_REPUBLIC = 'Dominican Republic'; + + /** + * @since 1.0.0 + */ + case ECUADOR = 'Ecuador'; + + /** + * @since 1.0.0 + */ + case EGYPT = 'Egypt'; + + /** + * @since 1.0.0 + */ + case EL_SALVADOR = 'El Salvador'; + + /** + * @since 1.0.0 + */ + case EQUATORIAL_GUINEA = 'Equatorial Guinea'; + + /** + * @since 1.0.0 + */ + case ERITREA = 'Eritrea'; + + /** + * @since 1.0.0 + */ + case ESTONIA = 'Estonia'; + + /** + * @since 1.0.0 + */ + case ESWATINI = 'Eswatini'; + + /** + * @since 1.0.0 + */ + case ETHIOPIA = 'Ethiopia'; + + /** + * @since 1.0.0 + */ + case FALKLAND_ISLANDS_MALVINAS = 'Falkland Islands (Malvinas)'; + + /** + * @since 1.0.0 + */ + case FAROE_ISLANDS = 'Faroe Islands'; + + /** + * @since 1.0.0 + */ + case FIJI = 'Fiji'; + + /** + * @since 1.0.0 + */ + case FINLAND = 'Finland'; + + /** + * @since 1.0.0 + */ + case FRANCE = 'France'; + + /** + * @since 1.0.0 + */ + case FRENCH_GUIANA = 'French Guiana'; + + /** + * @since 1.0.0 + */ + case FRENCH_POLYNESIA = 'French Polynesia'; + + /** + * @since 1.0.0 + */ + case FRENCH_SOUTHERN_TERRITORIES = 'French Southern Territories'; + + /** + * @since 1.0.0 + */ + case GABON = 'Gabon'; + + /** + * @since 1.0.0 + */ + case GAMBIA = 'Gambia'; + + /** + * @since 1.0.0 + */ + case GEORGIA = 'Georgia'; + + /** + * @since 1.0.0 + */ + case GERMANY = 'Germany'; + + /** + * @since 1.0.0 + */ + case GHANA = 'Ghana'; + + /** + * @since 1.0.0 + */ + case GIBRALTAR = 'Gibraltar'; + + /** + * @since 1.0.0 + */ + case GREECE = 'Greece'; + + /** + * @since 1.0.0 + */ + case GREENLAND = 'Greenland'; + + /** + * @since 1.0.0 + */ + case GRENADA = 'Grenada'; + + /** + * @since 1.0.0 + */ + case GUADELOUPE = 'Guadeloupe'; + + /** + * @since 1.0.0 + */ + case GUAM = 'Guam'; + + /** + * @since 1.0.0 + */ + case GUATEMALA = 'Guatemala'; + + /** + * @since 1.0.0 + */ + case GUERNSEY = 'Guernsey'; + + /** + * @since 1.0.0 + */ + case GUINEA = 'Guinea'; + + /** + * @since 1.0.0 + */ + case GUINEA_BISSAU = 'Guinea-Bissau'; + + /** + * @since 1.0.0 + */ + case GUYANA = 'Guyana'; + + /** + * @since 1.0.0 + */ + case HAITI = 'Haiti'; + + /** + * @since 1.0.0 + */ + case HEARD_ISLAND_AND_MCDONALD_ISLANDS = 'Heard Island and McDonald Islands'; + + /** + * @since 1.0.0 + */ + case HOLY_SEE = 'Holy See'; + + /** + * @since 1.0.0 + */ + case HONDURAS = 'Honduras'; + + /** + * @since 1.0.0 + */ + case HONG_KONG = 'Hong Kong'; + + /** + * @since 1.0.0 + */ + case HUNGARY = 'Hungary'; + + /** + * @since 1.0.0 + */ + case ICELAND = 'Iceland'; + + /** + * @since 1.0.0 + */ + case INDIA = 'India'; + + /** + * @since 1.0.0 + */ + case INDONESIA = 'Indonesia'; + + /** + * @since 1.0.0 + */ + case IRAN_ISLAMIC_REPUBLIC_OF = 'Iran, Islamic Republic of'; + + /** + * @since 1.0.0 + */ + case IRAQ = 'Iraq'; + + /** + * @since 1.0.0 + */ + case IRELAND = 'Ireland'; + + /** + * @since 1.0.0 + */ + case ISLE_OF_MAN = 'Isle of Man'; + + /** + * @since 1.0.0 + */ + case ISRAEL = 'Israel'; + + /** + * @since 1.0.0 + */ + case ITALY = 'Italy'; + + /** + * @since 1.0.0 + */ + case JAMAICA = 'Jamaica'; + + /** + * @since 1.0.0 + */ + case JAPAN = 'Japan'; + + /** + * @since 1.0.0 + */ + case JERSEY = 'Jersey'; + + /** + * @since 1.0.0 + */ + case JORDAN = 'Jordan'; + + /** + * @since 1.0.0 + */ + case KAZAKHSTAN = 'Kazakhstan'; + + /** + * @since 1.0.0 + */ + case KENYA = 'Kenya'; + + /** + * @since 1.0.0 + */ + case KIRIBATI = 'Kiribati'; + + /** + * @since 1.0.0 + */ + case KOREA_DEMOCRATIC_PEOPLES_REPUBLIC_OF = "Korea, Democratic People's Republic of"; + + /** + * @since 1.0.0 + */ + case KOREA_REPUBLIC_OF = 'Korea, Republic of'; + + /** + * @since 1.0.0 + */ + case KOSOVO = 'Kosovo'; + + /** + * @since 1.0.0 + */ + case KUWAIT = 'Kuwait'; + + /** + * @since 1.0.0 + */ + case KYRGYZSTAN = 'Kyrgyzstan'; + + /** + * @since 1.0.0 + */ + case LAO_PEOPLES_DEMOCRATIC_REPUBLIC = "Lao People's Democratic Republic"; + + /** + * @since 1.0.0 + */ + case LATVIA = 'Latvia'; + + /** + * @since 1.0.0 + */ + case LEBANON = 'Lebanon'; + + /** + * @since 1.0.0 + */ + case LESOTHO = 'Lesotho'; + + /** + * @since 1.0.0 + */ + case LIBERIA = 'Liberia'; + + /** + * @since 1.0.0 + */ + case LIBYA = 'Libya'; + + /** + * @since 1.0.0 + */ + case LIECHTENSTEIN = 'Liechtenstein'; + + /** + * @since 1.0.0 + */ + case LITHUANIA = 'Lithuania'; + + /** + * @since 1.0.0 + */ + case LUXEMBOURG = 'Luxembourg'; + + /** + * @since 1.0.0 + */ + case MACAO = 'Macao'; + + /** + * @since 1.0.0 + */ + case MADAGASCAR = 'Madagascar'; + + /** + * @since 1.0.0 + */ + case MALAWI = 'Malawi'; + + /** + * @since 1.0.0 + */ + case MALAYSIA = 'Malaysia'; + + /** + * @since 1.0.0 + */ + case MALDIVES = 'Maldives'; + + /** + * @since 1.0.0 + */ + case MALI = 'Mali'; + + /** + * @since 1.0.0 + */ + case MALTA = 'Malta'; + + /** + * @since 1.0.0 + */ + case MARSHALL_ISLANDS = 'Marshall Islands'; + + /** + * @since 1.0.0 + */ + case MARTINIQUE = 'Martinique'; + + /** + * @since 1.0.0 + */ + case MAURITANIA = 'Mauritania'; + + /** + * @since 1.0.0 + */ + case MAURITIUS = 'Mauritius'; + + /** + * @since 1.0.0 + */ + case MAYOTTE = 'Mayotte'; + + /** + * @since 1.0.0 + */ + case MEXICO = 'Mexico'; + + /** + * @since 1.0.0 + */ + case MICRONESIA_FEDERATED_STATES_OF = 'Micronesia, Federated States of'; + + /** + * @since 1.0.0 + */ + case MOLDOVA_REPUBLIC_OF = 'Moldova, Republic of'; + + /** + * @since 1.0.0 + */ + case MONACO = 'Monaco'; + + /** + * @since 1.0.0 + */ + case MONGOLIA = 'Mongolia'; + + /** + * @since 1.0.0 + */ + case MONTENEGRO = 'Montenegro'; + + /** + * @since 1.0.0 + */ + case MONTSERRAT = 'Montserrat'; + + /** + * @since 1.0.0 + */ + case MOROCCO = 'Morocco'; + + /** + * @since 1.0.0 + */ + case MOZAMBIQUE = 'Mozambique'; + + /** + * @since 1.0.0 + */ + case MYANMAR = 'Myanmar'; + + /** + * @since 1.0.0 + */ + case NAMIBIA = 'Namibia'; + + /** + * @since 1.0.0 + */ + case NAURU = 'Nauru'; + + /** + * @since 1.0.0 + */ + case NEPAL = 'Nepal'; + + /** + * @since 1.0.0 + */ + case NETHERLANDS_KINGDOM_OF_THE = 'Netherlands, Kingdom of the'; + + /** + * @since 1.0.0 + */ + case NEW_CALEDONIA = 'New Caledonia'; + + /** + * @since 1.0.0 + */ + case NEW_ZEALAND = 'New Zealand'; + + /** + * @since 1.0.0 + */ + case NICARAGUA = 'Nicaragua'; + + /** + * @since 1.0.0 + */ + case NIGER = 'Niger'; + + /** + * @since 1.0.0 + */ + case NIGERIA = 'Nigeria'; + + /** + * @since 1.0.0 + */ + case NIUE = 'Niue'; + + /** + * @since 1.0.0 + */ + case NORFOLK_ISLAND = 'Norfolk Island'; + + /** + * @since 1.0.0 + */ + case NORTH_MACEDONIA = 'North Macedonia'; + + /** + * @since 1.0.0 + */ + case NORTHERN_MARIANA_ISLANDS = 'Northern Mariana Islands'; + + /** + * @since 1.0.0 + */ + case NORWAY = 'Norway'; + + /** + * @since 1.0.0 + */ + case OMAN = 'Oman'; + + /** + * @since 1.0.0 + */ + case PAKISTAN = 'Pakistan'; + + /** + * @since 1.0.0 + */ + case PALAU = 'Palau'; + + /** + * @since 1.0.0 + */ + case PALESTINE_STATE_OF = 'Palestine, State of'; + + /** + * @since 1.0.0 + */ + case PANAMA = 'Panama'; + + /** + * @since 1.0.0 + */ + case PAPUA_NEW_GUINEA = 'Papua New Guinea'; + + /** + * @since 1.0.0 + */ + case PARAGUAY = 'Paraguay'; + + /** + * @since 1.0.0 + */ + case PERU = 'Peru'; + + /** + * @since 1.0.0 + */ + case PHILIPPINES = 'Philippines'; + + /** + * @since 1.0.0 + */ + case PITCAIRN = 'Pitcairn'; + + /** + * @since 1.0.0 + */ + case POLAND = 'Poland'; + + /** + * @since 1.0.0 + */ + case PORTUGAL = 'Portugal'; + + /** + * @since 1.0.0 + */ + case PUERTO_RICO = 'Puerto Rico'; + + /** + * @since 1.0.0 + */ + case QATAR = 'Qatar'; + + /** + * @since 1.0.0 + */ + case REUNION = 'Réunion'; + + /** + * @since 1.0.0 + */ + case ROMANIA = 'Romania'; + + /** + * @since 1.0.0 + */ + case RUSSIAN_FEDERATION = 'Russian Federation'; + + /** + * @since 1.0.0 + */ + case RWANDA = 'Rwanda'; + + /** + * @since 1.0.0 + */ + case SAINT_BARTHELEMY = 'Saint Barthélemy'; + + /** + * @since 1.0.0 + */ + case SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA = 'Saint Helena, Ascension and Tristan da Cunha'; + + /** + * @since 1.0.0 + */ + case SAINT_KITTS_AND_NEVIS = 'Saint Kitts and Nevis'; + + /** + * @since 1.0.0 + */ + case SAINT_LUCIA = 'Saint Lucia'; + + /** + * @since 1.0.0 + */ + case SAINT_MARTIN_FRENCH_PART = 'Saint Martin (French part)'; + + /** + * @since 1.0.0 + */ + case SAINT_PIERRE_AND_MIQUELON = 'Saint Pierre and Miquelon'; + + /** + * @since 1.0.0 + */ + case SAINT_VINCENT_AND_THE_GRENADINES = 'Saint Vincent and the Grenadines'; + + /** + * @since 1.0.0 + */ + case SAMOA = 'Samoa'; + + /** + * @since 1.0.0 + */ + case SAN_MARINO = 'San Marino'; + + /** + * @since 1.0.0 + */ + case SAO_TOME_AND_PRINCIPE = 'Sao Tome and Principe'; + + /** + * @since 1.0.0 + */ + case SAUDI_ARABIA = 'Saudi Arabia'; + + /** + * @since 1.0.0 + */ + case SENEGAL = 'Senegal'; + + /** + * @since 1.0.0 + */ + case SERBIA = 'Serbia'; + + /** + * @since 1.0.0 + */ + case SEYCHELLES = 'Seychelles'; + + /** + * @since 1.0.0 + */ + case SIERRA_LEONE = 'Sierra Leone'; + + /** + * @since 1.0.0 + */ + case SINGAPORE = 'Singapore'; + + /** + * @since 1.0.0 + */ + case SINT_MAARTEN_DUTCH_PART = 'Sint Maarten (Dutch part)'; + + /** + * @since 1.0.0 + */ + case SLOVAKIA = 'Slovakia'; + + /** + * @since 1.0.0 + */ + case SLOVENIA = 'Slovenia'; + + /** + * @since 1.0.0 + */ + case SOLOMON_ISLANDS = 'Solomon Islands'; + + /** + * @since 1.0.0 + */ + case SOMALIA = 'Somalia'; + + /** + * @since 1.0.0 + */ + case SOUTH_AFRICA = 'South Africa'; + + /** + * @since 1.0.0 + */ + case SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS = 'South Georgia and the South Sandwich Islands'; + + /** + * @since 1.0.0 + */ + case SOUTH_SUDAN = 'South Sudan'; + + /** + * @since 1.0.0 + */ + case SPAIN = 'Spain'; + + /** + * @since 1.0.0 + */ + case SRI_LANKA = 'Sri Lanka'; + + /** + * @since 1.0.0 + */ + case SUDAN = 'Sudan'; + + /** + * @since 1.0.0 + */ + case SURINAME = 'Suriname'; + + /** + * @since 1.0.0 + */ + case SVALBARD_AND_JAN_MAYEN = 'Svalbard and Jan Mayen'; + + /** + * @since 1.0.0 + */ + case SWEDEN = 'Sweden'; + + /** + * @since 1.0.0 + */ + case SWITZERLAND = 'Switzerland'; + + /** + * @since 1.0.0 + */ + case SYRIAN_ARAB_REPUBLIC = 'Syrian Arab Republic'; + + /** + * @since 1.0.0 + */ + case TAIWAN_PROVINCE_OF_CHINA = 'Taiwan, Province of China'; + + /** + * @since 1.0.0 + */ + case TAJIKISTAN = 'Tajikistan'; + + /** + * @since 1.0.0 + */ + case TANZANIA_UNITED_REPUBLIC_OF = 'Tanzania, United Republic of'; + + /** + * @since 1.0.0 + */ + case THAILAND = 'Thailand'; + + /** + * @since 1.0.0 + */ + case TIMOR_LESTE = 'Timor-Leste'; + + /** + * @since 1.0.0 + */ + case TOGO = 'Togo'; + + /** + * @since 1.0.0 + */ + case TOKELAU = 'Tokelau'; + + /** + * @since 1.0.0 + */ + case TONGA = 'Tonga'; + + /** + * @since 1.0.0 + */ + case TRINIDAD_AND_TOBAGO = 'Trinidad and Tobago'; + + /** + * @since 1.0.0 + */ + case TUNISIA = 'Tunisia'; + + /** + * @since 1.0.0 + */ + case TURKIYE = 'Türkiye'; + + /** + * @since 1.0.0 + */ + case TURKMENISTAN = 'Turkmenistan'; + + /** + * @since 1.0.0 + */ + case TURKS_AND_CAICOS_ISLANDS = 'Turks and Caicos Islands'; + + /** + * @since 1.0.0 + */ + case TUVALU = 'Tuvalu'; + + /** + * @since 1.0.0 + */ + case UGANDA = 'Uganda'; + + /** + * @since 1.0.0 + */ + case UKRAINE = 'Ukraine'; + + /** + * @since 1.0.0 + */ + case UNITED_ARAB_EMIRATES = 'United Arab Emirates'; + + /** + * @since 1.0.0 + */ + case UNITED_KINGDOM_OF_GREAT_BRITAIN_AND_NORTHERN_IRELAND = 'United Kingdom of Great Britain and Northern Ireland'; + + /** + * @since 1.0.0 + */ + case UNITED_STATES_MINOR_OUTLYING_ISLANDS = 'United States Minor Outlying Islands'; + + /** + * @since 1.0.0 + */ + case UNITED_STATES_OF_AMERICA = 'United States of America'; + + /** + * @since 1.0.0 + */ + case URUGUAY = 'Uruguay'; + + /** + * @since 1.0.0 + */ + case UZBEKISTAN = 'Uzbekistan'; + + /** + * @since 1.0.0 + */ + case VANUATU = 'Vanuatu'; + + /** + * @since 1.0.0 + */ + case VENEZUELA_BOLIVARIAN_REPUBLIC_OF = 'Venezuela, Bolivarian Republic of'; + + /** + * @since 1.0.0 + */ + case VIET_NAM = 'Viet Nam'; + + /** + * @since 1.0.0 + */ + case VIRGIN_ISLANDS_BRITISH = 'Virgin Islands (British)'; + + /** + * @since 1.0.0 + */ + case VIRGIN_ISLANDS_US = 'Virgin Islands (U.S.)'; + + /** + * @since 1.0.0 + */ + case WALLIS_AND_FUTUNA = 'Wallis and Futuna'; + + /** + * @since 1.0.0 + */ + case WESTERN_SAHARA = 'Western Sahara'; + + /** + * @since 1.0.0 + */ + case YEMEN = 'Yemen'; + + /** + * @since 1.0.0 + */ + case ZAMBIA = 'Zambia'; + + /** + * @since 1.0.0 + */ + case ZIMBABWE = 'Zimbabwe'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function code ():string { + + return match ($this) { + self::AFGHANISTAN => '004', + self::ALAND_ISLANDS => '248', + self::ALBANIA => '008', + self::ALGERIA => '012', + self::AMERICAN_SAMOA => '016', + self::ANDORRA => '020', + self::ANGOLA => '024', + self::ANGUILLA => '660', + self::ANTARCTICA => '010', + self::ANTIGUA_AND_BARBUDA => '028', + self::ARGENTINA => '032', + self::ARMENIA => '051', + self::ARUBA => '533', + self::AUSTRALIA => '036', + self::AUSTRIA => '040', + self::AZERBAIJAN => '031', + self::BAHAMAS => '044', + self::BAHRAIN => '048', + self::BANGLADESH => '050', + self::BARBADOS => '052', + self::BELARUS => '112', + self::BELGIUM => '056', + self::BELIZE => '084', + self::BENIN => '204', + self::BERMUDA => '060', + self::BHUTAN => '064', + self::BOLIVIA_PLURINATIONAL_STATE_OF => '068', + self::BONAIRE_SINT_EUSTATIUS_AND_SABA => '535', + self::BOSNIA_AND_HERZEGOVINA => '070', + self::BOTSWANA => '072', + self::BOUVET_ISLAND => '074', + self::BRAZIL => '076', + self::BRITISH_INDIAN_OCEAN_TERRITORY => '086', + self::BRUNEI_DARUSSALAM => '096', + self::BULGARIA => '100', + self::BURKINA_FASO => '854', + self::BURUNDI => '108', + self::CABO_VERDE => '132', + self::CAMBODIA => '116', + self::CAMEROON => '120', + self::CANADA => '124', + self::CAYMAN_ISLANDS => '136', + self::CENTRAL_AFRICAN_REPUBLIC => '140', + self::CHAD => '148', + self::CHILE => '152', + self::CHINA => '156', + self::CHRISTMAS_ISLAND => '162', + self::COCOS_KEELING_ISLANDS => '166', + self::COLOMBIA => '170', + self::COMOROS => '174', + self::CONGO => '178', + self::CONGO_DEMOCRATIC_REPUBLIC_OF_THE => '180', + self::COOK_ISLANDS => '184', + self::COSTA_RICA => '188', + self::COTE_D_IVOIRE => '384', + self::CROATIA => '191', + self::CUBA => '192', + self::CURACAO => '531', + self::CYPRUS => '196', + self::CZECHIA => '203', + self::DENMARK => '208', + self::DJIBOUTI => '262', + self::DOMINICA => '212', + self::DOMINICAN_REPUBLIC => '214', + self::ECUADOR => '218', + self::EGYPT => '818', + self::EL_SALVADOR => '222', + self::EQUATORIAL_GUINEA => '226', + self::ERITREA => '232', + self::ESTONIA => '233', + self::ESWATINI => '748', + self::ETHIOPIA => '231', + self::FALKLAND_ISLANDS_MALVINAS => '238', + self::FAROE_ISLANDS => '234', + self::FIJI => '242', + self::FINLAND => '246', + self::FRANCE => '250', + self::FRENCH_GUIANA => '254', + self::FRENCH_POLYNESIA => '258', + self::FRENCH_SOUTHERN_TERRITORIES => '260', + self::GABON => '266', + self::GAMBIA => '270', + self::GEORGIA => '268', + self::GERMANY => '276', + self::GHANA => '288', + self::GIBRALTAR => '292', + self::GREECE => '300', + self::GREENLAND => '304', + self::GRENADA => '308', + self::GUADELOUPE => '312', + self::GUAM => '316', + self::GUATEMALA => '320', + self::GUERNSEY => '831', + self::GUINEA => '324', + self::GUINEA_BISSAU => '624', + self::GUYANA => '328', + self::HAITI => '332', + self::HEARD_ISLAND_AND_MCDONALD_ISLANDS => '334', + self::HOLY_SEE => '336', + self::HONDURAS => '340', + self::HONG_KONG => '344', + self::HUNGARY => '348', + self::ICELAND => '352', + self::INDIA => '356', + self::INDONESIA => '360', + self::IRAN_ISLAMIC_REPUBLIC_OF => '364', + self::IRAQ => '368', + self::IRELAND => '372', + self::ISLE_OF_MAN => '833', + self::ISRAEL => '376', + self::ITALY => '380', + self::JAMAICA => '388', + self::JAPAN => '392', + self::JERSEY => '832', + self::JORDAN => '400', + self::KAZAKHSTAN => '398', + self::KENYA => '404', + self::KIRIBATI => '296', + self::KOREA_DEMOCRATIC_PEOPLES_REPUBLIC_OF => '408', + self::KOREA_REPUBLIC_OF => '410', + self::KOSOVO => '412', + self::KUWAIT => '414', + self::KYRGYZSTAN => '417', + self::LAO_PEOPLES_DEMOCRATIC_REPUBLIC => '418', + self::LATVIA => '428', + self::LEBANON => '422', + self::LESOTHO => '426', + self::LIBERIA => '430', + self::LIBYA => '434', + self::LIECHTENSTEIN => '438', + self::LITHUANIA => '440', + self::LUXEMBOURG => '442', + self::MACAO => '446', + self::MADAGASCAR => '450', + self::MALAWI => '454', + self::MALAYSIA => '458', + self::MALDIVES => '462', + self::MALI => '466', + self::MALTA => '470', + self::MARSHALL_ISLANDS => '584', + self::MARTINIQUE => '474', + self::MAURITANIA => '478', + self::MAURITIUS => '480', + self::MAYOTTE => '175', + self::MEXICO => '484', + self::MICRONESIA_FEDERATED_STATES_OF => '583', + self::MOLDOVA_REPUBLIC_OF => '498', + self::MONACO => '492', + self::MONGOLIA => '496', + self::MONTENEGRO => '499', + self::MONTSERRAT => '500', + self::MOROCCO => '504', + self::MOZAMBIQUE => '508', + self::MYANMAR => '104', + self::NAMIBIA => '516', + self::NAURU => '520', + self::NEPAL => '524', + self::NETHERLANDS_KINGDOM_OF_THE => '528', + self::NEW_CALEDONIA => '540', + self::NEW_ZEALAND => '554', + self::NICARAGUA => '558', + self::NIGER => '562', + self::NIGERIA => '566', + self::NIUE => '570', + self::NORFOLK_ISLAND => '574', + self::NORTH_MACEDONIA => '807', + self::NORTHERN_MARIANA_ISLANDS => '580', + self::NORWAY => '578', + self::OMAN => '512', + self::PAKISTAN => '586', + self::PALAU => '585', + self::PALESTINE_STATE_OF => '275', + self::PANAMA => '591', + self::PAPUA_NEW_GUINEA => '598', + self::PARAGUAY => '600', + self::PERU => '604', + self::PHILIPPINES => '608', + self::PITCAIRN => '612', + self::POLAND => '616', + self::PORTUGAL => '620', + self::PUERTO_RICO => '630', + self::QATAR => '634', + self::REUNION => '638', + self::ROMANIA => '642', + self::RUSSIAN_FEDERATION => '643', + self::RWANDA => '646', + self::SAINT_BARTHELEMY => '652', + self::SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA => '654', + self::SAINT_KITTS_AND_NEVIS => '659', + self::SAINT_LUCIA => '662', + self::SAINT_MARTIN_FRENCH_PART => '663', + self::SAINT_PIERRE_AND_MIQUELON => '666', + self::SAINT_VINCENT_AND_THE_GRENADINES => '670', + self::SAMOA => '882', + self::SAN_MARINO => '674', + self::SAO_TOME_AND_PRINCIPE => '678', + self::SAUDI_ARABIA => '682', + self::SENEGAL => '686', + self::SERBIA => '688', + self::SEYCHELLES => '690', + self::SIERRA_LEONE => '694', + self::SINGAPORE => '702', + self::SINT_MAARTEN_DUTCH_PART => '534', + self::SLOVAKIA => '703', + self::SLOVENIA => '705', + self::SOLOMON_ISLANDS => '090', + self::SOMALIA => '706', + self::SOUTH_AFRICA => '710', + self::SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS => '239', + self::SOUTH_SUDAN => '728', + self::SPAIN => '724', + self::SRI_LANKA => '144', + self::SUDAN => '729', + self::SURINAME => '740', + self::SVALBARD_AND_JAN_MAYEN => '744', + self::SWEDEN => '752', + self::SWITZERLAND => '756', + self::SYRIAN_ARAB_REPUBLIC => '760', + self::TAIWAN_PROVINCE_OF_CHINA => '158', + self::TAJIKISTAN => '762', + self::TANZANIA_UNITED_REPUBLIC_OF => '834', + self::THAILAND => '764', + self::TIMOR_LESTE => '626', + self::TOGO => '768', + self::TOKELAU => '772', + self::TONGA => '776', + self::TRINIDAD_AND_TOBAGO => '780', + self::TUNISIA => '788', + self::TURKIYE => '792', + self::TURKMENISTAN => '795', + self::TURKS_AND_CAICOS_ISLANDS => '796', + self::TUVALU => '798', + self::UGANDA => '800', + self::UKRAINE => '804', + self::UNITED_ARAB_EMIRATES => '784', + self::UNITED_KINGDOM_OF_GREAT_BRITAIN_AND_NORTHERN_IRELAND => '826', + self::UNITED_STATES_MINOR_OUTLYING_ISLANDS => '581', + self::UNITED_STATES_OF_AMERICA => '840', + self::URUGUAY => '858', + self::UZBEKISTAN => '860', + self::VANUATU => '548', + self::VENEZUELA_BOLIVARIAN_REPUBLIC_OF => '862', + self::VIET_NAM => '704', + self::VIRGIN_ISLANDS_BRITISH => '092', + self::VIRGIN_ISLANDS_US => '850', + self::WALLIS_AND_FUTUNA => '876', + self::WESTERN_SAHARA => '732', + self::YEMEN => '887', + self::ZAMBIA => '894', + self::ZIMBABWE => '716' + }; + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function parent ():M49 { + + return match ($this) { + self::AFGHANISTAN, self::BANGLADESH, self::BHUTAN, self::INDIA, self::IRAN_ISLAMIC_REPUBLIC_OF, + self::MALDIVES, self::NEPAL, self::PAKISTAN, self::SRI_LANKA + => SubRegion::SOUTHERN_ASIA, + self::ALAND_ISLANDS, self::DENMARK, self::ESTONIA, self::FAROE_ISLANDS, self::FINLAND, self::GUERNSEY, + self::ICELAND, self::IRELAND, self::ISLE_OF_MAN, self::JERSEY, self::LATVIA, self::LITHUANIA, self::NORWAY, + self::SVALBARD_AND_JAN_MAYEN, self::SWEDEN, self::UNITED_KINGDOM_OF_GREAT_BRITAIN_AND_NORTHERN_IRELAND + => SubRegion::NORTHERN_EUROPE, + self::ALBANIA, self::ANDORRA, self::BOSNIA_AND_HERZEGOVINA, self::CROATIA, self::GIBRALTAR, self::GREECE, + self::HOLY_SEE, self::ITALY, self::KOSOVO, self::MALTA, self::MONTENEGRO, self::NORTH_MACEDONIA, + self::PORTUGAL, self::SAN_MARINO, self::SERBIA, self::SLOVENIA, self::SPAIN + => SubRegion::SOUTHERN_EUROPE, + self::ALGERIA, self::EGYPT, self::LIBYA, self::MOROCCO, self::SUDAN, self::TUNISIA, self::WESTERN_SAHARA + => SubRegion::NORTHERN_AFRICA, + self::AMERICAN_SAMOA, self::COOK_ISLANDS, self::FRENCH_POLYNESIA, self::NIUE, self::PITCAIRN, self::SAMOA, + self::TOKELAU, self::TONGA, self::TUVALU, self::WALLIS_AND_FUTUNA + => SubRegion::POLYNESIA, + self::ANGOLA, self::CAMEROON, self::CENTRAL_AFRICAN_REPUBLIC, self::CHAD, self::CONGO, + self::CONGO_DEMOCRATIC_REPUBLIC_OF_THE, self::EQUATORIAL_GUINEA, self::GABON, + self::SAO_TOME_AND_PRINCIPE + => IntermediateRegion::MIDDLE_AFRICA, + self::ANGUILLA, self::ANTIGUA_AND_BARBUDA, self::ARUBA, self::BAHAMAS, self::BARBADOS, + self::BONAIRE_SINT_EUSTATIUS_AND_SABA, self::CAYMAN_ISLANDS, self::CUBA, self::CURACAO, self::DOMINICA, + self::DOMINICAN_REPUBLIC, self::GRENADA, self::GUADELOUPE, self::HAITI, self::JAMAICA, self::MARTINIQUE, + self::MONTSERRAT, self::PUERTO_RICO, self::SAINT_BARTHELEMY, self::SAINT_KITTS_AND_NEVIS, self::SAINT_LUCIA, + self::SAINT_MARTIN_FRENCH_PART, self::SAINT_VINCENT_AND_THE_GRENADINES, self::SINT_MAARTEN_DUTCH_PART, + self::TRINIDAD_AND_TOBAGO, self::TURKS_AND_CAICOS_ISLANDS, self::VIRGIN_ISLANDS_BRITISH, + self::VIRGIN_ISLANDS_US + => IntermediateRegion::CARIBBEAN, + self::ANTARCTICA + => Region::ANTARCTICA, + self::ARGENTINA, self::BOLIVIA_PLURINATIONAL_STATE_OF, self::BOUVET_ISLAND, self::BRAZIL, self::CHILE, + self::COLOMBIA, self::ECUADOR, self::FALKLAND_ISLANDS_MALVINAS, self::FRENCH_GUIANA, self::GUYANA, + self::PARAGUAY, self::PERU, self::SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS, self::SURINAME, + self::URUGUAY, self::VENEZUELA_BOLIVARIAN_REPUBLIC_OF + => IntermediateRegion::SOUTH_AMERICA, + self::ARMENIA, self::AZERBAIJAN, self::BAHRAIN, self::CYPRUS, self::GEORGIA, self::IRAQ, self::ISRAEL, + self::JORDAN, self::KUWAIT, self::LEBANON, self::OMAN, self::PALESTINE_STATE_OF, self::QATAR, + self::SAUDI_ARABIA, self::SYRIAN_ARAB_REPUBLIC, self::TURKIYE, self::UNITED_ARAB_EMIRATES, + self::YEMEN + => SubRegion::WESTERN_ASIA, + self::AUSTRALIA, self::CHRISTMAS_ISLAND, self::COCOS_KEELING_ISLANDS, + self::HEARD_ISLAND_AND_MCDONALD_ISLANDS, self::NEW_ZEALAND, + self::NORFOLK_ISLAND + => SubRegion::AUSTRALIA_AND_NEW_ZEALAND, + self::AUSTRIA, self::BELGIUM, self::FRANCE, self::GERMANY, self::LIECHTENSTEIN, self::LUXEMBOURG, + self::MONACO, self::NETHERLANDS_KINGDOM_OF_THE, self::SWITZERLAND + => SubRegion::WESTERN_EUROPE, + self::BELARUS, self::BULGARIA, self::CZECHIA, self::HUNGARY, self::MOLDOVA_REPUBLIC_OF, self::POLAND, + self::ROMANIA, self::RUSSIAN_FEDERATION, self::SLOVAKIA, self::UKRAINE + => SubRegion::EASTERN_EUROPE, + self::BELIZE, self::COSTA_RICA, self::EL_SALVADOR, self::GUATEMALA, self::HONDURAS, self::MEXICO, + self::NICARAGUA, self::PANAMA + => IntermediateRegion::CENTRAL_AMERICA, + self::BENIN, self::BURKINA_FASO, self::CABO_VERDE, self::COTE_D_IVOIRE, self::GAMBIA, self::GHANA, + self::GUINEA, self::GUINEA_BISSAU, self::LIBERIA, self::MALI, self::MAURITANIA, self::NIGER, self::NIGERIA, + self::SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA, self::SENEGAL, self::SIERRA_LEONE, + self::TOGO + => IntermediateRegion::WESTERN_AFRICA, + self::BERMUDA, self::CANADA, self::GREENLAND, self::SAINT_PIERRE_AND_MIQUELON, self::UNITED_STATES_OF_AMERICA + => SubRegion::NORTHERN_AMERICA, + self::BOTSWANA, self::ESWATINI, self::LESOTHO, self::NAMIBIA, self::SOUTH_AFRICA + => IntermediateRegion::SOUTHERN_AFRICA, + self::BRITISH_INDIAN_OCEAN_TERRITORY, self::BURUNDI, self::COMOROS, self::DJIBOUTI, self::ERITREA, + self::ETHIOPIA, self::FRENCH_SOUTHERN_TERRITORIES, self::KENYA, self::MADAGASCAR, self::MALAWI, + self::MAURITIUS, self::MAYOTTE, self::MOZAMBIQUE, self::REUNION, self::RWANDA, self::SEYCHELLES, + self::SOMALIA, self::SOUTH_SUDAN, self::TANZANIA_UNITED_REPUBLIC_OF, self::UGANDA, self::ZAMBIA, + self::ZIMBABWE + => IntermediateRegion::EASTERN_AFRICA, + self::BRUNEI_DARUSSALAM, self::CAMBODIA, self::INDONESIA, self::LAO_PEOPLES_DEMOCRATIC_REPUBLIC, + self::MALAYSIA, self::MYANMAR, self::PHILIPPINES, self::SINGAPORE, self::THAILAND, self::TIMOR_LESTE, + self::VIET_NAM + => SubRegion::SOUTH_EASTERN_ASIA, + self::CHINA, self::HONG_KONG, self::JAPAN, self::KOREA_DEMOCRATIC_PEOPLES_REPUBLIC_OF, + self::KOREA_REPUBLIC_OF, self::MACAO, self::MONGOLIA, self::TAIWAN_PROVINCE_OF_CHINA + => SubRegion::EASTERN_ASIA, + self::FIJI, self::NEW_CALEDONIA, self::PAPUA_NEW_GUINEA, self::SOLOMON_ISLANDS, self::VANUATU + => SubRegion::MELANESIA, + self::GUAM, self::KIRIBATI, self::MARSHALL_ISLANDS, self::MICRONESIA_FEDERATED_STATES_OF, self::NAURU, + self::NORTHERN_MARIANA_ISLANDS, self::PALAU, self::UNITED_STATES_MINOR_OUTLYING_ISLANDS + => SubRegion::MICRONESIA, + self::KAZAKHSTAN, self::KYRGYZSTAN, self::TAJIKISTAN, self::TURKMENISTAN, self::UZBEKISTAN + => SubRegion::CENTRAL_ASIA + }; + + } + +} \ No newline at end of file diff --git a/src/Type/Geo/IntermediateRegion.php b/src/Type/Geo/IntermediateRegion.php new file mode 100644 index 0000000..b0b53e9 --- /dev/null +++ b/src/Type/Geo/IntermediateRegion.php @@ -0,0 +1,99 @@ + + * @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.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +use FireHub\Core\Boundary\Type\Geo\M49; + +/** + * ### Represents an intermediate geographic region of the world + * + * The IntermediateRegion enum represents intermediate geographic regions within the FireHub Core type system. + * + * It provides stable geographic references for grouping countries into more specific geographic areas within a + * broader subregion. + * @since 1.0.0 + */ +enum IntermediateRegion:string implements M49 { + + /** + * @since 1.0.0 + */ + case CARIBBEAN = 'Caribbean'; + + /** + * @since 1.0.0 + */ + case CENTRAL_AMERICA = 'Central America'; + + /** + * @since 1.0.0 + */ + case EASTERN_AFRICA = 'Eastern Africa'; + + /** + * @since 1.0.0 + */ + case MIDDLE_AFRICA = 'Middle Africa'; + + /** + * @since 1.0.0 + */ + case SOUTH_AMERICA = 'South America'; + + /** + * @since 1.0.0 + */ + case SOUTHERN_AFRICA = 'Southern Africa'; + + /** + * @since 1.0.0 + */ + case WESTERN_AFRICA = 'Western Africa'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function code ():string { + + return match ($this) { + self::CARIBBEAN => '029', + self::CENTRAL_AMERICA => '013', + self::EASTERN_AFRICA => '014', + self::MIDDLE_AFRICA => '017', + self::SOUTH_AMERICA => '005', + self::SOUTHERN_AFRICA => '018', + self::WESTERN_AFRICA => '011' + }; + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function parent ():M49 { + + return match ($this) { + self::CARIBBEAN, self::CENTRAL_AMERICA, self::SOUTH_AMERICA + => SubRegion::LATIN_AMERICA_AND_THE_CARIBBEAN, + self::EASTERN_AFRICA, self::MIDDLE_AFRICA, self::SOUTHERN_AFRICA, self::WESTERN_AFRICA + => SubRegion::SUB_SAHARAN_AFRICA + }; + + } + +} \ No newline at end of file diff --git a/src/Type/Geo/Ocean.php b/src/Type/Geo/Ocean.php new file mode 100644 index 0000000..d16577d --- /dev/null +++ b/src/Type/Geo/Ocean.php @@ -0,0 +1,51 @@ + + * @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.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +/** + * ### Represents an ocean as a geographic value + * + * The Ocean enum represents the world's major oceans as geographic values within the FireHub Core type system. + * + * It provides stable geographic references for relationships and classifications involving the world's oceans. + * @since 1.0.0 + */ +enum Ocean:string { + + /** + * @since 1.0.0 + */ + case ARCTIC = 'Arctic'; + + /** + * @since 1.0.0 + */ + case ATLANTIC = 'Atlantic'; + + /** + * @since 1.0.0 + */ + case INDIAN = 'Indian'; + + /** + * @since 1.0.0 + */ + case PACIFIC = 'Pacific'; + + /** + * @since 1.0.0 + */ + case SOUTHERN = 'Southern'; + +} \ No newline at end of file diff --git a/src/Type/Geo/Region.php b/src/Type/Geo/Region.php new file mode 100644 index 0000000..8b08204 --- /dev/null +++ b/src/Type/Geo/Region.php @@ -0,0 +1,88 @@ + + * @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.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +use FireHub\Core\Boundary\Type\Geo\M49; + +/** + * ### Represents a major geographic region of the world + * + * The Region enum represents the major geographic regions of the world within the FireHub Core type system. + * + * It provides stable geographic references for grouping countries and other geographic entities into broad world + * regions. + * @since 1.0.0 + */ +enum Region:string implements M49 { + + /** + * @since 1.0.0 + */ + case AFRICA = 'Africa'; + + /** + * @since 1.0.0 + */ + case AMERICAS = 'Americas'; + + /** + * @since 1.0.0 + */ + case ANTARCTICA = 'Antarctica'; + + /** + * @since 1.0.0 + */ + case ASIA = 'Asia'; + + /** + * @since 1.0.0 + */ + case EUROPE = 'Europe'; + + /** + * @since 1.0.0 + */ + case OCEANIA = 'Oceania'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function code ():string { + + return match ($this) { + self::AFRICA => '002', + self::AMERICAS => '119', + self::ANTARCTICA => '110', + self::ASIA => '142', + self::EUROPE => '150', + self::OCEANIA => '009' + }; + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function parent ():M49 { + + return World::WORLD; + + } + +} \ No newline at end of file diff --git a/src/Type/Geo/SubRegion.php b/src/Type/Geo/SubRegion.php new file mode 100644 index 0000000..6707410 --- /dev/null +++ b/src/Type/Geo/SubRegion.php @@ -0,0 +1,165 @@ + + * @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.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +use FireHub\Core\Boundary\Type\Geo\M49; + +/** + * ### Represents a geographic subregion of the world + * + * The SubRegion enum represents the geographic subregions of the world within the FireHub Core type system. + * + * It provides stable geographic references for grouping countries into more specific regions within a broader + * geographic region. + * @since 1.0.0 + */ +enum SubRegion:string implements M49 { + + /** + * @since 1.0.0 + */ + case AUSTRALIA_AND_NEW_ZEALAND = 'Australia and New Zealand'; + + /** + * @since 1.0.0 + */ + case CENTRAL_ASIA = 'Central Asia'; + + /** + * @since 1.0.0 + */ + case EASTERN_ASIA = 'Eastern Asia'; + + /** + * @since 1.0.0 + */ + case EASTERN_EUROPE = 'Eastern Europe'; + + /** + * @since 1.0.0 + */ + case LATIN_AMERICA_AND_THE_CARIBBEAN = 'Latin America and the Caribbean'; + + /** + * @since 1.0.0 + */ + case MELANESIA = 'Melanesia'; + + /** + * @since 1.0.0 + */ + case MICRONESIA = 'Micronesia'; + + /** + * @since 1.0.0 + */ + case NORTHERN_AFRICA = 'Northern Africa'; + + /** + * @since 1.0.0 + */ + case NORTHERN_AMERICA = 'Northern America'; + + /** + * @since 1.0.0 + */ + case NORTHERN_EUROPE = 'Northern Europe'; + + /** + * @since 1.0.0 + */ + case POLYNESIA = 'Polynesia'; + + /** + * @since 1.0.0 + */ + case SOUTH_EASTERN_ASIA = 'South-Eastern Asia'; + + /** + * @since 1.0.0 + */ + case SOUTHERN_ASIA = 'Southern Asia'; + + /** + * @since 1.0.0 + */ + case SOUTHERN_EUROPE = 'Southern Europe'; + + /** + * @since 1.0.0 + */ + case SUB_SAHARAN_AFRICA = 'Sub-Saharan Africa'; + + /** + * @since 1.0.0 + */ + case WESTERN_ASIA = 'Western Asia'; + + /** + * @since 1.0.0 + */ + case WESTERN_EUROPE = 'Western Europe'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function code ():string { + + return match ($this) { + self::AUSTRALIA_AND_NEW_ZEALAND => '053', + self::CENTRAL_ASIA => '143', + self::EASTERN_ASIA => '030', + self::EASTERN_EUROPE => '051', + self::LATIN_AMERICA_AND_THE_CARIBBEAN => '419', + self::MELANESIA => '054', + self::MICRONESIA => '057', + self::NORTHERN_AFRICA => '015', + self::NORTHERN_AMERICA => '021', + self::NORTHERN_EUROPE => '154', + self::POLYNESIA => '061', + self::SOUTH_EASTERN_ASIA => '035', + self::SOUTHERN_ASIA => '034', + self::SOUTHERN_EUROPE => '039', + self::SUB_SAHARAN_AFRICA => '202', + self::WESTERN_ASIA => '145', + self::WESTERN_EUROPE => '155' + }; + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function parent ():M49 { + + return match ($this) { + self::AUSTRALIA_AND_NEW_ZEALAND, self::MELANESIA, self::MICRONESIA, self::POLYNESIA + => Region::OCEANIA, + self::CENTRAL_ASIA, self::EASTERN_ASIA, self::SOUTH_EASTERN_ASIA, self::SOUTHERN_ASIA, self::WESTERN_ASIA + => Region::ASIA, + self::EASTERN_EUROPE, self::NORTHERN_EUROPE, self::SOUTHERN_EUROPE, self::WESTERN_EUROPE + => Region::EUROPE, + self::LATIN_AMERICA_AND_THE_CARIBBEAN, self::NORTHERN_AMERICA + => Region::AMERICAS, + self::NORTHERN_AFRICA, self::SUB_SAHARAN_AFRICA + => Region::AFRICA + }; + + } + +} \ No newline at end of file diff --git a/src/Type/Geo/World.php b/src/Type/Geo/World.php new file mode 100644 index 0000000..38e7239 --- /dev/null +++ b/src/Type/Geo/World.php @@ -0,0 +1,58 @@ + + * @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.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +use FireHub\Core\Boundary\Type\Geo\M49; + +/** + * ### Represents the world as a geographic value + * + * The World enum represents the complete geographic world as a single value within the FireHub Core type system. + * + * It provides a stable geographic reference for operations and relationships that apply to the entire Earth rather than + * to a specific country, continent, landmass, or geographic region. + * @since 1.0.0 + */ +enum World:string implements M49 { + + /** + * @since 1.0.0 + */ + case WORLD = 'World'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function code ():string { + + return match ($this) { + self::WORLD => '001' + }; + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function parent ():?M49 { + + return null; + + } + +} \ No newline at end of file From 847bea66e32741e5ef9a6d5b2596aebd59565bf7 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 25 Aug 2026 12:43:40 +0200 Subject: [PATCH 029/118] Extend `Country` enum with ISO3166 support and additional helper methods **Details:** - Added `ISO3166` interface to `Country` for ISO-compliant alpha-2 and alpha-3 codes. - Implemented helper methods for streamlined country operations: - `fromAlpha2(string $code): self|false` - Resolve a country by its alpha-2 code. - `fromAlpha3(string $code): self|false` - Resolve a country by its alpha-3 code. - `casesFrom(M49 $region): array` - List countries in a specific region. - `casesFromContinentOrOcean(Continent|Ocean $value): array` - Filter countries by continent or ocean. - `is(M49 $region): bool` - Check if a country matches a given region. - `independent(): bool` - Determine if a country is independent. - `continentOrOcean(): Continent|Ocean` - Fetch the associated continent or ocean. - `alpha2(): string` - Retrieve alpha-2 code. - `alpha3(): string` - Retrieve alpha-3 code. - Introduced detailed PHPDoc annotations to clarify usage and improve maintainability. This enhancement integrates ISO3166 standards into the `Country` enum, providing comprehensive world country data, facilitating geographic operations, and aligning with FireHub's principles of precision and extensibility. --- src/Boundary/Type/Geo/ISO3166.php | 50 ++ src/Type/Geo/Country.php | 757 +++++++++++++++++++++++++++++- 2 files changed, 805 insertions(+), 2 deletions(-) create mode 100644 src/Boundary/Type/Geo/ISO3166.php diff --git a/src/Boundary/Type/Geo/ISO3166.php b/src/Boundary/Type/Geo/ISO3166.php new file mode 100644 index 0000000..5f00a21 --- /dev/null +++ b/src/Boundary/Type/Geo/ISO3166.php @@ -0,0 +1,50 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\Geo; + +/** + * ### The International Standard for country codes and codes for their subdivisions + * + * ISO 3166 is a standard published by the International Organization for Standardization (ISO) that defines codes + * for the names of countries, dependent territories, special areas of geographical interest, + * and their principal subdivisions (for example, provinces or states). + * @since 1.0.0 + */ +interface ISO3166 { + + /** + * ### Alpha 2 code + * + * ISO 3166-1 alpha-2 codes are two-letter country codes defined in ISO 3166-1, part of the ISO 3166 standard[1] + * published by the International Organization for Standardization (ISO), to represent countries, + * dependent territories, and special areas of geographical interest. + * @since 1.0.0 + * + * @return non-empty-string Alpha 2 code. + */ + public function alpha2 ():string; + + /** + * ### Alpha 3 code + * + * ISO 3166-1 alpha-3 codes are three-letter country codes defined in ISO 3166-1, part of the ISO 3166 standard + * published by the International Organization for Standardization (ISO), to represent countries, + * dependent territories, and special areas of geographical interest. + * @since 1.0.0 + * + * @return non-empty-string Alpha 3 code. + */ + public function alpha3 ():string; + +} \ No newline at end of file diff --git a/src/Type/Geo/Country.php b/src/Type/Geo/Country.php index 9038b93..73bac31 100644 --- a/src/Type/Geo/Country.php +++ b/src/Type/Geo/Country.php @@ -13,7 +13,9 @@ namespace FireHub\Core\Type\Geo; -use FireHub\Core\Boundary\Type\Geo\M49; +use FireHub\Core\Boundary\Type\Geo\ { + M49, ISO3166 +}; /** * ### Defines the world's countries @@ -25,7 +27,7 @@ * data that may change over time. * @since 1.0.0 */ -enum Country:string implements M49 { +enum Country:string implements M49, ISO3166 { /** * @since 1.0.0 @@ -1277,6 +1279,104 @@ enum Country:string implements M49 { */ case ZIMBABWE = 'Zimbabwe'; + /** + * ### Get county from alpha 2 code + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\Geo\Country::alpha2() To check alpha 2 code for country. + * + * @return self|false Returns country if found or `false` if country not found. + */ + public static function fromAlpha2 (string $code):self|false { + + foreach (self::cases() as $case) + if ($case->alpha2() === $code) return $case; + + return false; + + } + + /** + * ### Get county from alpha 3 code + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\Geo\Country::alpha3() To check alpha 3 code for country. + * + * @return self|false Returns country if found or `false` if country not found. + */ + public static function fromAlpha3 (string $code):self|false { + + foreach (self::cases() as $case) + if ($case->alpha3() === $code) return $case; + + return false; + + } + + /** + * ### Get all country's from a provided region + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\Geo\Country::is() To check if the country is a region. + * + * @param \FireHub\Core\Boundary\Type\Geo\M49 $region

+ * The region to filter by. + *

+ * + * @return \FireHub\Core\Type\Geo\Country[] List of country's. + */ + public static function casesFrom (M49 $region):array { + + $cases = []; + + foreach (self::cases() as $case) + if ($case->is($region)) $cases[] = $case; + + return $cases; + + } + + /** + * ### Get all country's from a provided continent or ocean + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\Geo\Country::continentOrOcean() To check a country's continent or ocean. + * + * @param \FireHub\Core\Type\Geo\Continent|\FireHub\Core\Type\Geo\Ocean $continent_or_ocean

+ * Continent or ocean to filter by. + *

+ * + * @return \FireHub\Core\Type\Geo\Country[] List of country's. + */ + public static function casesFromContinentOrOcean (Continent|Ocean $continent_or_ocean):array { + + $cases = []; + + foreach (self::cases() as $case) + if ($case->continentOrOcean() === $continent_or_ocean) $cases[] = $case; + + return $cases; + + } + + /** + * ### Check if the country is a region + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\Geo\Country::check() To check country's region. + * + * @param \FireHub\Core\Boundary\Type\Geo\M49 $region

+ * The region to check for. + *

+ * + * @return bool True if country is a region type, false otherwise. + */ + public function is (M49 $region):bool { + + return $this->check($region, $this); + + } + /** * @inheritDoc * @@ -1633,4 +1733,657 @@ public function parent ():M49 { } + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function alpha2 ():string { + + return match ($this) { + self::AFGHANISTAN => 'AF', + self::ALAND_ISLANDS => 'AX', + self::ALBANIA => 'AL', + self::ALGERIA => 'DZ', + self::AMERICAN_SAMOA => 'AS', + self::ANDORRA => 'AD', + self::ANGOLA => 'AO', + self::ANGUILLA => 'AI', + self::ANTARCTICA => 'AQ', + self::ANTIGUA_AND_BARBUDA => 'AG', + self::ARGENTINA => 'AR', + self::ARMENIA => 'AM', + self::ARUBA => 'AW', + self::AUSTRALIA => 'AU', + self::AUSTRIA => 'AT', + self::AZERBAIJAN => 'AZ', + self::BAHAMAS => 'BS', + self::BAHRAIN => 'BH', + self::BANGLADESH => 'BD', + self::BARBADOS => 'BB', + self::BELARUS => 'BY', + self::BELGIUM => 'BE', + self::BELIZE => 'BZ', + self::BENIN => 'BJ', + self::BERMUDA => 'BM', + self::BHUTAN => 'BT', + self::BOLIVIA_PLURINATIONAL_STATE_OF => 'BO', + self::BONAIRE_SINT_EUSTATIUS_AND_SABA => 'BQ', + self::BOSNIA_AND_HERZEGOVINA => 'BA', + self::BOTSWANA => 'BW', + self::BOUVET_ISLAND => 'BV', + self::BRAZIL => 'BR', + self::BRITISH_INDIAN_OCEAN_TERRITORY => 'IO', + self::BRUNEI_DARUSSALAM => 'BN', + self::BULGARIA => 'BG', + self::BURKINA_FASO => 'BF', + self::BURUNDI => 'BI', + self::CABO_VERDE => 'CV', + self::CAMBODIA => 'KH', + self::CAMEROON => 'CM', + self::CANADA => 'CA', + self::CAYMAN_ISLANDS => 'KY', + self::CENTRAL_AFRICAN_REPUBLIC => 'CF', + self::CHAD => 'TD', + self::CHILE => 'CL', + self::CHINA => 'CN', + self::CHRISTMAS_ISLAND => 'CX', + self::COCOS_KEELING_ISLANDS => 'CC', + self::COLOMBIA => 'CO', + self::COMOROS => 'KM', + self::CONGO => 'CG', + self::CONGO_DEMOCRATIC_REPUBLIC_OF_THE => 'CD', + self::COOK_ISLANDS => 'CK', + self::COSTA_RICA => 'CR', + self::COTE_D_IVOIRE => 'CI', + self::CROATIA => 'HR', + self::CUBA => 'CU', + self::CURACAO => 'CW', + self::CYPRUS => 'CY', + self::CZECHIA => 'CZ', + self::DENMARK => 'DK', + self::DJIBOUTI => 'DJ', + self::DOMINICA => 'DM', + self::DOMINICAN_REPUBLIC => 'DO', + self::ECUADOR => 'EC', + self::EGYPT => 'EG', + self::EL_SALVADOR => 'SV', + self::EQUATORIAL_GUINEA => 'GQ', + self::ERITREA => 'ER', + self::ESTONIA => 'EE', + self::ESWATINI => 'SZ', + self::ETHIOPIA => 'ET', + self::FALKLAND_ISLANDS_MALVINAS => 'FK', + self::FAROE_ISLANDS => 'FO', + self::FIJI => 'FJ', + self::FINLAND => 'FI', + self::FRANCE => 'FR', + self::FRENCH_GUIANA => 'GF', + self::FRENCH_POLYNESIA => 'PF', + self::FRENCH_SOUTHERN_TERRITORIES => 'TF', + self::GABON => 'GA', + self::GAMBIA => 'GM', + self::GEORGIA => 'GE', + self::GERMANY => 'DE', + self::GHANA => 'GH', + self::GIBRALTAR => 'GI', + self::GREECE => 'GR', + self::GREENLAND => 'GL', + self::GRENADA => 'GD', + self::GUADELOUPE => 'GP', + self::GUAM => 'GU', + self::GUATEMALA => 'GT', + self::GUERNSEY => 'GG', + self::GUINEA => 'GN', + self::GUINEA_BISSAU => 'GW', + self::GUYANA => 'GY', + self::HAITI => 'HT', + self::HEARD_ISLAND_AND_MCDONALD_ISLANDS => 'HM', + self::HOLY_SEE => 'VA', + self::HONDURAS => 'HN', + self::HONG_KONG => 'HK', + self::HUNGARY => 'HU', + self::ICELAND => 'IS', + self::INDIA => 'IN', + self::INDONESIA => 'ID', + self::IRAN_ISLAMIC_REPUBLIC_OF => 'IR', + self::IRAQ => 'IQ', + self::IRELAND => 'IE', + self::ISLE_OF_MAN => 'IM', + self::ISRAEL => 'IL', + self::ITALY => 'IT', + self::JAMAICA => 'JM', + self::JAPAN => 'JP', + self::JERSEY => 'JE', + self::JORDAN => 'JO', + self::KAZAKHSTAN => 'KZ', + self::KENYA => 'KE', + self::KIRIBATI => 'KI', + self::KOREA_DEMOCRATIC_PEOPLES_REPUBLIC_OF => 'KP', + self::KOREA_REPUBLIC_OF => 'KR', + self::KOSOVO => 'XK', + self::KUWAIT => 'KW', + self::KYRGYZSTAN => 'KG', + self::LAO_PEOPLES_DEMOCRATIC_REPUBLIC => 'LA', + self::LATVIA => 'LV', + self::LEBANON => 'LB', + self::LESOTHO => 'LS', + self::LIBERIA => 'LR', + self::LIBYA => 'LY', + self::LIECHTENSTEIN => 'LI', + self::LITHUANIA => 'LT', + self::LUXEMBOURG => 'LU', + self::MACAO => 'MO', + self::MADAGASCAR => 'MG', + self::MALAWI => 'MW', + self::MALAYSIA => 'MY', + self::MALDIVES => 'MV', + self::MALI => 'ML', + self::MALTA => 'MT', + self::MARSHALL_ISLANDS => 'MH', + self::MARTINIQUE => 'MQ', + self::MAURITANIA => 'MR', + self::MAURITIUS => 'MU', + self::MAYOTTE => 'YT', + self::MEXICO => 'MX', + self::MICRONESIA_FEDERATED_STATES_OF => 'FM', + self::MOLDOVA_REPUBLIC_OF => 'MD', + self::MONACO => 'MC', + self::MONGOLIA => 'MN', + self::MONTENEGRO => 'ME', + self::MONTSERRAT => 'MS', + self::MOROCCO => 'MA', + self::MOZAMBIQUE => 'MZ', + self::MYANMAR => 'MM', + self::NAMIBIA => 'NA', + self::NAURU => 'NR', + self::NEPAL => 'NP', + self::NETHERLANDS_KINGDOM_OF_THE => 'NL', + self::NEW_CALEDONIA => 'NC', + self::NEW_ZEALAND => 'NZ', + self::NICARAGUA => 'NI', + self::NIGER => 'NE', + self::NIGERIA => 'NG', + self::NIUE => 'NU', + self::NORFOLK_ISLAND => 'NF', + self::NORTH_MACEDONIA => 'MK', + self::NORTHERN_MARIANA_ISLANDS => 'MP', + self::NORWAY => 'NO', + self::OMAN => 'OM', + self::PAKISTAN => 'PK', + self::PALAU => 'PW', + self::PALESTINE_STATE_OF => 'PS', + self::PANAMA => 'PA', + self::PAPUA_NEW_GUINEA => 'PG', + self::PARAGUAY => 'PY', + self::PERU => 'PE', + self::PHILIPPINES => 'PH', + self::PITCAIRN => 'PN', + self::POLAND => 'PL', + self::PORTUGAL => 'PT', + self::PUERTO_RICO => 'PR', + self::QATAR => 'QA', + self::REUNION => 'RE', + self::ROMANIA => 'RO', + self::RUSSIAN_FEDERATION => 'RU', + self::RWANDA => 'RW', + self::SAINT_BARTHELEMY => 'BL', + self::SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA => 'SH', + self::SAINT_KITTS_AND_NEVIS => 'KN', + self::SAINT_LUCIA => 'LC', + self::SAINT_MARTIN_FRENCH_PART => 'MF', + self::SAINT_PIERRE_AND_MIQUELON => 'PM', + self::SAINT_VINCENT_AND_THE_GRENADINES => 'VC', + self::SAMOA => 'WS', + self::SAN_MARINO => 'SM', + self::SAO_TOME_AND_PRINCIPE => 'ST', + self::SAUDI_ARABIA => 'SA', + self::SENEGAL => 'SN', + self::SERBIA => 'RS', + self::SEYCHELLES => 'SC', + self::SIERRA_LEONE => 'SL', + self::SINGAPORE => 'SG', + self::SINT_MAARTEN_DUTCH_PART => 'SX', + self::SLOVAKIA => 'SK', + self::SLOVENIA => 'SI', + self::SOLOMON_ISLANDS => 'SB', + self::SOMALIA => 'SO', + self::SOUTH_AFRICA => 'ZA', + self::SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS => 'GS', + self::SOUTH_SUDAN => 'SS', + self::SPAIN => 'ES', + self::SRI_LANKA => 'LK', + self::SUDAN => 'SD', + self::SURINAME => 'SR', + self::SVALBARD_AND_JAN_MAYEN => 'SJ', + self::SWEDEN => 'SE', + self::SWITZERLAND => 'CH', + self::SYRIAN_ARAB_REPUBLIC => 'SY', + self::TAIWAN_PROVINCE_OF_CHINA => 'TW', + self::TAJIKISTAN => 'TJ', + self::TANZANIA_UNITED_REPUBLIC_OF => 'TZ', + self::THAILAND => 'TH', + self::TIMOR_LESTE => 'TL', + self::TOGO => 'TG', + self::TOKELAU => 'TK', + self::TONGA => 'TO', + self::TRINIDAD_AND_TOBAGO => 'TT', + self::TUNISIA => 'TN', + self::TURKIYE => 'TR', + self::TURKMENISTAN => 'TM', + self::TURKS_AND_CAICOS_ISLANDS => 'TC', + self::TUVALU => 'TV', + self::UGANDA => 'UG', + self::UKRAINE => 'UA', + self::UNITED_ARAB_EMIRATES => 'AE', + self::UNITED_KINGDOM_OF_GREAT_BRITAIN_AND_NORTHERN_IRELAND => 'GB', + self::UNITED_STATES_MINOR_OUTLYING_ISLANDS => 'UM', + self::UNITED_STATES_OF_AMERICA => 'US', + self::URUGUAY => 'UY', + self::UZBEKISTAN => 'UZ', + self::VANUATU => 'VU', + self::VENEZUELA_BOLIVARIAN_REPUBLIC_OF => 'VE', + self::VIET_NAM => 'VN', + self::VIRGIN_ISLANDS_BRITISH => 'VG', + self::VIRGIN_ISLANDS_US => 'VI', + self::WALLIS_AND_FUTUNA => 'WF', + self::WESTERN_SAHARA => 'EH', + self::YEMEN => 'YE', + self::ZAMBIA => 'ZM', + self::ZIMBABWE => 'ZW' + }; + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function alpha3 ():string { + + return match ($this) { + self::AFGHANISTAN => 'AFG', + self::ALAND_ISLANDS => 'ALA', + self::ALBANIA => 'ALB', + self::ALGERIA => 'DZA', + self::AMERICAN_SAMOA => 'ASM', + self::ANDORRA => 'AND', + self::ANGOLA => 'AGO', + self::ANGUILLA => 'AIA', + self::ANTARCTICA => 'ATA', + self::ANTIGUA_AND_BARBUDA => 'ATG', + self::ARGENTINA => 'ARG', + self::ARMENIA => 'ARM', + self::ARUBA => 'ABW', + self::AUSTRALIA => 'AUS', + self::AUSTRIA => 'AUT', + self::AZERBAIJAN => 'AZE', + self::BAHAMAS => 'BHS', + self::BAHRAIN => 'BHR', + self::BANGLADESH => 'BGD', + self::BARBADOS => 'BRB', + self::BELARUS => 'BLR', + self::BELGIUM => 'BEL', + self::BELIZE => 'BLZ', + self::BENIN => 'BEN', + self::BERMUDA => 'BMU', + self::BHUTAN => 'BTN', + self::BOLIVIA_PLURINATIONAL_STATE_OF => 'BOL', + self::BONAIRE_SINT_EUSTATIUS_AND_SABA => 'BES', + self::BOSNIA_AND_HERZEGOVINA => 'BIH', + self::BOTSWANA => 'BWA', + self::BOUVET_ISLAND => 'BVT', + self::BRAZIL => 'BRA', + self::BRITISH_INDIAN_OCEAN_TERRITORY => 'IOT', + self::BRUNEI_DARUSSALAM => 'BRN', + self::BULGARIA => 'BGR', + self::BURKINA_FASO => 'BFA', + self::BURUNDI => 'BDI', + self::CABO_VERDE => 'CPV', + self::CAMBODIA => 'KHM', + self::CAMEROON => 'CMR', + self::CANADA => 'CAN', + self::CAYMAN_ISLANDS => 'CYM', + self::CENTRAL_AFRICAN_REPUBLIC => 'CAF', + self::CHAD => 'TCD', + self::CHILE => 'CHL', + self::CHINA => 'CHN', + self::CHRISTMAS_ISLAND => 'CXR', + self::COCOS_KEELING_ISLANDS => 'CCK', + self::COLOMBIA => 'COL', + self::COMOROS => 'COM', + self::CONGO => 'COG', + self::CONGO_DEMOCRATIC_REPUBLIC_OF_THE => 'COD', + self::COOK_ISLANDS => 'COK', + self::COSTA_RICA => 'CRI', + self::COTE_D_IVOIRE => 'CIV', + self::CROATIA => 'HRV', + self::CUBA => 'CUB', + self::CURACAO => 'CUW', + self::CYPRUS => 'CYP', + self::CZECHIA => 'CZE', + self::DENMARK => 'DNK', + self::DJIBOUTI => 'DJI', + self::DOMINICA => 'DMA', + self::DOMINICAN_REPUBLIC => 'DOM', + self::ECUADOR => 'ECU', + self::EGYPT => 'EGY', + self::EL_SALVADOR => 'SLV', + self::EQUATORIAL_GUINEA => 'GNQ', + self::ERITREA => 'ERI', + self::ESTONIA => 'EST', + self::ESWATINI => 'SWZ', + self::ETHIOPIA => 'ETH', + self::FALKLAND_ISLANDS_MALVINAS => 'FLK', + self::FAROE_ISLANDS => 'FRO', + self::FIJI => 'FJI', + self::FINLAND => 'FIN', + self::FRANCE => 'FRA', + self::FRENCH_GUIANA => 'GUF', + self::FRENCH_POLYNESIA => 'PYF', + self::FRENCH_SOUTHERN_TERRITORIES => 'ATF', + self::GABON => 'GAB', + self::GAMBIA => 'GMB', + self::GEORGIA => 'GEO', + self::GERMANY => 'DEU', + self::GHANA => 'GHA', + self::GIBRALTAR => 'GIB', + self::GREECE => 'GRC', + self::GREENLAND => 'GRL', + self::GRENADA => 'GRD', + self::GUADELOUPE => 'GLP', + self::GUAM => 'GUM', + self::GUATEMALA => 'GTM', + self::GUERNSEY => 'GGY', + self::GUINEA => 'GIN', + self::GUINEA_BISSAU => 'GNB', + self::GUYANA => 'GUY', + self::HAITI => 'HTI', + self::HEARD_ISLAND_AND_MCDONALD_ISLANDS => 'HMD', + self::HOLY_SEE => 'VAT', + self::HONDURAS => 'HND', + self::HONG_KONG => 'HKG', + self::HUNGARY => 'HUN', + self::ICELAND => 'ISL', + self::INDIA => 'IND', + self::INDONESIA => 'IDN', + self::IRAN_ISLAMIC_REPUBLIC_OF => 'IRN', + self::IRAQ => 'IRQ', + self::IRELAND => 'IRL', + self::ISLE_OF_MAN => 'IMN', + self::ISRAEL => 'ISR', + self::ITALY => 'ITA', + self::JAMAICA => 'JAM', + self::JAPAN => 'JPN', + self::JERSEY => 'JEY', + self::JORDAN => 'JOR', + self::KAZAKHSTAN => 'KAZ', + self::KENYA => 'KEN', + self::KIRIBATI => 'KIR', + self::KOREA_DEMOCRATIC_PEOPLES_REPUBLIC_OF => 'PRK', + self::KOREA_REPUBLIC_OF => 'KOR', + self::KOSOVO => 'UNK', + self::KUWAIT => 'KWT', + self::KYRGYZSTAN => 'KGZ', + self::LAO_PEOPLES_DEMOCRATIC_REPUBLIC => 'LAO', + self::LATVIA => 'LVA', + self::LEBANON => 'LBN', + self::LESOTHO => 'LSO', + self::LIBERIA => 'LBR', + self::LIBYA => 'LBY', + self::LIECHTENSTEIN => 'LIE', + self::LITHUANIA => 'LTU', + self::LUXEMBOURG => 'LUX', + self::MACAO => 'MAC', + self::MADAGASCAR => 'MDG', + self::MALAWI => 'MWI', + self::MALAYSIA => 'MYS', + self::MALDIVES => 'MDV', + self::MALI => 'MLI', + self::MALTA => 'MLT', + self::MARSHALL_ISLANDS => 'MHL', + self::MARTINIQUE => 'MTQ', + self::MAURITANIA => 'MRT', + self::MAURITIUS => 'MUS', + self::MAYOTTE => 'MYT', + self::MEXICO => 'MEX', + self::MICRONESIA_FEDERATED_STATES_OF => 'FSM', + self::MOLDOVA_REPUBLIC_OF => 'MDA', + self::MONACO => 'MCO', + self::MONGOLIA => 'MNG', + self::MONTENEGRO => 'MNE', + self::MONTSERRAT => 'MSR', + self::MOROCCO => 'MAR', + self::MOZAMBIQUE => 'MOZ', + self::MYANMAR => 'MMR', + self::NAMIBIA => 'NAM', + self::NAURU => 'NRU', + self::NEPAL => 'NPL', + self::NETHERLANDS_KINGDOM_OF_THE => 'NLD', + self::NEW_CALEDONIA => 'NCL', + self::NEW_ZEALAND => 'NZL', + self::NICARAGUA => 'NIC', + self::NIGER => 'NER', + self::NIGERIA => 'NGA', + self::NIUE => 'NIU', + self::NORFOLK_ISLAND => 'NFK', + self::NORTH_MACEDONIA => 'MKD', + self::NORTHERN_MARIANA_ISLANDS => 'MNP', + self::NORWAY => 'NOR', + self::OMAN => 'OMN', + self::PAKISTAN => 'PAK', + self::PALAU => 'PLW', + self::PALESTINE_STATE_OF => 'PSE', + self::PANAMA => 'PAN', + self::PAPUA_NEW_GUINEA => 'PNG', + self::PARAGUAY => 'PRY', + self::PERU => 'PER', + self::PHILIPPINES => 'PHL', + self::PITCAIRN => 'PCN', + self::POLAND => 'POL', + self::PORTUGAL => 'PRT', + self::PUERTO_RICO => 'PRI', + self::QATAR => 'QAT', + self::REUNION => 'REU', + self::ROMANIA => 'ROU', + self::RUSSIAN_FEDERATION => 'RUS', + self::RWANDA => 'RWA', + self::SAINT_BARTHELEMY => 'BLM', + self::SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA => 'SHN', + self::SAINT_KITTS_AND_NEVIS => 'KNA', + self::SAINT_LUCIA => 'LCA', + self::SAINT_MARTIN_FRENCH_PART => 'MAF', + self::SAINT_PIERRE_AND_MIQUELON => 'SPM', + self::SAINT_VINCENT_AND_THE_GRENADINES => 'VCT', + self::SAMOA => 'WSM', + self::SAN_MARINO => 'SMR', + self::SAO_TOME_AND_PRINCIPE => 'STP', + self::SAUDI_ARABIA => 'SAU', + self::SENEGAL => 'SEN', + self::SERBIA => 'SRB', + self::SEYCHELLES => 'SYC', + self::SIERRA_LEONE => 'SLE', + self::SINGAPORE => 'SGP', + self::SINT_MAARTEN_DUTCH_PART => 'SXM', + self::SLOVAKIA => 'SVK', + self::SLOVENIA => 'SVN', + self::SOLOMON_ISLANDS => 'SLB', + self::SOMALIA => 'SOM', + self::SOUTH_AFRICA => 'ZAF', + self::SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS => 'SGS', + self::SOUTH_SUDAN => 'SSD', + self::SPAIN => 'ESP', + self::SRI_LANKA => 'LKA', + self::SUDAN => 'SDN', + self::SURINAME => 'SUR', + self::SVALBARD_AND_JAN_MAYEN => 'SJM', + self::SWEDEN => 'SWE', + self::SWITZERLAND => 'CHE', + self::SYRIAN_ARAB_REPUBLIC => 'SYR', + self::TAIWAN_PROVINCE_OF_CHINA => 'TWN', + self::TAJIKISTAN => 'TJK', + self::TANZANIA_UNITED_REPUBLIC_OF => 'TZA', + self::THAILAND => 'THA', + self::TIMOR_LESTE => 'TLS', + self::TOGO => 'TGO', + self::TOKELAU => 'TKL', + self::TONGA => 'TON', + self::TRINIDAD_AND_TOBAGO => 'TTO', + self::TUNISIA => 'TUN', + self::TURKIYE => 'TUR', + self::TURKMENISTAN => 'TKM', + self::TURKS_AND_CAICOS_ISLANDS => 'TCA', + self::TUVALU => 'TUV', + self::UGANDA => 'UGA', + self::UKRAINE => 'UKR', + self::UNITED_ARAB_EMIRATES => 'ARE', + self::UNITED_KINGDOM_OF_GREAT_BRITAIN_AND_NORTHERN_IRELAND => 'GBR', + self::UNITED_STATES_MINOR_OUTLYING_ISLANDS => 'UMI', + self::UNITED_STATES_OF_AMERICA => 'USA', + self::URUGUAY => 'URY', + self::UZBEKISTAN => 'UZB', + self::VANUATU => 'VUT', + self::VENEZUELA_BOLIVARIAN_REPUBLIC_OF => 'VEN', + self::VIET_NAM => 'VNM', + self::VIRGIN_ISLANDS_BRITISH => 'VGB', + self::VIRGIN_ISLANDS_US => 'VIR', + self::WALLIS_AND_FUTUNA => 'WLF', + self::WESTERN_SAHARA => 'ESH', + self::YEMEN => 'YEM', + self::ZAMBIA => 'ZMB', + self::ZIMBABWE => 'ZWE' + }; + + } + + /** + * ### Country's continent or ocean + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Geo\Continent|\FireHub\Core\Type\Geo\Ocean Country's continent or ocean. + */ + public function continentOrOcean ():Continent|Ocean { + + return match ($this) { + self::AFGHANISTAN, self::BANGLADESH, self::BHUTAN, self::INDIA, self::IRAN_ISLAMIC_REPUBLIC_OF, + self::MALDIVES, self::NEPAL, self::PAKISTAN, self::SRI_LANKA, self::ARMENIA, self::AZERBAIJAN, + self::BAHRAIN, self::CYPRUS, self::GEORGIA, self::IRAQ, self::ISRAEL, self::JORDAN, self::KUWAIT, + self::LEBANON, self::OMAN, self::PALESTINE_STATE_OF, self::QATAR, self::SAUDI_ARABIA, + self::SYRIAN_ARAB_REPUBLIC, self::TURKIYE, self::UNITED_ARAB_EMIRATES, self::YEMEN, + self::BRUNEI_DARUSSALAM, self::CAMBODIA, self::INDONESIA, self::LAO_PEOPLES_DEMOCRATIC_REPUBLIC, + self::MALAYSIA, self::MYANMAR, self::PHILIPPINES, self::SINGAPORE, self::THAILAND, self::TIMOR_LESTE, + self::VIET_NAM, self::CHINA, self::HONG_KONG, self::JAPAN, self::KOREA_DEMOCRATIC_PEOPLES_REPUBLIC_OF, + self::KOREA_REPUBLIC_OF, self::MACAO, self::MONGOLIA, self::TAIWAN_PROVINCE_OF_CHINA, self::KAZAKHSTAN, + self::KYRGYZSTAN, self::TAJIKISTAN, self::TURKMENISTAN, self::UZBEKISTAN + => Continent::ASIA, + self::ALAND_ISLANDS, self::DENMARK, self::ESTONIA, self::FAROE_ISLANDS, self::FINLAND, self::GUERNSEY, + self::ICELAND, self::IRELAND, self::ISLE_OF_MAN, self::JERSEY, self::LATVIA, self::LITHUANIA, self::NORWAY, + self::SVALBARD_AND_JAN_MAYEN, self::SWEDEN, self::UNITED_KINGDOM_OF_GREAT_BRITAIN_AND_NORTHERN_IRELAND, + self::ALBANIA, self::ANDORRA, self::BOSNIA_AND_HERZEGOVINA, self::CROATIA, self::GIBRALTAR, self::GREECE, + self::HOLY_SEE, self::ITALY, self::KOSOVO, self::MALTA, self::MONTENEGRO, self::NORTH_MACEDONIA, + self::PORTUGAL, self::SAN_MARINO, self::SERBIA, self::SLOVENIA, self::SPAIN, self::AUSTRIA, + self::BELGIUM, self::FRANCE, self::GERMANY, self::LIECHTENSTEIN, self::LUXEMBOURG, self::MONACO, + self::NETHERLANDS_KINGDOM_OF_THE, self::SWITZERLAND, self::BELARUS, self::BULGARIA, self::CZECHIA, + self::HUNGARY, self::MOLDOVA_REPUBLIC_OF, self::POLAND, self::ROMANIA, self::RUSSIAN_FEDERATION, + self::SLOVAKIA, self::UKRAINE + => Continent::EUROPE, + self::ALGERIA, self::EGYPT, self::LIBYA, self::MOROCCO, self::SUDAN, self::TUNISIA, self::WESTERN_SAHARA, + self::ANGOLA, self::CAMEROON, self::CENTRAL_AFRICAN_REPUBLIC, self::CHAD, self::CONGO, + self::CONGO_DEMOCRATIC_REPUBLIC_OF_THE, self::EQUATORIAL_GUINEA, self::GABON, self::SAO_TOME_AND_PRINCIPE, + self::BOTSWANA, self::ESWATINI, self::LESOTHO, self::NAMIBIA, self::SOUTH_AFRICA, + self::BRITISH_INDIAN_OCEAN_TERRITORY, self::BURUNDI, self::COMOROS, self::DJIBOUTI, self::ERITREA, + self::ETHIOPIA, self::FRENCH_SOUTHERN_TERRITORIES, self::KENYA, self::MADAGASCAR, self::MALAWI, + self::MAURITIUS, self::MAYOTTE, self::MOZAMBIQUE, self::REUNION, self::RWANDA, self::SEYCHELLES, + self::SOMALIA, self::SOUTH_SUDAN, self::TANZANIA_UNITED_REPUBLIC_OF, self::UGANDA, self::ZAMBIA, + self::ZIMBABWE, self::BENIN, self::BURKINA_FASO, self::CABO_VERDE, self::COTE_D_IVOIRE, self::GAMBIA, + self::GHANA, self::GUINEA, self::GUINEA_BISSAU, self::LIBERIA, self::MALI, self::MAURITANIA, self::NIGER, + self::NIGERIA, self::SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA, self::SENEGAL, self::SIERRA_LEONE, + self::TOGO + => Continent::AFRICA, + self::AMERICAN_SAMOA, self::COOK_ISLANDS, self::FRENCH_POLYNESIA, self::NIUE, self::PITCAIRN, self::SAMOA, + self::TOKELAU, self::TONGA, self::TUVALU, self::WALLIS_AND_FUTUNA, self::FIJI, self::NEW_CALEDONIA, + self::PAPUA_NEW_GUINEA, self::SOLOMON_ISLANDS, self::VANUATU, self::GUAM, self::KIRIBATI, + self::MARSHALL_ISLANDS, self::MICRONESIA_FEDERATED_STATES_OF, self::NAURU, + self::NORTHERN_MARIANA_ISLANDS, self::PALAU, self::UNITED_STATES_MINOR_OUTLYING_ISLANDS, + self::CHRISTMAS_ISLAND, self::COCOS_KEELING_ISLANDS, self::HEARD_ISLAND_AND_MCDONALD_ISLANDS, + self::NEW_ZEALAND, self::NORFOLK_ISLAND + => Ocean::PACIFIC, + self::ANGUILLA, self::ANTIGUA_AND_BARBUDA, self::ARUBA, self::BAHAMAS, self::BARBADOS, + self::BONAIRE_SINT_EUSTATIUS_AND_SABA, self::CAYMAN_ISLANDS, self::CUBA, self::CURACAO, self::DOMINICA, + self::DOMINICAN_REPUBLIC, self::GRENADA, self::GUADELOUPE, self::HAITI, self::JAMAICA, self::MARTINIQUE, + self::MONTSERRAT, self::PUERTO_RICO, self::SAINT_BARTHELEMY, self::SAINT_KITTS_AND_NEVIS, self::SAINT_LUCIA, + self::SAINT_MARTIN_FRENCH_PART, self::SAINT_VINCENT_AND_THE_GRENADINES, self::SINT_MAARTEN_DUTCH_PART, + self::TRINIDAD_AND_TOBAGO, self::TURKS_AND_CAICOS_ISLANDS, self::VIRGIN_ISLANDS_BRITISH, + self::VIRGIN_ISLANDS_US, self::BERMUDA, self::CANADA, self::GREENLAND, self::SAINT_PIERRE_AND_MIQUELON, + self::UNITED_STATES_OF_AMERICA, self::BELIZE, self::COSTA_RICA, self::EL_SALVADOR, self::GUATEMALA, + self::HONDURAS, self::MEXICO, self::NICARAGUA, self::PANAMA + => Continent::NORTH_AMERICA, + self::ANTARCTICA + => Continent::ANTARCTICA, + self::ARGENTINA, self::BOLIVIA_PLURINATIONAL_STATE_OF, self::BOUVET_ISLAND, self::BRAZIL, self::CHILE, + self::COLOMBIA, self::ECUADOR, self::FALKLAND_ISLANDS_MALVINAS, self::FRENCH_GUIANA, self::GUYANA, + self::PARAGUAY, self::PERU, self::SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS, self::SURINAME, + self::URUGUAY, self::VENEZUELA_BOLIVARIAN_REPUBLIC_OF + => Continent::SOUTH_AMERICA, + self::AUSTRALIA + => Continent::AUSTRALIA + }; + + } + + /** + * ### Checks if the country is independent or not + * @since 1.0.0 + * + * @return bool True if country is independent, false otherwise. + */ + public function independent ():bool { + + return match ($this) { + self::ALAND_ISLANDS, self::AMERICAN_SAMOA, self::ANGUILLA, self::ANTARCTICA, self::ARUBA, self::BERMUDA, + self::BONAIRE_SINT_EUSTATIUS_AND_SABA, self::BOUVET_ISLAND, self::BRITISH_INDIAN_OCEAN_TERRITORY, + self::CAYMAN_ISLANDS, self::CHRISTMAS_ISLAND, self::COCOS_KEELING_ISLANDS, self::COOK_ISLANDS, self::CURACAO, + self::FALKLAND_ISLANDS_MALVINAS, self::FAROE_ISLANDS, self::FRENCH_GUIANA, self::FRENCH_POLYNESIA, + self::FRENCH_SOUTHERN_TERRITORIES, self::GIBRALTAR, self::GREENLAND, self::GUADELOUPE, self::GUAM, + self::GUERNSEY, self::HEARD_ISLAND_AND_MCDONALD_ISLANDS, self::HONG_KONG, self::ISLE_OF_MAN, + self::JERSEY, self::KOSOVO, self::MACAO, self::MARTINIQUE, self::MAYOTTE, self::MONTSERRAT, + self::NEW_CALEDONIA, self::NIUE, self::NORFOLK_ISLAND, self::NORTHERN_MARIANA_ISLANDS, + self::PALESTINE_STATE_OF, self::PITCAIRN, self::PUERTO_RICO, self::REUNION, self::SAINT_BARTHELEMY, + self::SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA, self::SAINT_MARTIN_FRENCH_PART, + self::SAINT_PIERRE_AND_MIQUELON, self::SINT_MAARTEN_DUTCH_PART, + self::SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS, self::SVALBARD_AND_JAN_MAYEN, + self::TAIWAN_PROVINCE_OF_CHINA, self::TOKELAU, self::TURKS_AND_CAICOS_ISLANDS, + self::UNITED_STATES_MINOR_OUTLYING_ISLANDS, self::VIRGIN_ISLANDS_BRITISH, self::VIRGIN_ISLANDS_US, + self::WALLIS_AND_FUTUNA, self::WESTERN_SAHARA => false, + default => true + }; + + } + + /** + * ### Check country's region + * @since 1.0.0 + * + * @uses \FireHub\Core\Boundary\Type\Geo\M49::parent() To get parent. + * + * @param \FireHub\Core\Boundary\Type\Geo\M49 $region

+ * The region to check for. + *

+ * @param null|\FireHub\Core\Boundary\Type\Geo\M49 $current

+ * Current region. + *

+ * + * @return bool True if country is a region type, false otherwise. + */ + private function check (M49 $region, ?M49 $current):bool { + + if ($current === null) return false; + + if ($current === $region) return true; + + return $this->check($region, $current->parent()); + + } + } \ No newline at end of file From db177fd9440d3a6aa7b1225b7af29342dccd7cac Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 25 Aug 2026 13:15:15 +0200 Subject: [PATCH 030/118] Refine `Country` enum return types for clearer nullability **Details:** - Updated `fromAlpha2(string $code): self|false` to `fromAlpha2(string $code): ?self` to replace `false` with `null` as the return value when no match is found. - Updated `fromAlpha3(string $code): self|false` to `fromAlpha3(string $code): ?self` with the same adjustment. - Updated PHPDocs accordingly to reflect the nullability changes. This refinement aligns with modern PHP typing standards, ensuring clearer, more predictable handling of nullability while improving code readability and maintainability. --- src/Type/Geo/Country.php | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/Type/Geo/Country.php b/src/Type/Geo/Country.php index 73bac31..c3f55b6 100644 --- a/src/Type/Geo/Country.php +++ b/src/Type/Geo/Country.php @@ -1285,14 +1285,14 @@ enum Country:string implements M49, ISO3166 { * * @uses \FireHub\Core\Type\Geo\Country::alpha2() To check alpha 2 code for country. * - * @return self|false Returns country if found or `false` if country not found. + * @return null|self Returns country if found or null if country not found. */ - public static function fromAlpha2 (string $code):self|false { + public static function fromAlpha2 (string $code):?self { foreach (self::cases() as $case) if ($case->alpha2() === $code) return $case; - return false; + return null; } @@ -1302,14 +1302,14 @@ public static function fromAlpha2 (string $code):self|false { * * @uses \FireHub\Core\Type\Geo\Country::alpha3() To check alpha 3 code for country. * - * @return self|false Returns country if found or `false` if country not found. + * @return null|self Returns country if found or null if country not found. */ - public static function fromAlpha3 (string $code):self|false { + public static function fromAlpha3 (string $code):?self { foreach (self::cases() as $case) if ($case->alpha3() === $code) return $case; - return false; + return null; } From 2c0b69d918f1ca9af99fc4f3b1d06c50cc65b07d Mon Sep 17 00:00:00 2001 From: Riddick Date: Wed, 26 Aug 2026 08:58:25 +0200 Subject: [PATCH 031/118] Remove `withEncoding` method from `StringValue` Value Object **Details:** - Deleted the abstract `withEncoding(Encoding $encoding): static` method from the `StringValue` contract. - Removed the associated PHPDoc comments describing the method. This removal simplifies the `StringValue` abstraction by eliminating unused or redundant functionality, aligning with FireHub's principles of clarity, minimalism, and maintainability. --- src/Type/StringValue.php | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/src/Type/StringValue.php b/src/Type/StringValue.php index 48bbe81..c5e5026 100644 --- a/src/Type/StringValue.php +++ b/src/Type/StringValue.php @@ -49,18 +49,6 @@ abstract public function value ():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 * From 01047cf99f1fc4a55eb787ba334e91b6cc89fe94 Mon Sep 17 00:00:00 2001 From: Riddick Date: Wed, 26 Aug 2026 09:00:32 +0200 Subject: [PATCH 032/118] Remove `withTimezone` method from `DateTime` contract **Details:** - Deleted the abstract `withTimezone(Timezone $timezone): static` method from `DateTime`. - Removed the associated PHPDoc comments describing the method. This simplifies the `DateTime` contract by eliminating unused or redundant functionality, aligning with FireHub's principles of clarity, minimalism, and maintainability. --- src/Type/Temporal/DateTime.php | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/src/Type/Temporal/DateTime.php b/src/Type/Temporal/DateTime.php index a50447d..66ee8ea 100644 --- a/src/Type/Temporal/DateTime.php +++ b/src/Type/Temporal/DateTime.php @@ -49,18 +49,6 @@ abstract public function timezone ():Timezone; */ abstract public function value ():string; - /** - * ### Returns a new instance with the specified timezone - * @since 1.0.0 - * - * @param \FireHub\Core\Type\Temporal\Timezone $timezone

- * The timezone to set. - *

- * - * @return static The new instance with provided timezone. - */ - abstract public function withTimezone (Timezone $timezone):static; - /** * ### Returns the string representation of the value * From f3fe593c3c323fa8fec5acd822d121bafb43a3e6 Mon Sep 17 00:00:00 2001 From: Riddick Date: Wed, 26 Aug 2026 10:48:26 +0200 Subject: [PATCH 033/118] Add `Timestamp` and `Epoch` abstractions to support immutable temporal concepts **Details:** - Introduced the `Timestamp` abstract Value Object in `Core-Standard/src/Type/Temporal/Timestamp.php`: - Represents an immutable point in time measured from a defined epoch. - Extends the `Number` Value Object to provide core semantics of timestamp values, delegating implementation details to the `Foundation` and `Runtime` layers. - Enhanced the `DateTime` contract with a new abstract method: - `timestamp(): \FireHub\Core\Type\Temporal\Timestamp` to retrieve the timestamp of a date-time value. - Updated PHPDocs for consistency and clarity. - Added `Epoch` enum in `Core-Standard/src/Meta/Enum/Date/Epoch.php`: - Defines supported temporal epochs: UNIX, GPS, NTP, Windows NT, Excel, and Y2K. - Provides detailed metadata for each epoch, including epoch-specific offsets and descriptions. - Added utility method `unixOffset(): int` to compute Unix epoch offsets for supported epochs, ensuring compatibility with standard temporal calculations. These changes establish a robust framework for handling immutable temporal concepts in the FireHub Core, adhering to principles of precision, clarity, and extensibility. --- src/Meta/Enum/Date/Epoch.php | 135 ++++++++++++++++++++++++++++++++ src/Type/Temporal/DateTime.php | 8 ++ src/Type/Temporal/Timestamp.php | 33 ++++++++ 3 files changed, 176 insertions(+) create mode 100644 src/Meta/Enum/Date/Epoch.php create mode 100644 src/Type/Temporal/Timestamp.php diff --git a/src/Meta/Enum/Date/Epoch.php b/src/Meta/Enum/Date/Epoch.php new file mode 100644 index 0000000..96ae953 --- /dev/null +++ b/src/Meta/Enum/Date/Epoch.php @@ -0,0 +1,135 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date; + +/** + * ### Defines supported temporal epochs + * + * The Epoch enum defines the reference points from which timestamp values are measured. + * + * Each epoch represents a fixed point in time from which elapsed seconds and fractional seconds can be calculated. + * @since 1.0.0 + */ +enum Epoch:string { + + /** + * ### Unix epoch + * + * Unix Epoch used in POSIX time, used by Unix and Unix-like systems (Linux, macOS, Android), and programming + * languages: most C/C++ implementations, [32] Java, JavaScript, Perl, PHP, Python, Ruby, Tcl, ActionScript. + * Also used by Precision Time Protocol. + * + * + * 1970-01-01T00:00:00+00:00 + * + * + * @since 1.0.0 + */ + case UNIX = '1970-01-01T00:00:00+00:00'; + + /** + * ### GPS epoch + * + * The GPS epoch is the reference point used by the Global Positioning System (GPS) timescale. + * It begins at 1980-01-06T00:00:00+00:00 and is used as the starting point for measuring GPS time in seconds and + * fractional seconds. + * + * + * 1980-01-06T00:00:00+00:00 + * + * + * @since 1.0.0 + */ + case GPS = '1980-01-06T00:00:00+00:00'; + + /** + * ### NTP epoch + * + * The NTP epoch is the reference point used by the Network Time Protocol (NTP) timescale. + * It begins at 1900-01-01T00:00:00+00:00 and is used as the starting point for measuring NTP time in seconds and + * fractional seconds. + * + * + * 1900-01-01T00:00:00+00:00 + * + * + * @since 1.0.0 + */ + case NTP = '1900-01-01T00:00:00+00:00'; + + /** + * ### Windows NT epoch + * + * The Windows NT epoch is the reference point used by the Windows NT family of operating systems. + * It begins at 1601-01-01T00:00:00+00:00 and is used as the starting point for measuring Windows NT time in seconds + * and fractional seconds. + * + * + * 1601-01-01T00:00:00+00:00 + * + * + * @since 1.0.0 + */ + case WINDOWS_NT = '1601-01-01T00:00:00+00:00'; + + /** + * ### Excel epoch + * + * The Excel epoch is the reference point used by Microsoft Excel's serial date system. + * It begins at 1899-12-30T00:00:00+00:00 and is used as the starting point for measuring Excel serial date and + * time values. + * + * + * 1899-12-30T00:00:00+00:00 + * + * + * @since 1.0.0 + */ + case EXCEL = '1899-12-30T00:00:00+00:00'; + + /** + * ### Y2K epoch + * + * The Y2K epoch is the reference point marking the beginning of the year 2000. + * It begins at 2000-01-01T00:00:00+00:00 and can be used as an alternative starting point for measuring time. + * + * + * 2000-01-01T00:00:00+00:00 + * + * + * @since 1.0.0 + */ + case Y2K = '2000-01-01T00:00:00+00:00'; + + /** + * ### Returns the Unix epoch offset in seconds + * @since 1.0.0 + * + * @return int Unix epoch offset in seconds + */ + public function unixOffset ():int { + + return match ($this) { + self::UNIX => 0, + self::GPS => 315964800, + self::NTP => 2208988800, + self::WINDOWS_NT => -11644473600, + self::EXCEL => -2209161600, + self::Y2K => 946684800, + }; + + } + + +} \ No newline at end of file diff --git a/src/Type/Temporal/DateTime.php b/src/Type/Temporal/DateTime.php index 66ee8ea..0adc7d9 100644 --- a/src/Type/Temporal/DateTime.php +++ b/src/Type/Temporal/DateTime.php @@ -42,6 +42,14 @@ */ abstract public function timezone ():Timezone; + /** + * ### Returns the timestamp of the date and time value + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Temporal\Timestamp The timestamp of the date and time value. + */ + abstract public function timestamp ():Timestamp; + /** * @inheritDoc * diff --git a/src/Type/Temporal/Timestamp.php b/src/Type/Temporal/Timestamp.php new file mode 100644 index 0000000..4d955c9 --- /dev/null +++ b/src/Type/Temporal/Timestamp.php @@ -0,0 +1,33 @@ + + * @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\Temporal; + +use FireHub\Core\Type\Number; + +/** + * ### Defines an immutable timestamp value object contract + * + * The Timestamp class represents an immutable point in time measured relative to a defined epoch. + * + * It provides the fundamental contract for timestamp values across the FireHub ecosystem while leaving timestamp + * representation, arithmetic, conversion, and execution details to the Foundation and Runtime layers. + * + * The class defines the core semantics of a timestamp without providing implementation-specific behavior. + * @since 1.0.0 + * + * @template TValue of numeric|numeric-string + * + * @extends \FireHub\Core\Type\Number + */ +abstract readonly class Timestamp extends Number {} \ No newline at end of file From dd190a53e6da8a1def880821b37a7268df5caf5f Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 27 Aug 2026 09:17:18 +0200 Subject: [PATCH 034/118] Add comprehensive date and time format abstractions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Details:** - Introduced multiple enums to represent date and time formatting tokens in `Core-Standard/src/Meta/Enum/Date`: - **`Day`**, **`WeekDay`**, **`Week`**, **`Month`**, and **`Year`** for various date components. - **`Time`** and **`Timezone`** for representing time and timezone format characters. - Each enum implements the newly defined `Token` interface to standardize token behavior. - Enhanced `Format` enum to implement the `Token` interface for consistency. - Added new utility methods across enums to improve usability and align with existing conventions: - Methods for retrieving textual representations (e.g., `longName`, `shortName`) in `Day`, `Month`, and `WeekDay`. - Logical operations like ISO conversions (e.g., `isoValue`) and day calculations. - Structured tokens to align with PHP’s native date format specifiers for seamless integration. These changes provide an extensible, modular framework for handling date and time formatting across FireHub Core, promoting consistency, reusability, and strict typing. --- src/Meta/Enum/Date/Format.php | 15 ++- src/Meta/Enum/Date/Format/Day.php | 142 +++++++++++++++++++ src/Meta/Enum/Date/Format/Month.php | 102 ++++++++++++++ src/Meta/Enum/Date/Format/Time.php | 180 +++++++++++++++++++++++++ src/Meta/Enum/Date/Format/Timezone.php | 102 ++++++++++++++ src/Meta/Enum/Date/Format/Token.php | 35 +++++ src/Meta/Enum/Date/Format/Week.php | 50 +++++++ src/Meta/Enum/Date/Format/Year.php | 76 +++++++++++ src/Meta/Enum/Date/Month.php | 172 +++++++++++++++++++++++ src/Meta/Enum/Date/WeekDay.php | 145 ++++++++++++++++++++ 10 files changed, 1018 insertions(+), 1 deletion(-) create mode 100644 src/Meta/Enum/Date/Format/Day.php create mode 100644 src/Meta/Enum/Date/Format/Month.php create mode 100644 src/Meta/Enum/Date/Format/Time.php create mode 100644 src/Meta/Enum/Date/Format/Timezone.php create mode 100644 src/Meta/Enum/Date/Format/Token.php create mode 100644 src/Meta/Enum/Date/Format/Week.php create mode 100644 src/Meta/Enum/Date/Format/Year.php create mode 100644 src/Meta/Enum/Date/Month.php create mode 100644 src/Meta/Enum/Date/WeekDay.php diff --git a/src/Meta/Enum/Date/Format.php b/src/Meta/Enum/Date/Format.php index d8df994..c954ed2 100644 --- a/src/Meta/Enum/Date/Format.php +++ b/src/Meta/Enum/Date/Format.php @@ -13,6 +13,8 @@ namespace FireHub\Core\Meta\Enum\Date; +use FireHub\Core\Meta\Enum\Date\Format\Token; + /** * ### Provides predefined date and time formatting standards * @@ -23,7 +25,7 @@ * objects to maintain support for arbitrary custom PHP format strings. * @since 1.0.0 */ -enum Format:string { +enum Format:string implements Token { /** * ### ISO 8601 calendar date @@ -190,4 +192,15 @@ enum Format:string { */ case RSS = 'D, d M Y H:i:s O'; + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():string { + + return $this->value; + + } + } \ No newline at end of file diff --git a/src/Meta/Enum/Date/Format/Day.php b/src/Meta/Enum/Date/Format/Day.php new file mode 100644 index 0000000..ac2e12d --- /dev/null +++ b/src/Meta/Enum/Date/Format/Day.php @@ -0,0 +1,142 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date\Format; + +/** + * ### Defines day format tokens + * + * The Day enum defines the supported format tokens for representing the day of the month or day of the week. + * + * Each case corresponds to a native PHP date and time format character and represents a specific day representation, + * such as numeric, zero-padded numeric, abbreviated textual, or full textual output. + * @since 1.0.0 + */ +enum Day:string implements Token { + + /** + * ### Day of the month without leading zeros + * + * A numeric representation of the day of the month without leading zeros. + * + * + * 1-31 + * + * + * @since 1.0.0 + */ + case NUMBER = 'j'; + + /** + * ### Day of the month with leading zeros + * + * A two-digit numeric representation of the day of the month. + * + * + * 01-31 + * + * + * @since 1.0.0 + */ + case NUMBER_PADDED = 'd'; + + /** + * ### Short textual day name + * + * A three-letter textual representation of the day of the week. + * + * + * Mon-Sun + * + * + * @since 1.0.0 + */ + case TEXT_SHORT = 'D'; + + /** + * ### Full textual day name + * + * The full textual representation of the day of the week. + * + * + * Monday-Sunday + * + * + * @since 1.0.0 + */ + case TEXT_LONG = 'l'; + + /** + * ### Day of the year + * + * A numeric representation of the day of the year, starting at zero. + * + * + * 0-365 + * + * + * @since 1.0.0 + */ + case DAY_OF_YEAR = 'z'; + + /** + * ### Day of the week + * + * A numeric representation of the day of the week, with Sunday represented by zero. + * + * + * 0-6 + * + * + * @since 1.0.0 + */ + case DAY_OF_WEEK = 'w'; + + /** + * ### ISO day of the week + * + * A numeric representation of the ISO-8601 day of the week, with Monday represented by one and Sunday by seven. + * + * + * 1-7 + * + * + * @since 1.0.0 + */ + case ISO_DAY_OF_WEEK = 'N'; + + /** + * ### English ordinal suffix + * + * The English ordinal suffix for the day of the month. + * + * + * st, nd, rd, th + * + * + * @since 1.0.0 + */ + case ORDINAL_SUFFIX = 'S'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():string { + + return $this->value; + + } + +} \ No newline at end of file diff --git a/src/Meta/Enum/Date/Format/Month.php b/src/Meta/Enum/Date/Format/Month.php new file mode 100644 index 0000000..f6871fc --- /dev/null +++ b/src/Meta/Enum/Date/Format/Month.php @@ -0,0 +1,102 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date\Format; + +/** + * ### Defines month format tokens + * + * The Month enum defines the supported format tokens for representing the month and its properties. + * + * Each case corresponds to a native PHP date and time format character. + * @since 1.0.0 + */ +enum Month:string implements Token { + + /** + * ### Full textual month name + * + * The full textual representation of the month. + * + * + * January-December + * + * + * @since 1.0.0 + */ + case TEXT_LONG = 'F'; + + /** + * ### Short textual month name + * + * A three-letter textual representation of the month. + * + * + * Jan-Dec + * + * + * @since 1.0.0 + */ + case TEXT_SHORT = 'M'; + + /** + * ### Month number with leading zero + * + * A two-digit numeric representation of the month. + * + * + * 01-12 + * + * + * @since 1.0.0 + */ + case NUMBER_PADDED = 'm'; + + /** + * ### Month number without leading zero + * + * A numeric representation of the month without leading zeros. + * + * + * 1-12 + * + * + * @since 1.0.0 + */ + case NUMBER = 'n'; + + /** + * ### Number of days in the month + * + * The number of days in the month is represented by the current date. + * + * + * 28-31 + * + * + * @since 1.0.0 + */ + case DAYS_IN_MONTH = 't'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():string { + + return $this->value; + + } + +} \ No newline at end of file diff --git a/src/Meta/Enum/Date/Format/Time.php b/src/Meta/Enum/Date/Format/Time.php new file mode 100644 index 0000000..361d323 --- /dev/null +++ b/src/Meta/Enum/Date/Format/Time.php @@ -0,0 +1,180 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date\Format; + +/** + * ### Defines time format tokens + * + * The Time enum defines the supported format tokens for representing the time of day and its fractional components. + * + * Each case corresponds to a native PHP date and time format character. + * @since 1.0.0 + */ +enum Time:string implements Token { + + /** + * ### Uppercase ante meridiem or post meridiem + * + * A textual representation indicating whether the time is before or after noon. + * + * + * AM or PM + * + * + * @since 1.0.0 + */ + case MERIDIEM_UPPER = 'A'; + + /** + * ### Lowercase ante meridiem or post meridiem + * + * A lowercase textual representation indicating whether the time is before or after noon. + * + * + * am or pm + * + * + * @since 1.0.0 + */ + case MERIDIEM_LOWER = 'a'; + + /** + * ### Swatch Internet Time + * + * The current time in Swatch Internet Time, represented as beats from 000 to 999. + * + * + * 000-999 + * + * + * @since 1.0.0 + */ + case SWATCH_BEAT = 'B'; + + /** + * ### Hour in 12-hour format + * + * A numeric representation of the hour in a 12-hour format without leading zeros. + * + * + * 1-12 + * + * + * @since 1.0.0 + */ + case HOUR_12 = 'g'; + + /** + * ### Hour in 24-hour format + * + * A numeric representation of the hour in a 24-hour format without leading zeros. + * + * + * 0-23 + * + * + * @since 1.0.0 + */ + case HOUR_24 = 'G'; + + /** + * ### Hour in 12-hour format with leading zero + * + * A two-digit numeric representation of the hour in 12-hour format. + * + * + * 01-12 + * + * + * @since 1.0.0 + */ + case HOUR_12_PADDED = 'h'; + + /** + * ### Hour in 24-hour format with leading zero + * + * A two-digit numeric representation of the hour in 24-hour format. + * + * + * 00-23 + * + * + * @since 1.0.0 + */ + case HOUR_24_PADDED = 'H'; + + /** + * ### Minutes with leading zero + * + * A two-digit numeric representation of the minutes. + * + * + * 00-59 + * + * + * @since 1.0.0 + */ + case MINUTE = 'i'; + + /** + * ### Seconds with leading zero + * + * A two-digit numeric representation of the seconds. + * + * + * 00-59 + * + * + * @since 1.0.0 + */ + case SECOND = 's'; + + /** + * ### Milliseconds + * + * A three-digit numeric representation of milliseconds. + * + * + * 000-999 + * + * + * @since 1.0.0 + */ + case MILLISECOND = 'v'; + + /** + * ### Microseconds + * + * A six-digit numeric representation of microseconds. + * + * + * 000000-999999 + * + * + * @since 1.0.0 + */ + case MICROSECOND = 'u'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():string { + + return $this->value; + + } + +} \ No newline at end of file diff --git a/src/Meta/Enum/Date/Format/Timezone.php b/src/Meta/Enum/Date/Format/Timezone.php new file mode 100644 index 0000000..4cdc479 --- /dev/null +++ b/src/Meta/Enum/Date/Format/Timezone.php @@ -0,0 +1,102 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date\Format; + +/** + * ### Defines timezone format tokens + * + * The Timezone enum defines the supported format tokens for representing timezone information and UTC offsets. + * + * Each case corresponds to a native PHP date and time format character. + * @since 1.0.0 + */ +enum Timezone:string implements Token { + + /** + * ### Daylight Saving Time indicator + * + * Indicates whether daylight saving time is currently active. + * + * + * 1 or 0 + * + * + * @since 1.0.0 + */ + case DAYLIGHT_SAVING = 'I'; + + /** + * ### UTC offset in hours + * + * The difference from Coordinated Universal Time (UTC) in hours. + * + * + * +0200 + * + * + * @since 1.0.0 + */ + case OFFSET = 'O'; + + /** + * ### UTC offset with colon + * + * The difference from Coordinated Universal Time (UTC) with a colon separating hours and minutes. + * + * + * +02:00 + * + * + * @since 1.0.0 + */ + case OFFSET_COLON = 'P'; + + /** + * ### Timezone abbreviation + * + * The abbreviated timezone name. + * + * + * CET + * + * + * @since 1.0.0 + */ + case ABBREVIATION = 'T'; + + /** + * ### Timezone offset in seconds + * + * The total timezone offset from UTC, expressed in seconds. + * + * + * 7200 + * + * + * @since 1.0.0 + */ + case OFFSET_SECONDS = 'Z'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():string { + + return $this->value; + + } + +} \ No newline at end of file diff --git a/src/Meta/Enum/Date/Format/Token.php b/src/Meta/Enum/Date/Format/Token.php new file mode 100644 index 0000000..010913a --- /dev/null +++ b/src/Meta/Enum/Date/Format/Token.php @@ -0,0 +1,35 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date\Format; + +/** + * ### Defines a date and time format token + * + * The Token interface defines the common contract for enumerations representing native PHP date and time format + * tokens. + * + * Implementations provide a specific format token used to represent a date or time component. + * @since 1.0.0 + */ +interface Token { + + /** + * ### Returns the format token value + * @since 1.0.0 + * + * @return non-empty-string The format token value. + */ + public function value ():string; + +} \ No newline at end of file diff --git a/src/Meta/Enum/Date/Format/Week.php b/src/Meta/Enum/Date/Format/Week.php new file mode 100644 index 0000000..3db4fb3 --- /dev/null +++ b/src/Meta/Enum/Date/Format/Week.php @@ -0,0 +1,50 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date\Format; + +/** + * ### Defines week format tokens + * + * The Week enum defines the supported format tokens for representing calendar weeks. + * + * Each case corresponds to a native PHP date and time format character. + * @since 1.0.0 + */ +enum Week:string implements Token { + + /** + * ### ISO week number + * + * The ISO-8601 week number of the year. + * + * + * 01-53 + * + * + * @since 1.0.0 + */ + case ISO_NUMBER = 'W'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():string { + + return $this->value; + + } + +} \ No newline at end of file diff --git a/src/Meta/Enum/Date/Format/Year.php b/src/Meta/Enum/Date/Format/Year.php new file mode 100644 index 0000000..38d88d9 --- /dev/null +++ b/src/Meta/Enum/Date/Format/Year.php @@ -0,0 +1,76 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date\Format; + +/** + * ### Defines year format tokens + * + * The Year enum defines the supported format tokens for representing calendar years and leap years. + * + * Each case corresponds to a native PHP date and time format character. + * @since 1.0.0 + */ +enum Year:string implements Token { + + /** + * ### Two-digit year + * + * A two-digit numeric representation of the year. + * + * + * 00-99 + * + * + * @since 1.0.0 + */ + case NUMBER_SHORT = 'y'; + + /** + * ### Four-digit year + * + * A four-digit numeric representation of the year. + * + * + * 0000-9999 + * + * + * @since 1.0.0 + */ + case NUMBER_LONG = 'Y'; + + /** + * ### Leap year indicator + * + * Indicates whether the current year is a leap year. + * + * + * 1 or 0 + * + * + * @since 1.0.0 + */ + case LEAP_YEAR = 'L'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():string { + + return $this->value; + + } + +} \ No newline at end of file diff --git a/src/Meta/Enum/Date/Month.php b/src/Meta/Enum/Date/Month.php new file mode 100644 index 0000000..de19fe8 --- /dev/null +++ b/src/Meta/Enum/Date/Month.php @@ -0,0 +1,172 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date; + +/** + * ### Defines calendar months + * + * The Month enum defines the twelve months of the Gregorian calendar. + * + * Each case represents a specific calendar month and provides its corresponding numeric month value. + * @since 1.0.0 + */ +enum Month:int { + + /** + * ### January + * + * The first month of the Gregorian calendar year. + * @since 1.0.0 + */ + case JANUARY = 1; + + /** + * ### February + * + * The second month of the Gregorian calendar year. + * @since 1.0.0 + */ + case FEBRUARY = 2; + + /** + * ### March + * + * The third month of the Gregorian calendar year. + * @since 1.0.0 + */ + case MARCH = 3; + + /** + * ### April + * + * The fourth month of the Gregorian calendar year. + * @since 1.0.0 + */ + case APRIL = 4; + + /** + * ### May + * + * The fifth month of the Gregorian calendar year. + * @since 1.0.0 + */ + case MAY = 5; + + /** + * ### June + * + * The sixth month of the Gregorian calendar year. + * @since 1.0.0 + */ + case JUNE = 6; + + /** + * ### July + * + * The seventh month of the Gregorian calendar year. + * @since 1.0.0 + */ + case JULY = 7; + + /** + * ### August + * + * The eighth month of the Gregorian calendar year. + * @since 1.0.0 + */ + case AUGUST = 8; + + /** + * ### September + * + * The ninth month of the Gregorian calendar year. + * @since 1.0.0 + */ + case SEPTEMBER = 9; + + /** + * ### October + * + * The tenth month of the Gregorian calendar year. + * @since 1.0.0 + */ + case OCTOBER = 10; + + /** + * ### November + * + * The eleventh month of the Gregorian calendar year. + * @since 1.0.0 + */ + case NOVEMBER = 11; + + /** + * ### December + * + * The twelfth month of the Gregorian calendar year. + * @since 1.0.0 + */ + case DECEMBER = 12; + + /** + * ### Returns the long name of the month + * @since 1.0.0 + * + * @return non-empty-string The long name of the month. + */ + public function longName ():string { + + return match ($this) { + self::JANUARY => 'January', + self::FEBRUARY => 'February', + self::MARCH => 'March', + self::APRIL => 'April', + self::MAY => 'May', + self::JUNE => 'June', + self::JULY => 'July', + self::AUGUST => 'August', + self::SEPTEMBER => 'September', + self::OCTOBER => 'October', + self::NOVEMBER => 'November', + self::DECEMBER => 'December' + }; + + } + + /** + * ### Returns the short name of the month + * @since 1.0.0 + * + * @return non-empty-string The short name of the month. + */ + public function shortName ():string { + + return match ($this) { + self::JANUARY => 'Jan', + self::FEBRUARY => 'Feb', + self::MARCH => 'Mar', + self::APRIL => 'Apr', + self::MAY => 'May', + self::JUNE => 'Jun', + self::JULY => 'Jul', + self::AUGUST => 'Aug', + self::SEPTEMBER => 'Sep', + self::OCTOBER => 'Oct', + self::NOVEMBER => 'Nov', + self::DECEMBER => 'Dec' + }; + + } + +} \ No newline at end of file diff --git a/src/Meta/Enum/Date/WeekDay.php b/src/Meta/Enum/Date/WeekDay.php new file mode 100644 index 0000000..51ec160 --- /dev/null +++ b/src/Meta/Enum/Date/WeekDay.php @@ -0,0 +1,145 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date; + +/** + * ### Defines the days of the week + * + * The Weekday enum defines the seven days of the Gregorian calendar week. + * + * Each case represents a specific day of the week and provides its corresponding numeric value according to the + * native PHP date and time representation. + * @since 1.0.0 + */ +enum WeekDay:int { + + /** + * ### Sunday + * + * The first day of the week according to the native PHP date and time representation. + * @since 1.0.0 + */ + case SUNDAY = 0; + + /** + * ### Monday + * + * The second day of the week according to the native PHP date and time representation. + * @since 1.0.0 + */ + case MONDAY = 1; + + /** + * ### Tuesday + * + * The third day of the week according to the native PHP date and time representation. + * @since 1.0.0 + */ + case TUESDAY = 2; + + /** + * ### Wednesday + * + * The fourth day of the week according to the native PHP date and time representation. + * @since 1.0.0 + */ + case WEDNESDAY = 3; + + /** + * ### Thursday + * + * The fifth day of the week according to the native PHP date and time representation. + * @since 1.0.0 + */ + case THURSDAY = 4; + + /** + * ### Friday + * + * The sixth day of the week according to the native PHP date and time representation. + * @since 1.0.0 + */ + case FRIDAY = 5; + + /** + * ### Saturday + * + * The seventh day of the week according to the native PHP date and time representation. + * @since 1.0.0 + */ + case SATURDAY = 6; + + /** + * ### Returns the ISO weekday number + * + * Returns the numeric representation of the weekday according to ISO 8601, where Monday is 1 and Sunday is 7. + * @since 1.0.0 + * + * @return int<1,7> The ISO weekday number. + */ + public function isoValue ():int { + + return match ($this) { + self::MONDAY => 1, + self::TUESDAY => 2, + self::WEDNESDAY => 3, + self::THURSDAY => 4, + self::FRIDAY => 5, + self::SATURDAY => 6, + self::SUNDAY => 7, + }; + + } + + /** + * ### Returns the long name of the weekday + * @since 1.0.0 + * + * @return non-empty-string The long name of the weekday. + */ + public function longName ():string { + + return match ($this) { + self::SUNDAY => 'Sunday', + self::MONDAY => 'Monday', + self::TUESDAY => 'Tuesday', + self::WEDNESDAY => 'Wednesday', + self::THURSDAY => 'Thursday', + self::FRIDAY => 'Friday', + self::SATURDAY => 'Saturday', + }; + + } + + /** + * ### Returns the short name of the weekday + * @since 1.0.0 + * + * @return non-empty-string The short name of the weekday. + */ + public function shortName ():string { + + return match ($this) { + self::SUNDAY => 'Sun', + self::MONDAY => 'Mon', + self::TUESDAY => 'Tue', + self::WEDNESDAY => 'Wed', + self::THURSDAY => 'Thu', + self::FRIDAY => 'Fri', + self::SATURDAY => 'Sat', + }; + + } + +} \ No newline at end of file From 60b25fed8522497f5a5feac95035fcd6472bbd67 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 27 Aug 2026 12:40:24 +0200 Subject: [PATCH 035/118] Add `Unit` enum to define basic temporal units **Details:** - Introduced the `Unit` enum in `Core-Standard/src/Meta/Enum/Date/Unit.php` to represent fundamental calendar and time units. - Defined temporal units: **Millennium**, **Century**, **Decade**, **Year**, **Quarter**, **Month**, **Fortnight**, **Week**, **Day**, **Hour**, **Minute**, **Second**, **Millisecond**, and **Microsecond**. - Implemented two utility methods for unit operations: - `base(): ?self` - Returns the base unit from which the current unit is derived or `null` for primary units. - `factor(): int` - Retrieves the conversion factor to the base unit for each temporal unit. - Utilized PHP 8.1 native enum features with `strict_types` declaration. This addition provides a comprehensive and type-safe representation of fundamental temporal units, enhancing FireHub Core's capabilities in time-based calculations and abstractions while promoting clarity and extensibility. --- src/Meta/Enum/Date/Unit.php | 190 ++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 src/Meta/Enum/Date/Unit.php diff --git a/src/Meta/Enum/Date/Unit.php b/src/Meta/Enum/Date/Unit.php new file mode 100644 index 0000000..1c5fd63 --- /dev/null +++ b/src/Meta/Enum/Date/Unit.php @@ -0,0 +1,190 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date; + +/** + * ### Defines basic date and time units + * + * The Unit enum defines the fundamental calendar and time units supported by the FireHub temporal system. + * + * Each case represents a basic temporal unit that can be used as a reference for date and time calculations, + * comparisons, intervals, and conversions. + * @since 1.0.0 + */ +enum Unit { + + /** + * ### Millennium + * + * A period of time spanning 1,000 years. + * @since 1.0.0 + */ + case MILLENNIUM; + + /** + * ### Century + * + * A period of time spanning 100 years. + * @since 1.0.0 + */ + case CENTURY; + + /** + * ### Decade + * + * A period of time spanning 10 years. + * @since 1.0.0 + */ + case DECADE; + + /** + * ### Year + * + * A calendar year. + * @since 1.0.0 + */ + case YEAR; + + /** + * ### Quarter + * + * A calendar quarter. + * @since 1.0.0 + */ + case QUARTER; + + /** + * ### Month + * + * A calendar month. + * @since 1.0.0 + */ + case MONTH; + + /** + * ### Fortnight + * + * A period of time spanning 14 days. + * @since 1.0.0 + */ + case FORTNIGHT; + + /** + * ### Week + * + * A calendar week. + * @since 1.0.0 + */ + case WEEK; + + /** + * ### Day + * + * A calendar day. + * @since 1.0.0 + */ + case DAY; + + /** + * ### Hour + * + * An hour of time. + * @since 1.0.0 + */ + case HOUR; + + /** + * ### Minute + * + * A minute of time. + * @since 1.0.0 + */ + case MINUTE; + + /** + * ### Second + * + * A second of time. + * @since 1.0.0 + */ + case SECOND; + + /** + * ### Millisecond + * + * A millisecond of time. + * @since 1.0.0 + */ + case MILLISECOND; + + /** + * ### Microsecond + * + * A microsecond of time. + * @since 1.0.0 + */ + case MICROSECOND; + + /** + * ### Get the base unit + * + * Returns the base temporal unit from which the current unit is derived. + * + * The base unit represents the unit to which the current unit can be reduced using its conversion factor. + * @since 1.0.0 + * + * @return null|self The base unit, or null if the unit is not derived from another unit. + */ + public function base ():?self { + + return match ($this) { + self::MILLENNIUM, self::CENTURY, self::DECADE => self::YEAR, + self::FORTNIGHT, self::WEEK => self::DAY, + self::DAY => self::HOUR, + self::HOUR => self::MINUTE, + self::MINUTE => self::SECOND, + self::SECOND => self::MILLISECOND, + self::MILLISECOND => self::MICROSECOND, + self::YEAR, self::QUARTER, self::MONTH, self::MICROSECOND => null + }; + + } + + /** + * ### Get the conversion factor + * + * Returns the number of base units contained in one instance of the current unit. + * + * The factor defines the relationship between the current unit and its base unit. + * @since 1.0.0 + * + * @return int<1,max> The number of base units represented by one current unit. + */ + public function factor ():int { + + return match ($this) { + self::MILLENNIUM, self::SECOND, self::MILLISECOND => 1000, + self::CENTURY => 100, + self::HOUR, self::MINUTE => 60, + self::DAY => 24, + self::FORTNIGHT => 14, + self::DECADE => 10, + self::WEEK => 7, + self::QUARTER => 3, + self::YEAR, self::MONTH, self::MICROSECOND => 1 + }; + + } + +} \ No newline at end of file From 98e140a111f5ae20be2db1b9c5e5870db3cd0546 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 27 Aug 2026 13:30:19 +0200 Subject: [PATCH 036/118] Add `Ordinal`, `Relative`, `DateKeyword`, and `TimeKeyword` enums to define date and time expressions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Details:** - Introduced the following enums in `Core-Standard/src/Meta/Enum/Date/Expression`: - **`Ordinal`**: Represents ordinal positions (e.g., first through twelfth) for describing temporal occurrences. - **`Relative`**: Defines relative positions (e.g., next, last, previous, this) relative to a reference point. - **`DateKeyword`**: Contains common date-related keywords (e.g., yesterday, today, tomorrow) for parsing human-readable date expressions. - **`TimeKeyword`**: Includes time-related keywords (e.g., midnight, noon, now) for parsing temporal expressions. - Each enum utilizes PHP 8.1 native `enum` features with `strict_types` declared. - Documented all cases with PHPDoc annotations to ensure clarity and maintainability. These additions provide a structured, type-safe foundation for handling natural language date and time expressions within FireHub Core, aligning with FireHub’s principles of extensibility, precision, and semantic clarity. --- src/Meta/Enum/Date/Expression/DateKeyword.php | 50 ++++++++++ src/Meta/Enum/Date/Expression/Ordinal.php | 98 +++++++++++++++++++ src/Meta/Enum/Date/Expression/Relative.php | 59 +++++++++++ src/Meta/Enum/Date/Expression/TimeKeyword.php | 50 ++++++++++ 4 files changed, 257 insertions(+) create mode 100644 src/Meta/Enum/Date/Expression/DateKeyword.php create mode 100644 src/Meta/Enum/Date/Expression/Ordinal.php create mode 100644 src/Meta/Enum/Date/Expression/Relative.php create mode 100644 src/Meta/Enum/Date/Expression/TimeKeyword.php diff --git a/src/Meta/Enum/Date/Expression/DateKeyword.php b/src/Meta/Enum/Date/Expression/DateKeyword.php new file mode 100644 index 0000000..1723acb --- /dev/null +++ b/src/Meta/Enum/Date/Expression/DateKeyword.php @@ -0,0 +1,50 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date\Expression; + +/** + * ### Defines date-related temporal keywords + * + * The DateKeyword enum defines keywords that identify a calendar date relative to the current date. + * + * These values are commonly used when parsing human-readable date and time expressions. + * @since 1.0.0 + */ +enum DateKeyword:string { + + /** + * ### Yesterday + * + * The calendar day immediately preceding the current day. + * @since 1.0.0 + */ + case YESTERDAY = 'yesterday'; + + /** + * ### Today + * + * The current calendar day. + * @since 1.0.0 + */ + case TODAY = 'today'; + + /** + * ### Tomorrow + * + * The calendar day immediately follows the current day. + * @since 1.0.0 + */ + case TOMORROW = 'tomorrow'; + +} \ No newline at end of file diff --git a/src/Meta/Enum/Date/Expression/Ordinal.php b/src/Meta/Enum/Date/Expression/Ordinal.php new file mode 100644 index 0000000..3173aa2 --- /dev/null +++ b/src/Meta/Enum/Date/Expression/Ordinal.php @@ -0,0 +1,98 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date\Expression; + +/** + * ### Defines ordinal positions + * + * The Ordinal enum defines ordinal positions from first through twelfth. + * + * Ordinal positions can be used to describe the position of a temporal occurrence within a larger temporal unit. + * @since 1.0.0 + */ +enum Ordinal:string { + + /** + * ### First + * @since 1.0.0 + */ + case FIRST = 'first'; + + /** + * ### Second + * @since 1.0.0 + */ + case SECOND = 'second'; + + /** + * ### Third + * @since 1.0.0 + */ + case THIRD = 'third'; + + /** + * ### Fourth + * @since 1.0.0 + */ + case FOURTH = 'fourth'; + + /** + * ### Fifth + * @since 1.0.0 + */ + case FIFTH = 'fifth'; + + /** + * ### Sixth + * @since 1.0.0 + */ + case SIXTH = 'sixth'; + + /** + * ### Seventh + * @since 1.0.0 + */ + case SEVENTH = 'seventh'; + + /** + * ### Eighth + * @since 1.0.0 + */ + case EIGHTH = 'eighth'; + + /** + * ### Ninth + * @since 1.0.0 + */ + case NINTH = 'ninth'; + + /** + * ### Tenth + * @since 1.0.0 + */ + case TENTH = 'tenth'; + + /** + * ### Eleventh + * @since 1.0.0 + */ + case ELEVENTH = 'eleventh'; + + /** + * ### Twelfth + * @since 1.0.0 + */ + case TWELFTH = 'twelfth'; + +} \ No newline at end of file diff --git a/src/Meta/Enum/Date/Expression/Relative.php b/src/Meta/Enum/Date/Expression/Relative.php new file mode 100644 index 0000000..5cd550a --- /dev/null +++ b/src/Meta/Enum/Date/Expression/Relative.php @@ -0,0 +1,59 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date\Expression; + +/** + * ### Defines relative temporal positions + * + * The Relative enum defines temporal positions relative to a reference date or time. + * + * These values can be used to describe a temporal unit as preceding, following, or coinciding with a reference + * period. + * @since 1.0.0 + */ +enum Relative:string { + + /** + * ### Next + * + * The temporal period immediately follows the reference period. + * @since 1.0.0 + */ + case NEXT = 'next'; + + /** + * ### Last + * + * The immediately preceding temporal period. + * @since 1.0.0 + */ + case LAST = 'last'; + + /** + * ### Previous + * + * The temporal period immediately preceding the reference period. + * @since 1.0.0 + */ + case PREVIOUS = 'previous'; + + /** + * ### This + * + * The temporal period contains the reference point. + * @since 1.0.0 + */ + case THIS = 'this'; + +} \ No newline at end of file diff --git a/src/Meta/Enum/Date/Expression/TimeKeyword.php b/src/Meta/Enum/Date/Expression/TimeKeyword.php new file mode 100644 index 0000000..d0723c0 --- /dev/null +++ b/src/Meta/Enum/Date/Expression/TimeKeyword.php @@ -0,0 +1,50 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date\Expression; + +/** + * ### Defines time-related temporal keywords + * + * The TimeKeyword enum defines keywords that identify specific or relative times within a temporal expression. + * + * These values are commonly used when parsing human-readable date and time expressions. + * @since 1.0.0 + */ +enum TimeKeyword:string { + + /** + * ### Midnight + * + * The beginning of the calendar day at 00:00:00. + * @since 1.0.0 + */ + case MIDNIGHT = 'midnight'; + + /** + * ### Now + * + * The current date and time. + * @since 1.0.0 + */ + case NOW = 'now'; + + /** + * ### Noon + * + * The middle of the calendar day at 12:00:00. + * @since 1.0.0 + */ + case NOON = 'noon'; + +} \ No newline at end of file From 641f55aa4ae03fd60c086949f6e254e3bb11bc7e Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 27 Aug 2026 13:54:20 +0200 Subject: [PATCH 037/118] Split `TimeKeyword` into `Keyword` and removed unused `NOON` case. **Details:** - Extracted the `Keyword` enum from `TimeKeyword` to improve semantic clarity and modularity within temporal abstractions. - Removed the `NOON` case from `TimeKeyword` due to redundancy and lack of use within the codebase. - Updated PHPDoc and maintained strict typing compliance to align with FireHub's principles of clarity and maintainability. This update simplifies the structure of temporal keywords, promoting better separation of concerns and aligning with FireHub's extensibility goals. --- src/Meta/Enum/Date/Expression/Keyword.php | 34 +++++++++++++++++++ src/Meta/Enum/Date/Expression/TimeKeyword.php | 8 ----- 2 files changed, 34 insertions(+), 8 deletions(-) create mode 100644 src/Meta/Enum/Date/Expression/Keyword.php diff --git a/src/Meta/Enum/Date/Expression/Keyword.php b/src/Meta/Enum/Date/Expression/Keyword.php new file mode 100644 index 0000000..042f1a2 --- /dev/null +++ b/src/Meta/Enum/Date/Expression/Keyword.php @@ -0,0 +1,34 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date\Expression; + +/** + * ### Defines temporal keywords + * + * The Keyword enum defines keywords that identify specific or relative date and time within a temporal expression. + * + * These values are commonly used when parsing human-readable date and time expressions. + * @since 1.0.0 + */ +enum Keyword:string { + + /** + * ### Now + * + * The current date and time. + * @since 1.0.0 + */ + case NOW = 'now'; + +} \ No newline at end of file diff --git a/src/Meta/Enum/Date/Expression/TimeKeyword.php b/src/Meta/Enum/Date/Expression/TimeKeyword.php index d0723c0..90b5420 100644 --- a/src/Meta/Enum/Date/Expression/TimeKeyword.php +++ b/src/Meta/Enum/Date/Expression/TimeKeyword.php @@ -39,12 +39,4 @@ enum TimeKeyword:string { */ case NOW = 'now'; - /** - * ### Noon - * - * The middle of the calendar day at 12:00:00. - * @since 1.0.0 - */ - case NOON = 'noon'; - } \ No newline at end of file From 146c45141bd0fde8cc4c15b4c693be8b521d2320 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 27 Aug 2026 15:59:21 +0200 Subject: [PATCH 038/118] Add `WEEKDAY` case and refine `base` and `factor` logic in `Unit` enum **Details:** - Introduced the `WEEKDAY` case to describe days of the week in the `Unit` enum, documented with PHPDoc annotations. - Simplified the `base()` method to reduce verbosity by leveraging a default case and updating mappings for `QUARTER` and `FORTNIGHT`. - Refactored the `factor()` method to streamline conversion logic using a default case, removing redundant unit-specific entries (e.g., `HOUR`, `MINUTE`, `WEEK`). - Maintained strict typing and improved overall readability and maintainability of the `Unit` enum. These changes enhance the extensibility and simplicity of the `Unit` enum while adhering to FireHub's principles of precision and clarity. --- src/Meta/Enum/Date/Unit.php | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/src/Meta/Enum/Date/Unit.php b/src/Meta/Enum/Date/Unit.php index 1c5fd63..4cb9073 100644 --- a/src/Meta/Enum/Date/Unit.php +++ b/src/Meta/Enum/Date/Unit.php @@ -88,6 +88,14 @@ enum Unit { */ case WEEK; + /** + * ### Week day + * + * A day of the week. + * @since 1.0.0 + */ + case WEEKDAY; + /** * ### Day * @@ -150,13 +158,9 @@ public function base ():?self { return match ($this) { self::MILLENNIUM, self::CENTURY, self::DECADE => self::YEAR, - self::FORTNIGHT, self::WEEK => self::DAY, - self::DAY => self::HOUR, - self::HOUR => self::MINUTE, - self::MINUTE => self::SECOND, - self::SECOND => self::MILLISECOND, - self::MILLISECOND => self::MICROSECOND, - self::YEAR, self::QUARTER, self::MONTH, self::MICROSECOND => null + self::QUARTER => self::MONTH, + self::FORTNIGHT => self::DAY, + default => null }; } @@ -174,15 +178,12 @@ public function base ():?self { public function factor ():int { return match ($this) { - self::MILLENNIUM, self::SECOND, self::MILLISECOND => 1000, + self::MILLENNIUM => 1000, self::CENTURY => 100, - self::HOUR, self::MINUTE => 60, - self::DAY => 24, self::FORTNIGHT => 14, self::DECADE => 10, - self::WEEK => 7, self::QUARTER => 3, - self::YEAR, self::MONTH, self::MICROSECOND => 1 + default => 1 }; } From 7e2e438ea16952fd1eb90374790613b122f2a857 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 28 Aug 2026 09:38:27 +0200 Subject: [PATCH 039/118] Refactor temporal unit system and introduce `ExtendedUnit` enum - Extracted higher-level temporal units (Millennium, Century, Decade, Quarter) and related logic from `Unit` to a new `ExtendedUnit` enum for better separation of core and extended date/time units. - Updated methods in `Factories` and `Accessors` to utilize `ExtendedUnit` where applicable. - Introduced new methods in `ExtendedUnit` (`base` and `factor`) to handle base unit mappings and conversion factors. - Renamed methods for clarity: `firstDayOf` -> `firstDayOfRelativeMonth`, `lastDayOf` -> `lastDayOfRelativeMonth`, and others to better describe their purpose. - Replaced hardcoded constants in calculations (e.g., fortnight factor) with direct logic or `ExtendedUnit`. - Added a new `at` method for precise temporal positioning. This enhances flexibility while working with `DateTime`. This improvement increases modularity, enhances readability, and enables cleaner future extensions of temporal units. --- src/Meta/Enum/Date/ExtendedUnit.php | 99 +++++++++++++++++++++++++++++ src/Meta/Enum/Date/Unit.php | 76 ---------------------- 2 files changed, 99 insertions(+), 76 deletions(-) create mode 100644 src/Meta/Enum/Date/ExtendedUnit.php diff --git a/src/Meta/Enum/Date/ExtendedUnit.php b/src/Meta/Enum/Date/ExtendedUnit.php new file mode 100644 index 0000000..1e383d9 --- /dev/null +++ b/src/Meta/Enum/Date/ExtendedUnit.php @@ -0,0 +1,99 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum\Date; + +/** + * ### Defines extended date and time units + * + * The ExtendedUnit enum defines calendar-derived date and time units supported by the FireHub temporal system. + * + * Each case represents an extended temporal unit that provides higher-level calendar semantics beyond the + * fundamental date and time units. + * @since 1.0.0 + */ +enum ExtendedUnit { + + /** + * ### Millennium + * + * A period of time spanning 1,000 years. + * @since 1.0.0 + */ + case MILLENNIUM; + + /** + * ### Century + * + * A period of time spanning 100 years. + * @since 1.0.0 + */ + case CENTURY; + + /** + * ### Decade + * + * A period of time spanning 10 years. + * @since 1.0.0 + */ + case DECADE; + + /** + * ### Quarter + * + * A calendar quarter. + * @since 1.0.0 + */ + case QUARTER; + + /** + * ### Get the base unit + * + * Returns the base temporal unit from which the current unit is derived. + * + * The base unit represents the unit to which the current unit can be reduced using its conversion factor. + * @since 1.0.0 + * + * @return null|self The base unit, or null if the unit is not derived from another unit. + */ + public function base ():?Unit { + + return match ($this) { + self::MILLENNIUM, self::CENTURY, self::DECADE => Unit::YEAR, + self::QUARTER => Unit::MONTH + }; + + } + + /** + * ### Get the conversion factor + * + * Returns the number of base units contained in one instance of the current unit. + * + * The factor defines the relationship between the current unit and its base unit. + * @since 1.0.0 + * + * @return int<1,max> The number of base units represented by one current unit. + */ + public function factor ():int { + + return match ($this) { + self::MILLENNIUM => 1000, + self::CENTURY => 100, + self::DECADE => 10, + self::QUARTER => 3 + }; + + } + +} \ No newline at end of file diff --git a/src/Meta/Enum/Date/Unit.php b/src/Meta/Enum/Date/Unit.php index 4cb9073..06d0850 100644 --- a/src/Meta/Enum/Date/Unit.php +++ b/src/Meta/Enum/Date/Unit.php @@ -24,30 +24,6 @@ */ enum Unit { - /** - * ### Millennium - * - * A period of time spanning 1,000 years. - * @since 1.0.0 - */ - case MILLENNIUM; - - /** - * ### Century - * - * A period of time spanning 100 years. - * @since 1.0.0 - */ - case CENTURY; - - /** - * ### Decade - * - * A period of time spanning 10 years. - * @since 1.0.0 - */ - case DECADE; - /** * ### Year * @@ -56,14 +32,6 @@ enum Unit { */ case YEAR; - /** - * ### Quarter - * - * A calendar quarter. - * @since 1.0.0 - */ - case QUARTER; - /** * ### Month * @@ -144,48 +112,4 @@ enum Unit { */ case MICROSECOND; - /** - * ### Get the base unit - * - * Returns the base temporal unit from which the current unit is derived. - * - * The base unit represents the unit to which the current unit can be reduced using its conversion factor. - * @since 1.0.0 - * - * @return null|self The base unit, or null if the unit is not derived from another unit. - */ - public function base ():?self { - - return match ($this) { - self::MILLENNIUM, self::CENTURY, self::DECADE => self::YEAR, - self::QUARTER => self::MONTH, - self::FORTNIGHT => self::DAY, - default => null - }; - - } - - /** - * ### Get the conversion factor - * - * Returns the number of base units contained in one instance of the current unit. - * - * The factor defines the relationship between the current unit and its base unit. - * @since 1.0.0 - * - * @return int<1,max> The number of base units represented by one current unit. - */ - public function factor ():int { - - return match ($this) { - self::MILLENNIUM => 1000, - self::CENTURY => 100, - self::FORTNIGHT => 14, - self::DECADE => 10, - self::QUARTER => 3, - default => 1 - }; - - } - } \ No newline at end of file From 51eb94a8d4af00807885c9b5c411ad0f6eaa051a Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 28 Aug 2026 12:08:55 +0200 Subject: [PATCH 040/118] Introduce `Period` abstract Value Object as a base for temporal types **Details:** - Added `Period` in `Core-Standard/src/Type/Temporal/Period.php` to define an abstract, immutable base class for temporal period value objects. - Implements foundational period behaviors and contracts, delegating the detailed implementation to higher-level layers. - Introduced strict types and PHP 8.2 features, ensuring alignment with modern PHP standards. - Includes `Stringable` implementation for seamless string representation via the `__toString()` method, which proxies to the abstract `value()` method. This addition establishes a robust foundation for handling temporal periods, promoting clarity, immutability, and extensibility in the FireHub Core. --- src/Type/Temporal/Period.php | 60 ++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 src/Type/Temporal/Period.php diff --git a/src/Type/Temporal/Period.php b/src/Type/Temporal/Period.php new file mode 100644 index 0000000..5c9e6b0 --- /dev/null +++ b/src/Type/Temporal/Period.php @@ -0,0 +1,60 @@ + + * @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\Temporal; + +use FireHub\Core\Type\ValueObject; +use Stringable; + +/** + * ### Defines the base temporal Period Value Object type within the FireHub ecosystem + * + * This abstract class represents the foundation for all temporal Period Value Objects. + * + * It provides immutable period value semantics while allowing concrete implementations to define specific behavior + * for representing and working with sequences of temporal occurrences. + * + * The class keeps the Core layer focused on defining the temporal period 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\ValueObject + */ +abstract readonly class Period extends ValueObject implements Stringable { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():string; + + /** + * ### 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\Temporal\Period::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 a1a47a29b2e1eb518afdf731074b55d2d3b5e16b Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 28 Aug 2026 12:12:34 +0200 Subject: [PATCH 041/118] Refine `base` method in `ExtendedUnit` enum **Details:** - Updated `base()` method signature to use `Unit` return type instead of `null|self` for stricter type compliance. - Adjusted PHPDoc annotation to reflect the updated return type, enhancing code clarity and alignment with modern PHP standards. This refinement ensures consistency with strict typing practices and improves the maintainability of the `ExtendedUnit` enum. --- src/Meta/Enum/Date/ExtendedUnit.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Meta/Enum/Date/ExtendedUnit.php b/src/Meta/Enum/Date/ExtendedUnit.php index 1e383d9..9a67229 100644 --- a/src/Meta/Enum/Date/ExtendedUnit.php +++ b/src/Meta/Enum/Date/ExtendedUnit.php @@ -64,9 +64,9 @@ enum ExtendedUnit { * The base unit represents the unit to which the current unit can be reduced using its conversion factor. * @since 1.0.0 * - * @return null|self The base unit, or null if the unit is not derived from another unit. + * @return \FireHub\Core\Meta\Enum\Date\Unit The base unit, or null if the unit is not derived from another unit. */ - public function base ():?Unit { + public function base ():Unit { return match ($this) { self::MILLENNIUM, self::CENTURY, self::DECADE => Unit::YEAR, From 49cfd361dd3fbb354ea61bb47d16ef8b7672614d Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 31 Aug 2026 13:14:50 +0200 Subject: [PATCH 042/118] Introduce `Timespan` abstract Value Object for base temporal timespan type **Details:** - Added `Timespan` in `Core-Standard/src/Type/Temporal/Timespan.php` as an abstract, immutable base class for temporal timespan value objects in the FireHub Core. - Extends the `Number` Value Object to represent numeric-string-based timespan values with strict type compliance. - Implements `Stringable` for seamless string representation, delegating logic to the abstract `value()` method for concrete implementations. - Designed to provide foundational timespan semantics, leaving specific behavior definitions to higher-level layers like `Foundation`. This addition promotes consistency, precision, and extensibility in handling temporal timespans while adhering to FireHub's principles of clarity and immutability. --- src/Type/Temporal/Timespan.php | 60 ++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 src/Type/Temporal/Timespan.php diff --git a/src/Type/Temporal/Timespan.php b/src/Type/Temporal/Timespan.php new file mode 100644 index 0000000..523056e --- /dev/null +++ b/src/Type/Temporal/Timespan.php @@ -0,0 +1,60 @@ + + * @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\Temporal; + +use FireHub\Core\Type\Number; +use Stringable; + +/** + * ### Defines the base temporal Timespan Value Object type within the FireHub ecosystem + * + * This abstract class represents the foundation for all temporal Timespan Value Objects. + * + * It provides immutable timespan value semantics while allowing concrete implementations to define specific behavior + * for representing and working with elapsed amounts of time. + * + * The class keeps the Core layer focused on defining the temporal timespan value contract, while concrete + * implementations belong to higher-level layers such as Foundation. + * @since 1.0.0 + * + * @template TValue of numeric-string + * + * @extends \FireHub\Core\Type\Number + */ +abstract readonly class Timespan extends Number implements Stringable { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():string; + + /** + * ### 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\Temporal\Timespan::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 eb157b87521a683afd049fb3c1f36324bc668ba0 Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 31 Aug 2026 15:29:21 +0200 Subject: [PATCH 043/118] Introduce `Components` abstract Value Object for Timespan elements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Details:** - Added the `Components` abstract class in `Core-Standard/src/Type/Temporal/Timespan/Components.php` to define the core value object for timespan elements such as days, hours, minutes, seconds, and microseconds. - Updated the `Timespan` abstract class to include a new `components()` method returning `Components` for detailed decomposition of timespan values. - Ensured immutability and strict typing compliance by leveraging PHP 8.2 features alongside meticulous PHPDoc annotations. This enhancement introduces a modular and extensible approach for managing decomposed timespan data while adhering to FireHub’s principles of clarity, precision, and immutability. --- src/Type/Temporal/Timespan.php | 15 ++++ src/Type/Temporal/Timespan/Components.php | 89 +++++++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 src/Type/Temporal/Timespan/Components.php diff --git a/src/Type/Temporal/Timespan.php b/src/Type/Temporal/Timespan.php index 523056e..9d84c64 100644 --- a/src/Type/Temporal/Timespan.php +++ b/src/Type/Temporal/Timespan.php @@ -13,6 +13,7 @@ namespace FireHub\Core\Type\Temporal; +use FireHub\Core\Type\Temporal\Timespan\Components; use FireHub\Core\Type\Number; use Stringable; @@ -34,6 +35,20 @@ */ abstract readonly class Timespan extends Number implements Stringable { + /** + * ### Returns the components of the timespan + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Temporal\Timespan\Components, + * minutes: int<0,59>, + * seconds: int<0,59>, + * microseconds: int<0,999999> + * }> + */ + abstract public function components ():Components; + /** * @inheritDoc * diff --git a/src/Type/Temporal/Timespan/Components.php b/src/Type/Temporal/Timespan/Components.php new file mode 100644 index 0000000..15a4bf3 --- /dev/null +++ b/src/Type/Temporal/Timespan/Components.php @@ -0,0 +1,89 @@ + + * @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\Temporal\Timespan; + +use FireHub\Core\Type\ValueObject; + +/** + * ### Defines the base temporal Timespan components Value Object type within the FireHub ecosystem + * + * The TimespanComponents class represents the individual calendar-independent components of an elapsed timespan. + * + * It provides immutable value semantics for decomposed timespan values while allowing concrete implementations to + * define how individual components are represented and calculated. + * + * The class keeps the Core layer focused on defining the timespan components contract, while concrete implementations + * belong to higher-level layers such as Foundation. + * @since 1.0.0 + * + * @template TValue of array{ + * days: numeric-string, + * hours: int<0,23>, + * minutes: int<0,59>, + * seconds: int<0,59>, + * microseconds: int<0,999999> + * } + * + * @extends \FireHub\Core\Type\ValueObject + */ +abstract readonly class Components extends ValueObject { + + /** + * ### Returns the number of days + * @since 1.0.0 + * + * @return numeric-string The number of days. + */ + abstract public function days ():string; + + /** + * ### Returns the number of hours + * @since 1.0.0 + * + * @return int<0,23> The number of hours. + */ + abstract public function hours ():int; + + /** + * ### Returns the number of minutes + * @since 1.0.0 + * + * @return int<0,59> The number of minutes. + */ + abstract public function minutes ():int; + + /** + * ### Returns the number of seconds + * @since 1.0.0 + * + * @return int<0,59> The number of seconds. + */ + abstract public function seconds ():int; + + /** + * ### Returns the number of microseconds + * @since 1.0.0 + * + * @return int<0,999999> The number of microseconds. + */ + abstract public function microseconds ():int; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():array; + +} \ No newline at end of file From 672bbaa0b289efa3927af325c1b247487ab57194 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 1 Sep 2026 10:38:53 +0200 Subject: [PATCH 044/118] Add `duration` abstract method to `Period` Value Object MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Details:** - Introduced the `duration()` abstract method in `Core-Standard/src/Type/Temporal/Period.php`. - Method returns a `Timespan` value object representing the duration of the period. - Added PHPDoc annotations to clarify method behavior and ensure strict typing compliance. This addition enhances the `Period` Value Object by defining a standard interface for retrieving its duration, aligning with FireHub’s principles of clarity, immutability, and precision. --- src/Type/Temporal/Period.php | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/Type/Temporal/Period.php b/src/Type/Temporal/Period.php index 5c9e6b0..2bc533c 100644 --- a/src/Type/Temporal/Period.php +++ b/src/Type/Temporal/Period.php @@ -34,6 +34,15 @@ */ abstract readonly class Period extends ValueObject implements Stringable { + /** + * ### Returns the duration of the period + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Temporal\Timespan The duration of the period as a Timespan Value + * Object. + */ + abstract public function duration ():Timespan; + /** * @inheritDoc * From 38883c1e7cbb66006df15f5029cb32b93cd2979e Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 1 Sep 2026 12:14:39 +0200 Subject: [PATCH 045/118] Introduce `Interval` abstract Value Object for temporal types **Details:** - Added `Interval` in `Core-Standard/src/Type/Temporal/Interval.php` as an abstract, immutable base class for temporal interval value objects within the FireHub Core. - Extends the `ValueObject` class and enforces the implementation of the `value()` method to define interval boundaries. - Includes PHP 8.2 features, `readonly` support, and robust PHPDoc annotations for strict typing and clarity. - Designed to represent the contract for bounded temporal intervals while leaving concrete behaviors to higher-level layers like `Foundation`. This addition establishes a foundational abstraction for managing intervals, aligning with FireHub's principles of precision, immutability, and extensibility. --- src/Type/Temporal/Interval.php | 43 ++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 src/Type/Temporal/Interval.php diff --git a/src/Type/Temporal/Interval.php b/src/Type/Temporal/Interval.php new file mode 100644 index 0000000..53f9682 --- /dev/null +++ b/src/Type/Temporal/Interval.php @@ -0,0 +1,43 @@ + + * @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\Temporal; + +use FireHub\Core\Type\ValueObject; + +/** + * ### Defines the base temporal Interval Value Object type within the FireHub ecosystem + * + * This abstract class represents the foundation for all temporal Interval Value Objects. + * + * It provides immutable interval value semantics while allowing concrete implementations to define specific behavior + * for representing and working with recurring temporal occurrences within a bounded period. + * + * The class keeps the Core layer focused on defining the temporal interval value contract, while concrete implementations + * belong to higher-level layers such as Foundation. + * @since 1.0.0 + * + * @template TValue of array + * + * @extends \FireHub\Core\Type\ValueObject + */ +abstract readonly class Interval extends ValueObject { + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + abstract public function value ():array; + +} \ No newline at end of file From 62ef729e8e19e99b3d049aa059e54a65fb0d5dca Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 1 Sep 2026 14:44:14 +0200 Subject: [PATCH 046/118] Introduce foundational contracts for core data structures **Details:** - Added the `Enumerable` interface in `Core-Standard/src/Boundary/Type/Enumerable.php` to define a contract for types that can expose their values sequentially through iteration. - Introduced the `DataStructure` interface in `Core-Standard/src/Boundary/Type/DataStructure.php` to provide a core contract for organizing and managing structured data. - Created the `Collection` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection.php`, extending `DataStructure` and `Enumerable` to represent data structures exposing enumerable collections of values. - Added the `Linear` interface in `Core-Standard/src/Boundary/Type/DataStructure/Classification/Linear.php` to describe data structures organized as a linear sequence. - Defined the `Vector` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Vector.php` as a contract for linear collections with indexed access and dynamic growth capabilities. These additions establish a standardized framework for representing and interacting with core data structures, adhering to FireHub's principles of clarity, extensibility, and modular design. --- src/Boundary/Type/DataStructure.php | 33 +++++++++++++++ .../DataStructure/Classification/Linear.php | 30 ++++++++++++++ .../Type/DataStructure/Collection.php | 41 +++++++++++++++++++ .../Type/DataStructure/Collection/Vector.php | 35 ++++++++++++++++ src/Boundary/Type/Enumerable.php | 33 +++++++++++++++ 5 files changed, 172 insertions(+) create mode 100644 src/Boundary/Type/DataStructure.php create mode 100644 src/Boundary/Type/DataStructure/Classification/Linear.php create mode 100644 src/Boundary/Type/DataStructure/Collection.php create mode 100644 src/Boundary/Type/DataStructure/Collection/Vector.php create mode 100644 src/Boundary/Type/Enumerable.php diff --git a/src/Boundary/Type/DataStructure.php b/src/Boundary/Type/DataStructure.php new file mode 100644 index 0000000..975eb55 --- /dev/null +++ b/src/Boundary/Type/DataStructure.php @@ -0,0 +1,33 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type; + +/** + * ### Represents a fundamental contract for a data structure + * + * A data structure defines a structured way of organizing, storing, accessing, and manipulating data. It + * provides the conceptual contract that implementations must follow when representing a particular + * organization of data. + * + * Data structures may differ in their internal representation, access patterns, ordering guarantees, mutation + * behavior, and operational characteristics. The contract defines their externally observable behavior without + * prescribing how the underlying data must be stored or processed. + * + * Data structures are not value objects. Their purpose is to provide structured data organization and operations + * rather than to represent a domain value identified solely by its value. + * @since 1.0.0 + * + * @template TValue + */ +interface DataStructure {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Classification/Linear.php b/src/Boundary/Type/DataStructure/Classification/Linear.php new file mode 100644 index 0000000..5d199b2 --- /dev/null +++ b/src/Boundary/Type/DataStructure/Classification/Linear.php @@ -0,0 +1,30 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Classification; + +/** + * ### Identifies a data structure whose values are organized in a linear sequence + * + * A linear data structure organizes its values along a single sequential dimension, where each value has a + * defined position relative to other values. Values are arranged according to a logical order that allows + * traversal from one position to the next. + * + * This classification describes the organizational characteristics of a data structure and does not prescribe + * a specific inheritance relationship, storage representation, access strategy, or implementation. + * + * Linear structures may provide positional access, sequential traversal, or operations at one or both ends of + * the sequence depending on their concrete contract. + * @since 1.0.0 + */ +interface Linear {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection.php b/src/Boundary/Type/DataStructure/Collection.php new file mode 100644 index 0000000..70c8f76 --- /dev/null +++ b/src/Boundary/Type/DataStructure/Collection.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 >=7.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure; + +use FireHub\Core\Boundary\Type\ { + DataStructure, Enumerable +}; + +/** + * ### Represents a data structure that organizes a group of values as a logical collection + * + * A collection provides a common contract for data structures that contain multiple values and expose those + * values as an enumerable group. Collections may provide different mechanisms for accessing, ordering, + * associating, inserting, removing, or otherwise manipulating their values depending on their specialized + * structure. + * + * The collection contract does not prescribe a particular internal representation, ordering strategy, key model, + * or storage mechanism. Specialized collection contracts define the semantics required by particular collection + * types, such as linear, associative, or unordered collections. + * + * A collection is a specialized form of data structure and therefore inherits the fundamental data-organization + * contract defined by DataStructure. + * @since 1.0.0 + * + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure + * @extends \FireHub\Core\Boundary\Type\Enumerable + */ +interface Collection extends DataStructure, Enumerable {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Vector.php b/src/Boundary/Type/DataStructure/Collection/Vector.php new file mode 100644 index 0000000..6352a50 --- /dev/null +++ b/src/Boundary/Type/DataStructure/Collection/Vector.php @@ -0,0 +1,35 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Collection; + +use FireHub\Core\Boundary\Type\DataStructure\Collection; + +/** + * ### Represents a linear collection that provides indexed access to its values + * + * A vector organizes its values in a contiguous logical sequence where each value is associated with a + * zero-based integer index. Values can be accessed, replaced, added, or removed according to their position + * within the sequence. + * + * The vector contract defines positional access and modification without prescribing the underlying storage + * representation, memory layout, capacity management, or implementation strategy. + * + * A vector preserves the relative order of its values and allows the sequence to grow or shrink dynamically. + * @since 1.0.0 + * + * @template TValue + * + * @extends Collection + */ +interface Vector extends Collection {} \ No newline at end of file diff --git a/src/Boundary/Type/Enumerable.php b/src/Boundary/Type/Enumerable.php new file mode 100644 index 0000000..5154fa6 --- /dev/null +++ b/src/Boundary/Type/Enumerable.php @@ -0,0 +1,33 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type; + +use IteratorAggregate; + +/** + * ### Represents a type whose values can be enumerated sequentially + * + * An enumerable type provides a contract for exposing its values through a defined iteration mechanism. It allows + * consumers to traverse the available values without depending on the underlying representation or storage mechanism. + * + * The contract does not prescribe how values are stored, how iteration is implemented, or whether the underlying + * data is finite, lazy, or materialized. These characteristics are defined by the implementing type. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends IteratorAggregate + */ +interface Enumerable extends IteratorAggregate {} \ No newline at end of file From 257ebbc98a5d809c2e5f8a2a0b9aca83bb56b423 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 1 Sep 2026 14:47:42 +0200 Subject: [PATCH 047/118] Refine `Vector` interface to generalize template parameter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Details:** - Updated the `@extends` PHPDoc in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Vector.php`, replacing `Collection` with `Collection` to remove the unnecessary restriction on the key type. - This change promotes a more flexible definition of the `Vector` interface, consistent with FireHub’s principles of clarity and extensibility. --- src/Boundary/Type/DataStructure/Collection/Vector.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Boundary/Type/DataStructure/Collection/Vector.php b/src/Boundary/Type/DataStructure/Collection/Vector.php index 6352a50..59f5f8d 100644 --- a/src/Boundary/Type/DataStructure/Collection/Vector.php +++ b/src/Boundary/Type/DataStructure/Collection/Vector.php @@ -30,6 +30,6 @@ * * @template TValue * - * @extends Collection + * @extends Collection */ interface Vector extends Collection {} \ No newline at end of file From e66e872bef912fdf66474baa78a869c883a7b0a4 Mon Sep 17 00:00:00 2001 From: Riddick Date: Wed, 2 Sep 2026 12:39:45 +0200 Subject: [PATCH 048/118] Add `getIterator()` method to `Enumerable` interface MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Details:** - Expanded the `Enumerable` interface in `Core-Standard/src/Boundary/Type/Enumerable.php` by introducing the `getIterator()` method for traversing enumerable values. - Updated `IteratorAggregate` import to include `Traversable` to align with the new method’s return type. - Enhanced PHPDoc to describe the new method, ensuring alignment with FireHub's modern PHP standards. This change reinforces the contract for enumerable types, ensuring consistency and improving extensibility in the FireHub Core boundary. --- src/Boundary/Type/Enumerable.php | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/src/Boundary/Type/Enumerable.php b/src/Boundary/Type/Enumerable.php index 5154fa6..c9f4f4a 100644 --- a/src/Boundary/Type/Enumerable.php +++ b/src/Boundary/Type/Enumerable.php @@ -13,7 +13,7 @@ namespace FireHub\Core\Boundary\Type; -use IteratorAggregate; +use IteratorAggregate, Traversable; /** * ### Represents a type whose values can be enumerated sequentially @@ -30,4 +30,14 @@ * * @extends IteratorAggregate */ -interface Enumerable extends IteratorAggregate {} \ No newline at end of file +interface Enumerable extends IteratorAggregate { + + /** + * ### Returns an iterator for traversing the values + * @since 1.0.0 + * + * @return Traversable + */ + public function getIterator ():Traversable; + +} \ No newline at end of file From 4a9039c7deeaf319b0d267e37720602ac204d568 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 3 Sep 2026 08:21:02 +0200 Subject: [PATCH 049/118] Add `Cloneable` interface to define deep copy behavior **Details:** - Introduced the `Cloneable` interface in `Core-Standard/src/Boundary/Capability/Cloneable.php`. - Defines the `copy()` method to create an independent deep copy of the implementing object. - Ensures that the returned copy does not share mutable state with the original object, adhering to immutability principles. - Includes robust PHPDoc annotations to clarify the method's contract and behavior, maintaining alignment with modern PHP standards. This addition provides a standardized way to enforce deep copy behavior in objects, promoting clarity, independence, and consistency in the FireHub Core boundary. --- src/Boundary/Capability/Cloneable.php | 36 +++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 src/Boundary/Capability/Cloneable.php diff --git a/src/Boundary/Capability/Cloneable.php b/src/Boundary/Capability/Cloneable.php new file mode 100644 index 0000000..9d4ca0a --- /dev/null +++ b/src/Boundary/Capability/Cloneable.php @@ -0,0 +1,36 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability; + +/** + * ### Defines the ability to create an independent deep copy + * + * Cloneable defines a contract for objects that can create an independent deep copy of themselves. The returned + * copy must not share a mutable object state with the original object. + * + * Implementations are responsible for recursively copying mutable objects contained within their state to preserve + * the independence of the returned copy. + * @since 1.0.0 + */ +interface Cloneable { + + /** + * ### Creates an independent deep copy of the object + * @since 1.0.0 + * + * @return static An independent deep copy of the object. + */ + public function copy ():static; + +} \ No newline at end of file From ab686eb1f121d1017363981d994531f952235e26 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 3 Sep 2026 10:24:49 +0200 Subject: [PATCH 050/118] Introduce `Maybe` abstract type to represent optional values **Details:** - Added `Maybe` abstract class in `Core-Standard/src/Type/Maybe.php` to define a foundational type for representing optional values in the FireHub Core. - Includes `isSome()` and `isNone()` abstract methods to differentiate between the presence and absence of a value. - Designed as an alternative to null, adhering to modern PHP standards and ensuring clearer semantics for optional data. - Implements strict typing with PHP 8.2 and employs robust PHPDoc annotations for improved clarity and precision. This addition establishes a standardized mechanism for handling optional values, promoting immutability, clarity, and robustness in the FireHub ecosystem. --- src/Type/Maybe.php | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 src/Type/Maybe.php diff --git a/src/Type/Maybe.php b/src/Type/Maybe.php new file mode 100644 index 0000000..30ae4f7 --- /dev/null +++ b/src/Type/Maybe.php @@ -0,0 +1,46 @@ + + * @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; + +/** + * ### Represents an optional value + * + * Maybe represents a value that may or may not exist. A Maybe instance is either a Some value containing a value + * or a None value representing the absence of a value. + * + * Maybe distinguishes between an existing value and the absence of a value without using `null` as an implicit + * absence marker. + * @since 1.0.0 + * + * @template TValue + */ +abstract readonly class Maybe { + + /** + * ### Determines whether a value exists + * @since 1.0.0 + * + * @return bool True if a value exists, false otherwise. + */ + abstract public function isSome ():bool; + + /** + * ### Determines whether a value does not exist + * @since 1.0.0 + * + * @return bool True if a value does not exist, false otherwise. + */ + abstract public function isNone ():bool; + +} \ No newline at end of file From 0a4f73640fc4524345bb5296aea71ddead80ecae Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 3 Sep 2026 14:36:45 +0200 Subject: [PATCH 051/118] Add `MutationOutcome` enum to represent mutation operation results **Details:** - Introduced the `MutationOutcome` enum in `Core-Standard/src/Meta/Enum/MutationOutcome.php` to standardize results for create, update, remove, and not-found mutation operations. - Includes four cases: `CREATED`, `UPDATED`, `REMOVED`, and `NOT_FOUND`, with comprehensive PHPDoc annotations for clarity and consistency. - Targets PHP 8.1+ to align with modern language standards and enhance type safety. This addition provides a clear, extensible mechanism to represent mutation outcomes, promoting standardization and clarity across the FireHub Core ecosystem. --- src/Meta/Enum/MutationOutcome.php | 48 +++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 src/Meta/Enum/MutationOutcome.php diff --git a/src/Meta/Enum/MutationOutcome.php b/src/Meta/Enum/MutationOutcome.php new file mode 100644 index 0000000..aa41f9e --- /dev/null +++ b/src/Meta/Enum/MutationOutcome.php @@ -0,0 +1,48 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Meta\Enum; + +/** + * ### Represents the outcome of a mutation operation + * + * MutationOutcome describes the result of an operation that attempts to create, update, or remove an entry. + * @since 1.0.0 + */ +enum MutationOutcome { + + /** + * ### New Entry Created + * @since 1.0.0 + */ + case CREATED; + + /** + * ### Existing Entry Updated + * @since 1.0.0 + */ + case UPDATED; + + /** + * ### Entry Removed + * @since 1.0.0 + */ + case REMOVED; + + /** + * ### Entry Not Found + * @since 1.0.0 + */ + case NOT_FOUND; + +} \ No newline at end of file From dcaa56c6f033e0b9634b464bff62a26a716e0719 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 4 Sep 2026 09:39:10 +0200 Subject: [PATCH 052/118] Add `Iteration` and `Traversal` interfaces for iterable value contracts **Details:** - Introduced the `Iteration` interface in `Core-Standard/src/Boundary/Capability/Iteration.php` to define a contract for accessing an iterable sequence of values without dictating storage or traversal mechanisms. Includes the `iterate()` method for returning an iterable sequence. - Added the `Traversal` interface in `Core-Standard/src/Boundary/Capability/Traversal.php` to specify a traversal mechanism for iterable values with controlled semantics and an optional `$limit` parameter in the `traverse()` method. - Both interfaces are designed with PHP generics (`@template`) for type safety and extensibility. These additions establish foundational contracts for iterable value management, aligning with FireHub's principles of clarity, modularity, and type safety. --- src/Boundary/Capability/Iteration.php | 38 +++++++++++++++++++++++ src/Boundary/Capability/Traversal.php | 43 +++++++++++++++++++++++++++ 2 files changed, 81 insertions(+) create mode 100644 src/Boundary/Capability/Iteration.php create mode 100644 src/Boundary/Capability/Traversal.php diff --git a/src/Boundary/Capability/Iteration.php b/src/Boundary/Capability/Iteration.php new file mode 100644 index 0000000..8ae3263 --- /dev/null +++ b/src/Boundary/Capability/Iteration.php @@ -0,0 +1,38 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability; + +/** + * ### Defines iteration over a sequence of values + * + * Iteration provides access to an iterable sequence of values without prescribing how those values are stored, + * represented, or traversed. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface Iteration { + + /** + * ### Iterates over the values + * + * Returns an iterable sequence containing the values exposed by the implementation. + * @since 1.0.0 + * + * @return iterable + */ + public function iterate ():iterable; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Traversal.php b/src/Boundary/Capability/Traversal.php new file mode 100644 index 0000000..a6064c3 --- /dev/null +++ b/src/Boundary/Capability/Traversal.php @@ -0,0 +1,43 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability; + +/** + * ### Defines traversal of a sequence of values + * + * Traversal provides access to values through an iterable sequence without prescribing how the values are stored + * or represented. Implementations define the order and semantics in which values are traversed. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface Traversal { + + /** + * ### Traverses the values + * + * Returns iterable that yields values according to the traversal order defined by the implementation. + * Traversal may be limited to a maximum number of elements. + * @since 1.0.0 + * + * @param null|int $limit

+ * Maximum number of elements to yield. If null, traversal continues until the traversal naturally terminates. + *

+ * + * @return iterable The traversed values. + */ + public function traverse (?int $limit = null):iterable; + +} \ No newline at end of file From a792f7a6fad582e8d8cf08e04d572936589ccb4c Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 4 Sep 2026 10:19:26 +0200 Subject: [PATCH 053/118] Update badges in README to point to the `architecture/foundation-support` branch **Details:** - Updated branch references in the PHPStan, PHPUnit, and Codecov badges from `architecture/error-exception-base` to `architecture/foundation-support`. - Ensures that badges reflect the latest workflow and coverage for the active branch. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 44b5a2c..fc07a8d 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,9 @@ /> -[![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) +[![PHPStan](https://github.com/The-FireHub-Project/Core-Standard/actions/workflows/PHPStan.yml/badge.svg?branch=architecture%2Ffoundation-support)](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%2Ffoundation-support)](https://github.com/The-FireHub-Project/Core-Standard/actions/workflows/PHPUnit.yml) +[![Codecov](https://codecov.io/gh/The-FireHub-Project/Core-Standard/branch/architecture%2Ffoundation-support/graph/badge.svg?token=XW2YEONF51)](https://app.codecov.io/gh/The-FireHub-Project/Core-Standard/tree/architecture%2Ffoundation-support)

From 24edc8896e9f470afc14eb99b394c56e10dc78e2 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 4 Sep 2026 10:23:03 +0200 Subject: [PATCH 054/118] Add `module_meta` component to Codecov configuration **Details:** - Added a new `module_meta` component to `.github/codecov.yaml` with a target coverage of 80%. - Configured paths to include `src/Meta/**` for code coverage tracking. - Aligns with the existing structure for modular coverage configuration in the Core-Standard repository. --- .github/codecov.yaml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/codecov.yaml b/.github/codecov.yaml index 9457102..d86828d 100644 --- a/.github/codecov.yaml +++ b/.github/codecov.yaml @@ -16,6 +16,12 @@ component_management: - "src/Exception/**" coverage: target: 80% + - component_id: module_meta + name: meta + paths: + - "src/Meta/**" + coverage: + target: 80% - component_id: module_type name: type paths: From fc03fb9ec3977407605631e5cc7d983f63fd0f0c Mon Sep 17 00:00:00 2001 From: Riddick Date: Wed, 9 Sep 2026 12:10:23 +0200 Subject: [PATCH 055/118] Add BidirectionalIteration and BidirectionalTraversal interfaces for enhanced sequence manipulation --- .../Capability/BidirectionalIteration.php | 40 ++++++++++++++++ .../Capability/BidirectionalTraversal.php | 46 +++++++++++++++++++ 2 files changed, 86 insertions(+) create mode 100644 src/Boundary/Capability/BidirectionalIteration.php create mode 100644 src/Boundary/Capability/BidirectionalTraversal.php diff --git a/src/Boundary/Capability/BidirectionalIteration.php b/src/Boundary/Capability/BidirectionalIteration.php new file mode 100644 index 0000000..74d16c7 --- /dev/null +++ b/src/Boundary/Capability/BidirectionalIteration.php @@ -0,0 +1,40 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability; + +/** + * ### Defines bidirectional iteration over a sequence of values + * + * Bidirectional iteration extends standard iteration with access to the same sequence in reverse order without + * prescribing how those values are stored or represented. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends \FireHub\Core\Boundary\Capability\Iteration + */ +interface BidirectionalIteration extends Iteration { + + /** + * ### Iterates over the values in reverse order + * + * Returns an iterable sequence containing the values exposed by the implementation in reverse iteration order. + * @since 1.0.0 + * + * @return iterable + */ + public function iterateReverse ():iterable; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/BidirectionalTraversal.php b/src/Boundary/Capability/BidirectionalTraversal.php new file mode 100644 index 0000000..f9b073f --- /dev/null +++ b/src/Boundary/Capability/BidirectionalTraversal.php @@ -0,0 +1,46 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability; + +/** + * ### Defines bidirectional traversal of a sequence of values + * + * Bidirectional traversal extends standard traversal with access to values in the reverse traversal direction without + * prescribing how those values are stored or represented. Implementations define the order and semantics in which + * values are traversed in each direction. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends \FireHub\Core\Boundary\Capability\Traversal + */ +interface BidirectionalTraversal extends Traversal { + + /** + * ### Traverses the values in reverse order + * + * Returns an iterable that yields values according to the reverse traversal order defined by the implementation. + * Traversal may be limited to a maximum number of elements. + * @since 1.0.0 + * + * @param null|int $limit

+ * Maximum number of elements to yield. If null, traversal continues until the traversal naturally terminates. + *

+ * + * @return iterable The traversed values. + */ + public function traverseReverse (?int $limit = null):iterable; + +} \ No newline at end of file From 93e0d5bcb18aae1db66e0c0960ea0e50d6b1fe81 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 10 Sep 2026 09:16:03 +0200 Subject: [PATCH 056/118] Add foundational capability interfaces for mutation, access, and measurement in Core-Standard **Details:** - Introduced mutation interfaces: - `BackInsertion`, `BackRemoval`, `BackMutation` - `FrontInsertion`, `FrontRemoval`, `FrontMutation` - `DequeMutation`, `IndexMutation`, and `KeyMutation` These interfaces define contracts for mutating data at specific boundaries, by indices, or by keys while adhering to FireHub's principles of clarity and immutability. - Added access interfaces: - `IndexAccess`, `KeyAccess`, and `BoundaryAccess` These provide contracts for read-only access to values by index, by key, or at the front and back of sequences. - Added measurement interfaces: - `Metrics` and `Capacity` These define contracts for size metrics and bounded capacity awareness. These additions establish a robust framework for structured data access, manipulation, and measurement, fostering consistency and modularity across the FireHub Core ecosystem. --- .../Capability/Access/BoundaryAccess.php | 51 ++++++++++++++ .../Capability/Access/IndexAccess.php | 60 +++++++++++++++++ src/Boundary/Capability/Access/KeyAccess.php | 56 ++++++++++++++++ .../Capability/Measurement/Capacity.php | 58 ++++++++++++++++ .../Capability/Measurement/Metrics.php | 48 +++++++++++++ .../Capability/Mutation/BackInsertion.php | 44 ++++++++++++ .../Capability/Mutation/BackMutation.php | 31 +++++++++ .../Capability/Mutation/BackRemoval.php | 42 ++++++++++++ .../Capability/Mutation/DequeMutation.php | 31 +++++++++ .../Capability/Mutation/FrontInsertion.php | 44 ++++++++++++ .../Capability/Mutation/FrontMutation.php | 31 +++++++++ .../Capability/Mutation/FrontRemoval.php | 42 ++++++++++++ .../Capability/Mutation/IndexMutation.php | 67 +++++++++++++++++++ .../Capability/Mutation/KeyMutation.php | 67 +++++++++++++++++++ 14 files changed, 672 insertions(+) create mode 100644 src/Boundary/Capability/Access/BoundaryAccess.php create mode 100644 src/Boundary/Capability/Access/IndexAccess.php create mode 100644 src/Boundary/Capability/Access/KeyAccess.php create mode 100644 src/Boundary/Capability/Measurement/Capacity.php create mode 100644 src/Boundary/Capability/Measurement/Metrics.php create mode 100644 src/Boundary/Capability/Mutation/BackInsertion.php create mode 100644 src/Boundary/Capability/Mutation/BackMutation.php create mode 100644 src/Boundary/Capability/Mutation/BackRemoval.php create mode 100644 src/Boundary/Capability/Mutation/DequeMutation.php create mode 100644 src/Boundary/Capability/Mutation/FrontInsertion.php create mode 100644 src/Boundary/Capability/Mutation/FrontMutation.php create mode 100644 src/Boundary/Capability/Mutation/FrontRemoval.php create mode 100644 src/Boundary/Capability/Mutation/IndexMutation.php create mode 100644 src/Boundary/Capability/Mutation/KeyMutation.php diff --git a/src/Boundary/Capability/Access/BoundaryAccess.php b/src/Boundary/Capability/Access/BoundaryAccess.php new file mode 100644 index 0000000..25a8797 --- /dev/null +++ b/src/Boundary/Capability/Access/BoundaryAccess.php @@ -0,0 +1,51 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Access; + +use FireHub\Core\Type\Maybe; + +/** + * ### Defines access to boundary values + * + * Boundary access provides read-only access to the first and last values of an ordered sequence. + * + * The capability defines the fundamental operations for retrieving values at the boundaries without prescribing + * how values are stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + */ +interface BoundaryAccess { + + /** + * ### Returns the first value + * + * Returns the value at the beginning of the sequence when it exists. + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Maybe The first value, or an empty Maybe if no value exists. + */ + public function first ():Maybe; + + /** + * ### Returns the last value + * + * Returns the value at the end of the sequence when it exists. + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Maybe The last value, or an empty Maybe if no value exists. + */ + public function last ():Maybe; + +} diff --git a/src/Boundary/Capability/Access/IndexAccess.php b/src/Boundary/Capability/Access/IndexAccess.php new file mode 100644 index 0000000..92bbac8 --- /dev/null +++ b/src/Boundary/Capability/Access/IndexAccess.php @@ -0,0 +1,60 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Access; + +use FireHub\Core\Type\Maybe; + +/** + * ### Defines indexed access to values + * + * Indexed access provides read-only access to values identified by an integer index. + * + * The capability defines the fundamental operations for determining whether an index exists and retrieving the + * value associated with it, without prescribing how values are stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + */ +interface IndexAccess { + + /** + * ### Determines whether an index exists + * + * Determines whether a value is available at the specified index. + * @since 1.0.0 + * + * @param int $index

+ * The index to check. + *

+ * + * @return bool True if the index exists, false otherwise. + */ + public function has (int $index):bool; + + /** + * ### Returns the value at the specified index + * + * Returns the value currently stored at the specified index. + * @since 1.0.0 + * + * @param int $index

+ * The zero-based index of the value to retrieve. + *

+ * + * @return \FireHub\Core\Type\Maybe The value at the specified index, or an empty Maybe if the index + * does not exist. + */ + public function get (int $index):Maybe; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Access/KeyAccess.php b/src/Boundary/Capability/Access/KeyAccess.php new file mode 100644 index 0000000..500c790 --- /dev/null +++ b/src/Boundary/Capability/Access/KeyAccess.php @@ -0,0 +1,56 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Access; + +use FireHub\Core\Type\Maybe; + +/** + * ### Defines key-based access to values + * + * Key access provides read-only access to values identified by their keys. + * + * The capability defines the fundamental operations for determining whether a key exists and retrieving the value + * associated with it, without prescribing how values are stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface KeyAccess { + + /** + * ### Determines whether a key exists + * @since 1.0.0 + * + * @param TKey $key

+ * The key to check. + *

+ * + * @return bool True if a value exists for the specified key, false otherwise. + */ + public function has (mixed $key):bool; + + /** + * ### Returns the value associated with the specified key + * @since 1.0.0 + * + * @param TKey $key

+ * The key whose value should be returned. + *

+ * + * @return \FireHub\Core\Type\Maybe The associated value, or an empty Maybe if the key does not exist. + */ + public function get (mixed $key):Maybe; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Measurement/Capacity.php b/src/Boundary/Capability/Measurement/Capacity.php new file mode 100644 index 0000000..004fa3b --- /dev/null +++ b/src/Boundary/Capability/Measurement/Capacity.php @@ -0,0 +1,58 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Measurement; + +/** + * ### Defines bounded capacity awareness + * + * Capacity awareness provides information about the maximum number of values that can be contained and the + * remaining space available for additional values. + * + * The capability defines the fundamental operations for observing capacity constraints without prescribing how + * capacity is managed, enforced, or represented internally. + * @since 1.0.0 + */ +interface Capacity { + + /** + * ### Determines whether the capacity is full + * + * Determines whether the maximum capacity has been reached. + * @since 1.0.0 + * + * @return bool True if the maximum capacity has been reached, false otherwise. + */ + public function isFull ():bool; + + /** + * ### Returns the maximum capacity + * + * Returns the maximum number of values that can be contained. + * @since 1.0.0 + * + * @return non-negative-int The maximum number of values that can be contained. + */ + public function capacity ():int; + + /** + * ### Returns the remaining capacity + * + * Returns the number of additional values that can be contained before the maximum capacity is reached. + * @since 1.0.0 + * + * @return non-negative-int The number of additional values that can be contained. + */ + public function remainingCapacity ():int; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Measurement/Metrics.php b/src/Boundary/Capability/Measurement/Metrics.php new file mode 100644 index 0000000..6761bf9 --- /dev/null +++ b/src/Boundary/Capability/Measurement/Metrics.php @@ -0,0 +1,48 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Measurement; + +/** + * ### Defines measurable size information + * + * Metrics provide information about the current number of values without prescribing how those values are stored, + * organized, accessed, or represented internally. + * + * The capability defines the fundamental operations for determining whether values are present and observing their + * current number. + * @since 1.0.0 + */ +interface Metrics { + + /** + * ### Determines whether there are no values + * + * Determines whether the current number of values is zero. + * @since 1.0.0 + * + * @return bool True if there are no values, false otherwise. + */ + public function isEmpty ():bool; + + /** + * ### Returns the number of values + * + * Returns the number of values currently contained. + * @since 1.0.0 + * + * @return non-negative-int The number of values currently contained. + */ + public function size ():int; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/BackInsertion.php b/src/Boundary/Capability/Mutation/BackInsertion.php new file mode 100644 index 0000000..7c5db1d --- /dev/null +++ b/src/Boundary/Capability/Mutation/BackInsertion.php @@ -0,0 +1,44 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +/** + * ### Defines insertion at the back boundary + * + * Back insertion defines the ability to insert values at the back boundary of an ordered sequence. + * + * The capability defines the fundamental operation for adding values after the current last value without + * prescribing how values are stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + */ +interface BackInsertion { + + /** + * ### Inserts values at the back + * + * Inserts one or more values at the back boundary as a single batch operation. The values are inserted in the + * same order in which they are provided. + * @since 1.0.0 + * + * @param TValue ...$values

+ * The values to insert at the back. + *

+ * + * @return void + */ + public function insertBack (mixed ...$values):void; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/BackMutation.php b/src/Boundary/Capability/Mutation/BackMutation.php new file mode 100644 index 0000000..4ad2f75 --- /dev/null +++ b/src/Boundary/Capability/Mutation/BackMutation.php @@ -0,0 +1,31 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +/** + * ### Defines mutation at the back boundary + * + * Back mutation combines back insertion and back removal into a single capability, providing the complete set of + * mutation operations available at the back boundary of an ordered sequence. + * + * The capability defines only the operations for modifying the back boundary without prescribing how values are + * stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + * + * @extends \FireHub\Foundation\DataStructure\Storage\Capability\BackInsertion + * @extends \FireHub\Foundation\DataStructure\Storage\Capability\BackRemoval + */ +interface BackMutation extends BackInsertion, BackRemoval {} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/BackRemoval.php b/src/Boundary/Capability/Mutation/BackRemoval.php new file mode 100644 index 0000000..85a4a3c --- /dev/null +++ b/src/Boundary/Capability/Mutation/BackRemoval.php @@ -0,0 +1,42 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Type\Maybe; + +/** + * ### Defines removal from the back boundary + * + * Back removal defines the ability to remove and return the value at the back boundary of an ordered sequence. + * + * The capability defines the fundamental operation for removing the current last value without prescribing how + * values are stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + */ +interface BackRemoval { + + /** + * ### Removes and returns the last value + * + * Removes the value currently located at the back boundary and returns the removed value. If no value exists, + * an empty Maybe is returned. + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Maybe The removed value, or an empty Maybe if no value exists. + */ + public function removeBack ():Maybe; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/DequeMutation.php b/src/Boundary/Capability/Mutation/DequeMutation.php new file mode 100644 index 0000000..04c492f --- /dev/null +++ b/src/Boundary/Capability/Mutation/DequeMutation.php @@ -0,0 +1,31 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +/** + * ### Defines mutation at both boundaries + * + * Deque mutation combines front mutation and back mutation into a single capability, providing the complete set of + * insertion and removal operations available at both boundaries of an ordered sequence. + * + * The capability defines the fundamental operations for modifying either boundary without prescribing how values + * are stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + * + * @extends \FireHub\Foundation\DataStructure\Storage\Capability\FrontMutation + * @extends \FireHub\Foundation\DataStructure\Storage\Capability\BackMutation + */ +interface DequeMutation extends FrontMutation, BackMutation {} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/FrontInsertion.php b/src/Boundary/Capability/Mutation/FrontInsertion.php new file mode 100644 index 0000000..ce9bd38 --- /dev/null +++ b/src/Boundary/Capability/Mutation/FrontInsertion.php @@ -0,0 +1,44 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +/** + * ### Defines insertion at the front boundary + * + * Front insertion defines the ability to insert values at the front boundary of an ordered sequence. + * + * The capability defines the fundamental operation for adding values before the current first value without + * prescribing how values are stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + */ +interface FrontInsertion { + + /** + * ### Inserts values at the front + * + * Inserts one or more values at the front boundary as a single batch operation. The values are inserted in the + * same order in which they are provided, so the first provided value becomes the first newly inserted value. + * @since 1.0.0 + * + * @param TValue ...$values

+ * The values to insert at the front. + *

+ * + * @return void + */ + public function insertFront (mixed ...$values):void; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/FrontMutation.php b/src/Boundary/Capability/Mutation/FrontMutation.php new file mode 100644 index 0000000..c047af8 --- /dev/null +++ b/src/Boundary/Capability/Mutation/FrontMutation.php @@ -0,0 +1,31 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +/** + * ### Defines mutation at the front boundary + * + * Front mutation combines front insertion and front removal into a single capability, providing the complete set + * of mutation operations available at the front boundary of an ordered sequence. + * + * The capability defines only the operations for modifying the front boundary without prescribing how values are + * stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + * + * @extends \FireHub\Foundation\DataStructure\Storage\Capability\FrontInsertion + * @extends \FireHub\Foundation\DataStructure\Storage\Capability\FrontRemoval + */ +interface FrontMutation extends FrontInsertion, FrontRemoval {} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/FrontRemoval.php b/src/Boundary/Capability/Mutation/FrontRemoval.php new file mode 100644 index 0000000..febd317 --- /dev/null +++ b/src/Boundary/Capability/Mutation/FrontRemoval.php @@ -0,0 +1,42 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Type\Maybe; + +/** + * ### Defines removal from the front boundary + * + * Front removal defines the ability to remove and return the value at the front boundary of an ordered sequence. + * + * The capability defines the fundamental operation for removing the current first value without prescribing how + * values are stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + */ +interface FrontRemoval { + + /** + * ### Removes and returns the first value + * + * Removes the value currently located at the front boundary and returns the removed value. If no value exists, + * an empty Maybe is returned. + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Maybe The removed value, or an empty Maybe if no value exists. + */ + public function removeFront ():Maybe; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/IndexMutation.php b/src/Boundary/Capability/Mutation/IndexMutation.php new file mode 100644 index 0000000..1599671 --- /dev/null +++ b/src/Boundary/Capability/Mutation/IndexMutation.php @@ -0,0 +1,67 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Meta\Enum\MutationOutcome; + +/** + * ### Defines indexed mutation of values + * + * Indexed mutation provides the ability to create, replace, and remove values identified by an integer index. + * + * The capability defines the fundamental operations for modifying indexed values without prescribing how values + * are stored, organized, or represented internally. Each mutation operation reports its result through a + * MutationOutcome value. + * @since 1.0.0 + * + * @template TValue + */ +interface IndexMutation { + + /** + * ### Sets the value at the specified index + * + * Associates the specified value with the given index. If the index does not exist, a new value is created. + * If the index already exists, its current value is replaced. + * @since 1.0.0 + * + * @param int $index

+ * The index at which to set the value. + *

+ * + * @param TValue $value

+ * The value to set. + *

+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: CREATED if a new value was + * created, or UPDATED if an existing value was replaced. + */ + public function set (int $index, mixed $value):MutationOutcome; + + /** + * ### Removes the value at the specified index + * + * Removes the value associated with the specified index when it exists. + * @since 1.0.0 + * + * @param int $index

+ * The index of the value to remove. + *

+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: REMOVED if a value was removed, + * or NOT_FOUND if the index does not exist. + */ + public function remove (int $index):MutationOutcome; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/KeyMutation.php b/src/Boundary/Capability/Mutation/KeyMutation.php new file mode 100644 index 0000000..bc337d8 --- /dev/null +++ b/src/Boundary/Capability/Mutation/KeyMutation.php @@ -0,0 +1,67 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Meta\Enum\MutationOutcome; + +/** + * ### Defines key-based mutation of values + * + * Key mutation provides the ability to create, replace, and remove values identified by their keys. + * + * The capability defines the fundamental operations for modifying keyed values without prescribing how values + * are stored, organized, or represented internally. Each mutation operation reports its result through a + * MutationOutcome value. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface KeyMutation { + + /** + * ### Sets the value associated with the specified key + * + * Associates the specified value with the given key. If the key does not exist, a new value is created. If the + * key already exists, its current value is replaced. + * @since 1.0.0 + * + * @param TKey $key

+ * The key with which to associate the value. + *

+ * @param TValue $value

+ * The value to set. + *

+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: CREATED if a new value was + * created, or UPDATED if an existing value was replaced. + */ + public function set (mixed $key, mixed $value):MutationOutcome; + + /** + * ### Removes the value associated with the specified key + * + * Removes the value associated with the specified key when it exists. + * @since 1.0.0 + * + * @param TKey $key

+ * The key whose associated value should be removed. + *

+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: REMOVED if a value was removed, + * or NOT_FOUND if the key does not exist. + */ + public function remove (mixed $key):MutationOutcome; + +} \ No newline at end of file From 17219e309ed109422f2a88b3d986412528ca4ba2 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 10 Sep 2026 09:22:25 +0200 Subject: [PATCH 057/118] Update namespace references in mutation capability interfaces **Details:** - Updated `@extends` PHPDoc annotations in `BackMutation`, `FrontMutation`, and `DequeMutation` interfaces to reference `FireHub\Core\Boundary\Capability\Mutation` instead of `FireHub\Foundation\DataStructure\Storage\Capability`. - Ensures consistent namespace usage across Core-Standard components, aligning with the modular structure of the FireHub ecosystem. --- src/Boundary/Capability/Mutation/BackMutation.php | 4 ++-- src/Boundary/Capability/Mutation/DequeMutation.php | 4 ++-- src/Boundary/Capability/Mutation/FrontMutation.php | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/Boundary/Capability/Mutation/BackMutation.php b/src/Boundary/Capability/Mutation/BackMutation.php index 4ad2f75..b04e448 100644 --- a/src/Boundary/Capability/Mutation/BackMutation.php +++ b/src/Boundary/Capability/Mutation/BackMutation.php @@ -25,7 +25,7 @@ * * @template TValue * - * @extends \FireHub\Foundation\DataStructure\Storage\Capability\BackInsertion - * @extends \FireHub\Foundation\DataStructure\Storage\Capability\BackRemoval + * @extends \FireHub\Core\Boundary\Capability\Mutation\BackInsertion + * @extends \FireHub\Core\Boundary\Capability\Mutation\BackRemoval */ interface BackMutation extends BackInsertion, BackRemoval {} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/DequeMutation.php b/src/Boundary/Capability/Mutation/DequeMutation.php index 04c492f..c0c910d 100644 --- a/src/Boundary/Capability/Mutation/DequeMutation.php +++ b/src/Boundary/Capability/Mutation/DequeMutation.php @@ -25,7 +25,7 @@ * * @template TValue * - * @extends \FireHub\Foundation\DataStructure\Storage\Capability\FrontMutation - * @extends \FireHub\Foundation\DataStructure\Storage\Capability\BackMutation + * @extends \FireHub\Core\Boundary\Capability\Mutation\FrontMutation + * @extends \FireHub\Core\Boundary\Capability\Mutation\BackMutation */ interface DequeMutation extends FrontMutation, BackMutation {} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/FrontMutation.php b/src/Boundary/Capability/Mutation/FrontMutation.php index c047af8..fc58957 100644 --- a/src/Boundary/Capability/Mutation/FrontMutation.php +++ b/src/Boundary/Capability/Mutation/FrontMutation.php @@ -25,7 +25,7 @@ * * @template TValue * - * @extends \FireHub\Foundation\DataStructure\Storage\Capability\FrontInsertion - * @extends \FireHub\Foundation\DataStructure\Storage\Capability\FrontRemoval + * @extends \FireHub\Core\Boundary\Capability\Mutation\FrontInsertion + * @extends \FireHub\Core\Boundary\Capability\Mutation\FrontRemoval */ interface FrontMutation extends FrontInsertion, FrontRemoval {} \ No newline at end of file From dd689936d1b237bfcf0e08fd94d882f27428207d Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 10 Sep 2026 09:39:19 +0200 Subject: [PATCH 058/118] Enhance `Vector` and `Collection` interfaces with additional contracts for access and measurement **Details:** - Updated `Vector` interface: - Extended from `IndexAccess` to formalize positional access capabilities. - Enhanced PHPDoc annotations for clarity on vector semantics, including ordered, indexed access and value mutability independence. - Updated `Collection` interface: - Extended from `Metrics` to establish a contract for collection size measurement. - Refined PHPDoc to align with FireHub's modular conventions. These improvements ensure precise, consistent contracts for collections, enhancing clarity, extensibility, and modularity across the FireHub Core ecosystem. --- .../Type/DataStructure/Collection.php | 3 ++- .../Type/DataStructure/Collection/Vector.php | 19 +++++++++++-------- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/src/Boundary/Type/DataStructure/Collection.php b/src/Boundary/Type/DataStructure/Collection.php index 70c8f76..57810f6 100644 --- a/src/Boundary/Type/DataStructure/Collection.php +++ b/src/Boundary/Type/DataStructure/Collection.php @@ -13,6 +13,7 @@ namespace FireHub\Core\Boundary\Type\DataStructure; +use FireHub\Core\Boundary\Capability\Measurement\Metrics; use FireHub\Core\Boundary\Type\ { DataStructure, Enumerable }; @@ -38,4 +39,4 @@ * @extends \FireHub\Core\Boundary\Type\DataStructure * @extends \FireHub\Core\Boundary\Type\Enumerable */ -interface Collection extends DataStructure, Enumerable {} \ No newline at end of file +interface Collection extends DataStructure, Enumerable, Metrics {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Vector.php b/src/Boundary/Type/DataStructure/Collection/Vector.php index 59f5f8d..ba1e543 100644 --- a/src/Boundary/Type/DataStructure/Collection/Vector.php +++ b/src/Boundary/Type/DataStructure/Collection/Vector.php @@ -13,23 +13,26 @@ namespace FireHub\Core\Boundary\Type\DataStructure\Collection; +use FireHub\Core\Boundary\Capability\Access\IndexAccess; use FireHub\Core\Boundary\Type\DataStructure\Collection; /** * ### Represents a linear collection that provides indexed access to its values * - * A vector organizes its values in a contiguous logical sequence where each value is associated with a - * zero-based integer index. Values can be accessed, replaced, added, or removed according to their position - * within the sequence. + * A vector organizes its values in an ordered logical sequence where each value is associated with an integer + * index, providing positional access to the values contained within the collection. * - * The vector contract defines positional access and modification without prescribing the underlying storage - * representation, memory layout, capacity management, or implementation strategy. + * The vector contract defines the fundamental semantics of an indexed linear collection without prescribing + * whether the collection is mutable, how values are stored, or which underlying representation or implementation + * strategy is used. * - * A vector preserves the relative order of its values and allows the sequence to grow or shrink dynamically. + * A vector preserves the relative order of its values while providing deterministic access to individual values + * according to their position within the sequence. * @since 1.0.0 * * @template TValue * - * @extends Collection + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Capability\Access\IndexAccess */ -interface Vector extends Collection {} \ No newline at end of file +interface Vector extends Collection, IndexAccess {} \ No newline at end of file From d4cee9b77e94cbb4537dd6351625379e3935cafd Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 10 Sep 2026 09:49:28 +0200 Subject: [PATCH 059/118] Extend `Vector` interface with `BoundaryAccess` for enhanced access support **Details:** - Updated `Vector` interface to extend `BoundaryAccess`, formalizing read-only access to boundary elements alongside existing `IndexAccess` capabilities. - Reflected the change in PHPDoc annotations for both `Vector` interface and its extended contracts. - Ensures consistency with FireHub's access capability interfaces, enhancing modularity and clarity in data structure semantics. --- src/Boundary/Type/DataStructure/Collection/Vector.php | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/Boundary/Type/DataStructure/Collection/Vector.php b/src/Boundary/Type/DataStructure/Collection/Vector.php index ba1e543..45989d6 100644 --- a/src/Boundary/Type/DataStructure/Collection/Vector.php +++ b/src/Boundary/Type/DataStructure/Collection/Vector.php @@ -13,7 +13,9 @@ namespace FireHub\Core\Boundary\Type\DataStructure\Collection; -use FireHub\Core\Boundary\Capability\Access\IndexAccess; +use FireHub\Core\Boundary\Capability\Access\ { + BoundaryAccess, IndexAccess +}; use FireHub\Core\Boundary\Type\DataStructure\Collection; /** @@ -33,6 +35,7 @@ * @template TValue * * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Capability\Access\BoundaryAccess * @extends \FireHub\Core\Boundary\Capability\Access\IndexAccess */ -interface Vector extends Collection, IndexAccess {} \ No newline at end of file +interface Vector extends Collection, BoundaryAccess, IndexAccess {} \ No newline at end of file From 5d341c279f84286d6f3f7e9eb671678f1666c770 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 10 Sep 2026 12:11:30 +0200 Subject: [PATCH 060/118] Enhance `Maybe` type with `value()` method and introduce `NoValueException` for absence handling **Details:** - Updated `Maybe` abstract type to include a `value()` method, enabling retrieval of the contained value. - Added `NoValueException` in `Core-Standard/src/Type/Exception/NoValueException.php` to handle attempts to access a value from a `Maybe` instance representing the absence of data. - Ensures clearer and more robust handling of optional values, adhering to FireHub's principles of immutability, type safety, and modern PHP standards. --- src/Type/Exception/NoValueException.php | 27 +++++++++++++++++++++++++ src/Type/Maybe.php | 8 ++++++++ 2 files changed, 35 insertions(+) create mode 100644 src/Type/Exception/NoValueException.php diff --git a/src/Type/Exception/NoValueException.php b/src/Type/Exception/NoValueException.php new file mode 100644 index 0000000..67667f1 --- /dev/null +++ b/src/Type/Exception/NoValueException.php @@ -0,0 +1,27 @@ + + * @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.3 + * @package Core + */ + +namespace FireHub\Core\Type\Exception; + +/** + * ### Thrown when attempting to access a value that does not exist + * + * This exception is thrown when an operation attempts to retrieve the contained value from a Maybe instance that + * represents the absence of a value. + * @since 1.0.0 + */ +final class NoValueException extends ValueObjectException { + + protected const string DEFAULT_MESSAGE = 'No value exists'; + +} \ No newline at end of file diff --git a/src/Type/Maybe.php b/src/Type/Maybe.php index 30ae4f7..76a4c78 100644 --- a/src/Type/Maybe.php +++ b/src/Type/Maybe.php @@ -43,4 +43,12 @@ abstract public function isSome ():bool; */ abstract public function isNone ():bool; + /** + * ### Returns the contained value + * @since 1.0.0 + * + * @return TValue The contained value. + */ + abstract public function value ():mixed; + } \ No newline at end of file From f65518998857cc32552272d55646cc454241d90c Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 10 Sep 2026 13:31:29 +0200 Subject: [PATCH 061/118] Add foundational `Arrayable` and `Jsonable` capability interfaces for conversion contracts **Details:** - Introduced the `Arrayable` interface in `Core-Standard/src/Boundary/Capability/Conversion/Arrayable.php` to define a contract for converting objects to array representations via the `toArray()` method. - Added the `Jsonable` interface in `Core-Standard/src/Boundary/Capability/Conversion/Jsonable.php` to specify a contract for JSON conversion using the `toJson()` method. - Incorporated PHP generics (`@template`) in `Arrayable` for enhanced type safety in array key and value definitions. - Both interfaces emphasize clarity, modularity, and extensibility while adhering to FireHub's principles of modern PHP standards and ecosystem consistency. These additions establish foundational conversion contracts for object interoperability, ensuring seamless integration across the FireHub ecosystem. --- .../Capability/Conversion/Arrayable.php | 40 +++++++++++++++++++ .../Capability/Conversion/Jsonable.php | 37 +++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100644 src/Boundary/Capability/Conversion/Arrayable.php create mode 100644 src/Boundary/Capability/Conversion/Jsonable.php diff --git a/src/Boundary/Capability/Conversion/Arrayable.php b/src/Boundary/Capability/Conversion/Arrayable.php new file mode 100644 index 0000000..be601fa --- /dev/null +++ b/src/Boundary/Capability/Conversion/Arrayable.php @@ -0,0 +1,40 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Conversion; + +/** + * ### Defines conversion to an array representation + * + * Array conversion provides the ability to represent the values of an object as a PHP array. + * + * The capability defines the fundamental operation for producing an array representation without prescribing how + * values are stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TKey of array-key + * @template TValue + */ +interface Arrayable { + + /** + * ### Returns the array representation + * + * Returns the values represented as a PHP array while preserving their logical keys when applicable. + * @since 1.0.0 + * + * @return array The array representation. + */ + public function toArray ():array; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Conversion/Jsonable.php b/src/Boundary/Capability/Conversion/Jsonable.php new file mode 100644 index 0000000..0dd0ce3 --- /dev/null +++ b/src/Boundary/Capability/Conversion/Jsonable.php @@ -0,0 +1,37 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Conversion; + +/** + * ### Defines conversion to a JSON representation + * + * JSON conversion provides the ability to represent the value of an object as a JSON-encoded string. + * + * The capability defines the fundamental operation for producing a JSON representation without prescribing how + * values are stored, organized, encoded, or represented internally. + * @since 1.0.0 + */ +interface Jsonable { + + /** + * ### Returns the JSON representation + * + * Returns the value represented as a JSON-encoded string. + * @since 1.0.0 + * + * @return string The JSON representation. + */ + public function toJson ():string; + +} \ No newline at end of file From 052dc094ed0a35921639bcfd440a5feae40bc4d1 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 10 Sep 2026 14:38:30 +0200 Subject: [PATCH 062/118] Update PHPDoc in `IndexMutation` to include `NOT_FOUND` mutation outcome **Details:** - Enhanced PHPDoc for the `set` method in `IndexMutation` to document the new `NOT_FOUND` outcome when the index does not exist. - Improves clarity and completeness of the mutation contract, aligning with FireHub's principles of robust and explicit documentation. --- src/Boundary/Capability/Mutation/IndexMutation.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Boundary/Capability/Mutation/IndexMutation.php b/src/Boundary/Capability/Mutation/IndexMutation.php index 1599671..bff80cd 100644 --- a/src/Boundary/Capability/Mutation/IndexMutation.php +++ b/src/Boundary/Capability/Mutation/IndexMutation.php @@ -45,7 +45,7 @@ interface IndexMutation { *

* * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: CREATED if a new value was - * created, or UPDATED if an existing value was replaced. + * created, UPDATED if an existing value was replaced or NOT_FOUND if the index does not exist. */ public function set (int $index, mixed $value):MutationOutcome; From ea686a6c52c143c766c679b624d3640b8b518680 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 15 Sep 2026 09:54:06 +0200 Subject: [PATCH 063/118] Add foundational `Forkable` capability interface for cloning mutable instances **Details:** - Introduced the `Forkable` interface in `Core-Standard/src/Boundary/Capability/Forkable.php` to define a contract for creating independently mutable forks of instances via the `fork()` method. - Documented the contract's semantics, including initial state sharing, divergence through mutation, and copy-on-write strategies. - Enhances modularity and immutability principles in the FireHub Core ecosystem, providing a reusable mechanism for safe instance duplication. --- src/Boundary/Capability/Forkable.php | 44 ++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 src/Boundary/Capability/Forkable.php diff --git a/src/Boundary/Capability/Forkable.php b/src/Boundary/Capability/Forkable.php new file mode 100644 index 0000000..5d7be77 --- /dev/null +++ b/src/Boundary/Capability/Forkable.php @@ -0,0 +1,44 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability; + +/** + * ### Defines the ability to create an independently mutable fork + * + * Forking provides the ability to create another instance that initially represents the same logical state as the + * original instance while allowing their states to diverge independently through later mutations. + * + * Implementations may initially share internal state between the original and forked instances and defer physical + * copying until either instance is modified, such as through a copy-on-write strategy. + * + * The capability defines only the observable semantics of forking and does not prescribe how state sharing, + * ownership tracking, detachment, or copying is implemented internally. + * @since 1.0.0 + */ +interface Forkable { + + /** + * ### Creates an independently mutable fork + * + * Creates another instance that initially represents the same logical state as the current instance. + * + * The original and forked instances may share internal state until either instance is modified. Subsequent + * mutations to one instance must not affect the logical state of the other instance. + * @since 1.0.0 + * + * @return static The forked instance. + */ + public function fork ():static; + +} \ No newline at end of file From 3dfcfd00567ec665047cf7002272b282860ad435 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 15 Sep 2026 12:04:05 +0200 Subject: [PATCH 064/118] Add `Linear` classification to `Vector` and introduce `Deque` interface for double-ended collections **Details:** - Updated `Vector` interface to extend `Linear`, refining its classification as a linear data structure. - Added a new `Deque` interface to represent double-ended collections, supporting access to both front and back boundaries. - Documented `Deque`'s semantics, ensuring clarity on its linear, ordered, and boundary-accessible nature. These changes enhance the FireHub Core ecosystem with clearer data structure contracts, adhering to modularity and extensibility principles. --- .../Type/DataStructure/Collection/Deque.php | 39 +++++++++++++++++++ .../Type/DataStructure/Collection/Vector.php | 3 +- 2 files changed, 41 insertions(+), 1 deletion(-) create mode 100644 src/Boundary/Type/DataStructure/Collection/Deque.php diff --git a/src/Boundary/Type/DataStructure/Collection/Deque.php b/src/Boundary/Type/DataStructure/Collection/Deque.php new file mode 100644 index 0000000..2ca063c --- /dev/null +++ b/src/Boundary/Type/DataStructure/Collection/Deque.php @@ -0,0 +1,39 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Collection; + +use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear; +use FireHub\Core\Boundary\Capability\Access\BoundaryAccess; +use FireHub\Core\Boundary\Type\DataStructure\Collection; + +/** + * ### Represents a linear collection that provides access to both ends of its values + * + * A deque organizes its values in an ordered logical sequence where values can be accessed from both the front and + * back of the collection. + * + * The deque contract defines the fundamental semantics of a double-ended linear collection without prescribing + * whether the collection is mutable, how values are stored, or which underlying representation or implementation + * strategy is used. + * + * A deque preserves the relative order of its values while providing deterministic access to the values at both + * boundaries of the sequence. + * @since 1.0.0 + * + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Capability\Access\IndexAccess + */ +interface Deque extends Linear, Collection, BoundaryAccess {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Vector.php b/src/Boundary/Type/DataStructure/Collection/Vector.php index 45989d6..d6334b7 100644 --- a/src/Boundary/Type/DataStructure/Collection/Vector.php +++ b/src/Boundary/Type/DataStructure/Collection/Vector.php @@ -13,6 +13,7 @@ namespace FireHub\Core\Boundary\Type\DataStructure\Collection; +use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear; use FireHub\Core\Boundary\Capability\Access\ { BoundaryAccess, IndexAccess }; @@ -38,4 +39,4 @@ * @extends \FireHub\Core\Boundary\Capability\Access\BoundaryAccess * @extends \FireHub\Core\Boundary\Capability\Access\IndexAccess */ -interface Vector extends Collection, BoundaryAccess, IndexAccess {} \ No newline at end of file +interface Vector extends Linear, Collection, BoundaryAccess, IndexAccess {} \ No newline at end of file From 9e0b76975f26fca94d1751eb4fd53690d66d4afa Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 15 Sep 2026 12:07:01 +0200 Subject: [PATCH 065/118] Update `Deque` PHPDoc to replace `IndexAccess` with `BoundaryAccess` in annotations **Details:** - Modified the `Deque` interface's PHPDoc to correctly extend `BoundaryAccess` instead of `IndexAccess`. - Ensures accurate documentation of the `Deque` interface, highlighting its focus on boundary-based access operations. - Aligns with FireHub's principles of clear, precise, and consistent type contracts. --- src/Boundary/Type/DataStructure/Collection/Deque.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Boundary/Type/DataStructure/Collection/Deque.php b/src/Boundary/Type/DataStructure/Collection/Deque.php index 2ca063c..25b66b2 100644 --- a/src/Boundary/Type/DataStructure/Collection/Deque.php +++ b/src/Boundary/Type/DataStructure/Collection/Deque.php @@ -34,6 +34,6 @@ * @template TValue * * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection - * @extends \FireHub\Core\Boundary\Capability\Access\IndexAccess + * @extends \FireHub\Core\Boundary\Capability\Access\BoundaryAccess */ interface Deque extends Linear, Collection, BoundaryAccess {} \ No newline at end of file From a63cc39816d91a9495600c02653e749883581700 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 15 Sep 2026 12:18:04 +0200 Subject: [PATCH 066/118] Refactor `BoundaryAccess` to split front and back boundary capabilities **Details:** - Extracted `last()` into a new `BackAccess` interface to define back boundary access. - Extracted `first()` into a new `FrontAccess` interface to define front boundary access. - Updated `BoundaryAccess` to extend `FrontAccess` and `BackAccess` for modular composition. - Ensures clearer separation of concerns and enhanced flexibility in boundary access capabilities, adhering to FireHub's principles of modularity and extensibility. --- src/Boundary/Capability/Access/BackAccess.php | 41 +++++++++++++++++++ .../Capability/Access/BoundaryAccess.php | 31 +++----------- .../Capability/Access/FrontAccess.php | 41 +++++++++++++++++++ 3 files changed, 87 insertions(+), 26 deletions(-) create mode 100644 src/Boundary/Capability/Access/BackAccess.php create mode 100644 src/Boundary/Capability/Access/FrontAccess.php diff --git a/src/Boundary/Capability/Access/BackAccess.php b/src/Boundary/Capability/Access/BackAccess.php new file mode 100644 index 0000000..e4c2192 --- /dev/null +++ b/src/Boundary/Capability/Access/BackAccess.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 >=7.4 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Access; + +use FireHub\Core\Type\Maybe; + +/** + * ### Defines access to the back boundary value + * + * Back access provides read-only access to the last value of an ordered sequence. + * + * The capability defines the fundamental operation for retrieving the value at the back boundary without + * prescribing how values are stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + */ +interface BackAccess { + + /** + * ### Returns the last value + * + * Returns the value at the end of the sequence when it exists. + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Maybe The last value, or an empty Maybe if no value exists. + */ + public function last ():Maybe; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Access/BoundaryAccess.php b/src/Boundary/Capability/Access/BoundaryAccess.php index 25a8797..2e0ba5a 100644 --- a/src/Boundary/Capability/Access/BoundaryAccess.php +++ b/src/Boundary/Capability/Access/BoundaryAccess.php @@ -7,14 +7,12 @@ * @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 + * @php-version >=7.0 * @package Core */ namespace FireHub\Core\Boundary\Capability\Access; -use FireHub\Core\Type\Maybe; - /** * ### Defines access to boundary values * @@ -25,27 +23,8 @@ * @since 1.0.0 * * @template TValue + * + * @extends \FireHub\Core\Boundary\Capability\Access\FrontAccess + * @extends \FireHub\Core\Boundary\Capability\Access\BackAccess */ -interface BoundaryAccess { - - /** - * ### Returns the first value - * - * Returns the value at the beginning of the sequence when it exists. - * @since 1.0.0 - * - * @return \FireHub\Core\Type\Maybe The first value, or an empty Maybe if no value exists. - */ - public function first ():Maybe; - - /** - * ### Returns the last value - * - * Returns the value at the end of the sequence when it exists. - * @since 1.0.0 - * - * @return \FireHub\Core\Type\Maybe The last value, or an empty Maybe if no value exists. - */ - public function last ():Maybe; - -} +interface BoundaryAccess extends FrontAccess, BackAccess {} \ No newline at end of file diff --git a/src/Boundary/Capability/Access/FrontAccess.php b/src/Boundary/Capability/Access/FrontAccess.php new file mode 100644 index 0000000..f30279d --- /dev/null +++ b/src/Boundary/Capability/Access/FrontAccess.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 >=7.4 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Access; + +use FireHub\Core\Type\Maybe; + +/** + * ### Defines access to the front boundary value + * + * Front access provides read-only access to the first value of an ordered sequence. + * + * The capability defines the fundamental operation for retrieving the value at the front boundary without + * prescribing how values are stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + */ +interface FrontAccess { + + /** + * ### Returns the first value + * + * Returns the value at the beginning of the sequence when it exists. + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Maybe The first value, or an empty Maybe if no value exists. + */ + public function first ():Maybe; + +} \ No newline at end of file From 3a37c752f245cd20491c10e3e85795864355777f Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 15 Sep 2026 14:23:27 +0200 Subject: [PATCH 067/118] Add new `Stack` interface and adjust imports in `Vector` and `Deque` **Details:** - Introduced the `Stack` interface for last-in, first-out collections with clear, annotated semantics about its linear structure and top-bound access. - Adjusted import ordering in `Vector` and `Deque` to align with FireHub's namespace conventions. - Enhances the Core ecosystem by extending modularity and clarifying type contracts for stack-based data structures. --- .../Type/DataStructure/Collection/Deque.php | 2 +- .../Type/DataStructure/Collection/Stack.php | 40 +++++++++++++++++++ .../Type/DataStructure/Collection/Vector.php | 2 +- 3 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 src/Boundary/Type/DataStructure/Collection/Stack.php diff --git a/src/Boundary/Type/DataStructure/Collection/Deque.php b/src/Boundary/Type/DataStructure/Collection/Deque.php index 25b66b2..9c27963 100644 --- a/src/Boundary/Type/DataStructure/Collection/Deque.php +++ b/src/Boundary/Type/DataStructure/Collection/Deque.php @@ -14,8 +14,8 @@ namespace FireHub\Core\Boundary\Type\DataStructure\Collection; use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear; -use FireHub\Core\Boundary\Capability\Access\BoundaryAccess; use FireHub\Core\Boundary\Type\DataStructure\Collection; +use FireHub\Core\Boundary\Capability\Access\BoundaryAccess; /** * ### Represents a linear collection that provides access to both ends of its values diff --git a/src/Boundary/Type/DataStructure/Collection/Stack.php b/src/Boundary/Type/DataStructure/Collection/Stack.php new file mode 100644 index 0000000..a9563f5 --- /dev/null +++ b/src/Boundary/Type/DataStructure/Collection/Stack.php @@ -0,0 +1,40 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Collection; + +use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear; +use FireHub\Core\Boundary\Type\DataStructure\Collection; +use FireHub\Core\Boundary\Capability\Access\BackAccess; + +/** + * ### Represents a linear collection that provides last-in, first-out access to its values + * + * A stack organizes its values in an ordered logical sequence according to last-in, first-out semantics, where + * the most recently added value represents the top of the collection and is the first value available for + * retrieval. + * + * The stack contract defines the fundamental semantics of a last-in, first-out linear collection without + * prescribing whether the collection is mutable, how values are stored, or which underlying representation or + * implementation strategy is used. + * + * A stack preserves the relative order of its values while providing deterministic access to the value at the + * top of the sequence. + * @since 1.0.0 + * + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Capability\Access\BackAccess + */ +interface Stack extends Linear, Collection, BackAccess {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Vector.php b/src/Boundary/Type/DataStructure/Collection/Vector.php index d6334b7..1313d41 100644 --- a/src/Boundary/Type/DataStructure/Collection/Vector.php +++ b/src/Boundary/Type/DataStructure/Collection/Vector.php @@ -14,10 +14,10 @@ namespace FireHub\Core\Boundary\Type\DataStructure\Collection; use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear; +use FireHub\Core\Boundary\Type\DataStructure\Collection; use FireHub\Core\Boundary\Capability\Access\ { BoundaryAccess, IndexAccess }; -use FireHub\Core\Boundary\Type\DataStructure\Collection; /** * ### Represents a linear collection that provides indexed access to its values From 731056361cef451d5a7d49723cb9e8282ec7c33f Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 15 Sep 2026 14:26:58 +0200 Subject: [PATCH 068/118] Add `Queue` interface to represent first-in, first-out linear collections **Details:** - Introduced a new `Queue` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Queue.php` to define a contract for first-in, first-out (FIFO) linear collections. - Extended `Linear`, `Collection`, and `FrontAccess` interfaces to integrate linearity, collection semantics, and front-bound access capabilities. - Documented `Queue` semantics, emphasizing its ordered value preservation and deterministic front-access behavior. - Enhances the FireHub Core ecosystem with a modular, extensible type contract for FIFO-based data structures, adhering to the project's principles of clarity and robust design. --- .../Type/DataStructure/Collection/Queue.php | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 src/Boundary/Type/DataStructure/Collection/Queue.php diff --git a/src/Boundary/Type/DataStructure/Collection/Queue.php b/src/Boundary/Type/DataStructure/Collection/Queue.php new file mode 100644 index 0000000..eacbf26 --- /dev/null +++ b/src/Boundary/Type/DataStructure/Collection/Queue.php @@ -0,0 +1,39 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Collection; + +use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear; +use FireHub\Core\Boundary\Type\DataStructure\Collection; +use FireHub\Core\Boundary\Capability\Access\FrontAccess; + +/** + * ### Represents a linear collection that provides first-in, first-out access to its values + * + * A queue organizes its values in an ordered logical sequence according to first-in, first-out semantics, where + * the earliest added value represents the front of the collection and is the first value available for retrieval. + * + * The queue contract defines the fundamental semantics of a first-in, first-out linear collection without + * prescribing whether the collection is mutable, how values are stored, or which underlying representation or + * implementation strategy is used. + * + * A queue preserves the relative order of its values while providing deterministic access to the value at the + * front of the sequence. + * @since 1.0.0 + * + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Capability\Access\FrontAccess + */ +interface Queue extends Linear, Collection, FrontAccess {} \ No newline at end of file From 0e6120461794301bd792adbdb5cce7031c1902b2 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 15 Sep 2026 14:56:46 +0200 Subject: [PATCH 069/118] Add `Unordered` and `Associative` interfaces for data structure classifications **Details:** - Introduced the `Unordered` interface to classify data structures without positional order semantics, documenting characteristics like membership testing, uniqueness, and multiplicity support. - Added the `Associative` interface to classify data structures that organize values by key-value association, emphasizing keyed access and mutation capabilities. - Both interfaces enhance the FireHub Core ecosystem by defining modular and extensible type contracts for structural classification while adhering to project standards of clarity and robust design. --- .../Classification/Associative.php | 30 ++++++++++++++++++ .../Classification/Unordered.php | 31 +++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 src/Boundary/Type/DataStructure/Classification/Associative.php create mode 100644 src/Boundary/Type/DataStructure/Classification/Unordered.php diff --git a/src/Boundary/Type/DataStructure/Classification/Associative.php b/src/Boundary/Type/DataStructure/Classification/Associative.php new file mode 100644 index 0000000..6676823 --- /dev/null +++ b/src/Boundary/Type/DataStructure/Classification/Associative.php @@ -0,0 +1,30 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Classification; + +/** + * ### Identifies a data structure whose values are organized by key association + * + * An associative data structure organizes its values through associations between keys and values, where each + * value is identified or addressed according to an associated key rather than solely by its sequential position. + * + * This classification describes the organizational characteristics of a data structure and does not prescribe + * a specific inheritance relationship, storage representation, key type, access strategy, ordering, or + * implementation. + * + * Associative structures may provide keyed access, keyed mutation, iteration over key-value associations, or + * additional operations depending on their concrete contract. + * @since 1.0.0 + */ +interface Associative {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Classification/Unordered.php b/src/Boundary/Type/DataStructure/Classification/Unordered.php new file mode 100644 index 0000000..b6f996e --- /dev/null +++ b/src/Boundary/Type/DataStructure/Classification/Unordered.php @@ -0,0 +1,31 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Classification; + +/** + * ### Identifies a data structure whose values have no defined positional order + * + * An unordered data structure organizes its values without assigning semantic significance to their relative + * positions or iteration order. Values belong to the structure independently of where they appear in its + * underlying representation. + * + * This classification describes the organizational characteristics of a data structure and does not prescribe + * a specific inheritance relationship, storage representation, lookup strategy, iteration order, or + * implementation. + * + * Unordered structures may provide membership testing, uniqueness semantics, multiplicity semantics, or other + * operations depending on their concrete contract. + * @since 1.0.0 + */ +interface Unordered {} \ No newline at end of file From 56f944e48ed291cb70b3c328bd9164dd039e529d Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 15 Sep 2026 15:02:56 +0200 Subject: [PATCH 070/118] Add `Map` interface to define key-value associative collections and refactor generic type annotations across data structures **Details:** - Introduced the `Map` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Map.php` to describe associative collections maintaining key-value pairs. Documented its semantics with a focus on deterministic access via keys and constraints on key-value associations. - Updated generic type annotations in `Collection`, `Queue`, `Stack`, `Deque`, `Vector`, and `DataStructure` to include the `TKey` template parameter, enabling support for typed keys in collections. - Adjusted `Collection` to extend `DataStructure` and `Enumerable` for consistency in hierarchical type contracts. - Enhances the FireHub Core ecosystem by enabling clearer type safety, extensibility, and modularity while maintaining alignment with project principles of robust design and modern PHP standards. --- src/Boundary/Type/DataStructure.php | 1 + .../Type/DataStructure/Collection.php | 5 ++- .../Type/DataStructure/Collection/Deque.php | 2 +- .../Type/DataStructure/Collection/Map.php | 43 +++++++++++++++++++ .../Type/DataStructure/Collection/Queue.php | 2 +- .../Type/DataStructure/Collection/Stack.php | 2 +- .../Type/DataStructure/Collection/Vector.php | 2 +- 7 files changed, 51 insertions(+), 6 deletions(-) create mode 100644 src/Boundary/Type/DataStructure/Collection/Map.php diff --git a/src/Boundary/Type/DataStructure.php b/src/Boundary/Type/DataStructure.php index 975eb55..7f35e6f 100644 --- a/src/Boundary/Type/DataStructure.php +++ b/src/Boundary/Type/DataStructure.php @@ -28,6 +28,7 @@ * rather than to represent a domain value identified solely by its value. * @since 1.0.0 * + * @template TKey * @template TValue */ interface DataStructure {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection.php b/src/Boundary/Type/DataStructure/Collection.php index 57810f6..3d6e663 100644 --- a/src/Boundary/Type/DataStructure/Collection.php +++ b/src/Boundary/Type/DataStructure/Collection.php @@ -34,9 +34,10 @@ * contract defined by DataStructure. * @since 1.0.0 * + * @template TKey * @template TValue * - * @extends \FireHub\Core\Boundary\Type\DataStructure - * @extends \FireHub\Core\Boundary\Type\Enumerable + * @extends \FireHub\Core\Boundary\Type\DataStructure + * @extends \FireHub\Core\Boundary\Type\Enumerable */ interface Collection extends DataStructure, Enumerable, Metrics {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Deque.php b/src/Boundary/Type/DataStructure/Collection/Deque.php index 9c27963..9e26bf6 100644 --- a/src/Boundary/Type/DataStructure/Collection/Deque.php +++ b/src/Boundary/Type/DataStructure/Collection/Deque.php @@ -33,7 +33,7 @@ * * @template TValue * - * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection * @extends \FireHub\Core\Boundary\Capability\Access\BoundaryAccess */ interface Deque extends Linear, Collection, BoundaryAccess {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Map.php b/src/Boundary/Type/DataStructure/Collection/Map.php new file mode 100644 index 0000000..52d8b05 --- /dev/null +++ b/src/Boundary/Type/DataStructure/Collection/Map.php @@ -0,0 +1,43 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Collection; + +use FireHub\Core\Boundary\Type\DataStructure\Classification\Associative; +use FireHub\Core\Boundary\Type\DataStructure\Collection; +use FireHub\Core\Boundary\Capability\Access\ { + BoundaryAccess, KeyAccess +}; + +/** + * ### Represents a collection that associates keys with values + * + * A map organizes its values through associations between keys and values, where each value is identified by a + * corresponding key that provides deterministic access to the associated value. + * + * The map contract defines the fundamental semantics of an associative collection without prescribing whether + * the collection is mutable, how key-value associations are stored, whether iteration order is significant, or + * which underlying representation or implementation strategy is used. + * + * A map maintains at most one value associated with each key while allowing values to be retrieved according to + * their corresponding keys. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Capability\Access\BoundaryAccess + * @extends \FireHub\Core\Boundary\Capability\Access\KeyAccess + */ +interface Map extends Associative, Collection, BoundaryAccess, KeyAccess {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Queue.php b/src/Boundary/Type/DataStructure/Collection/Queue.php index eacbf26..9e50566 100644 --- a/src/Boundary/Type/DataStructure/Collection/Queue.php +++ b/src/Boundary/Type/DataStructure/Collection/Queue.php @@ -33,7 +33,7 @@ * * @template TValue * - * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection * @extends \FireHub\Core\Boundary\Capability\Access\FrontAccess */ interface Queue extends Linear, Collection, FrontAccess {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Stack.php b/src/Boundary/Type/DataStructure/Collection/Stack.php index a9563f5..cd6f6b0 100644 --- a/src/Boundary/Type/DataStructure/Collection/Stack.php +++ b/src/Boundary/Type/DataStructure/Collection/Stack.php @@ -34,7 +34,7 @@ * * @template TValue * - * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection * @extends \FireHub\Core\Boundary\Capability\Access\BackAccess */ interface Stack extends Linear, Collection, BackAccess {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Vector.php b/src/Boundary/Type/DataStructure/Collection/Vector.php index 1313d41..73c57f7 100644 --- a/src/Boundary/Type/DataStructure/Collection/Vector.php +++ b/src/Boundary/Type/DataStructure/Collection/Vector.php @@ -35,7 +35,7 @@ * * @template TValue * - * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection * @extends \FireHub\Core\Boundary\Capability\Access\BoundaryAccess * @extends \FireHub\Core\Boundary\Capability\Access\IndexAccess */ From 9f27294c8e941ccdb70a9671bc37a775965f4e3c Mon Sep 17 00:00:00 2001 From: Riddick Date: Wed, 16 Sep 2026 08:33:37 +0200 Subject: [PATCH 071/118] Remove `BoundaryAccess` from `Map` interface to simplify key-value contract **Details:** - Removed the `BoundaryAccess` import and inheritance from the `Map` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Map.php`. - Streamlined `Map` to focus solely on `KeyAccess` for key-based associative collections, aligning with its primary purpose. - Improves clarity and reduces unnecessary complexity in the `Map` interface, adhering to FireHub's principles of modularity and precise type contracts. --- src/Boundary/Type/DataStructure/Collection/Map.php | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/Boundary/Type/DataStructure/Collection/Map.php b/src/Boundary/Type/DataStructure/Collection/Map.php index 52d8b05..49aa59d 100644 --- a/src/Boundary/Type/DataStructure/Collection/Map.php +++ b/src/Boundary/Type/DataStructure/Collection/Map.php @@ -15,9 +15,7 @@ use FireHub\Core\Boundary\Type\DataStructure\Classification\Associative; use FireHub\Core\Boundary\Type\DataStructure\Collection; -use FireHub\Core\Boundary\Capability\Access\ { - BoundaryAccess, KeyAccess -}; +use FireHub\Core\Boundary\Capability\Access\KeyAccess; /** * ### Represents a collection that associates keys with values @@ -40,4 +38,4 @@ * @extends \FireHub\Core\Boundary\Capability\Access\BoundaryAccess * @extends \FireHub\Core\Boundary\Capability\Access\KeyAccess */ -interface Map extends Associative, Collection, BoundaryAccess, KeyAccess {} \ No newline at end of file +interface Map extends Associative, Collection, KeyAccess {} \ No newline at end of file From 4bfcc91ee999cfcc07f9fa2500ebf76970926e29 Mon Sep 17 00:00:00 2001 From: Riddick Date: Wed, 16 Sep 2026 08:36:17 +0200 Subject: [PATCH 072/118] Remove redundant `BoundaryAccess` inheritance from `Map` interface **Details:** - Eliminated the unnecessary `BoundaryAccess` inheritance from the `Map` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Map.php`. - Streamlines the `Map` contract to focus exclusively on `KeyAccess` for clarity and reduced complexity. - Enhances modularity and precision of type definitions, adhering to FireHub's principles of clear and robust design. --- src/Boundary/Type/DataStructure/Collection/Map.php | 1 - 1 file changed, 1 deletion(-) diff --git a/src/Boundary/Type/DataStructure/Collection/Map.php b/src/Boundary/Type/DataStructure/Collection/Map.php index 49aa59d..1e3463b 100644 --- a/src/Boundary/Type/DataStructure/Collection/Map.php +++ b/src/Boundary/Type/DataStructure/Collection/Map.php @@ -35,7 +35,6 @@ * @template TValue * * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection - * @extends \FireHub\Core\Boundary\Capability\Access\BoundaryAccess * @extends \FireHub\Core\Boundary\Capability\Access\KeyAccess */ interface Map extends Associative, Collection, KeyAccess {} \ No newline at end of file From 8b8773766d525a9ceb43818f0c469e2c9d8953e3 Mon Sep 17 00:00:00 2001 From: Riddick Date: Wed, 16 Sep 2026 10:05:59 +0200 Subject: [PATCH 073/118] Add `Set`, `ValueAccess`, and `ValueMutation` interfaces; enhance `MutationOutcome` enum **Details:** - Introduced the `Set` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Set.php` to define a contract for unique value collections, documenting membership semantics and enforcing value equality without prescribing internal implementation. - Added the `ValueAccess` interface to provide a capability for membership testing, ensuring modularity in value retrieval operations. - Implemented the `ValueMutation` interface for value-based mutation capabilities, defining operations for adding and removing values with clear outcome semantics. - Extended the `MutationOutcome` enum to include the `ALREADY_EXISTS` case, enhancing mutation result granularity for operations like `add`. - Enhances the FireHub Core ecosystem by introducing modular and extensible core concepts, adhering to project principles of robust design, clarity, and modern PHP standards. --- .../Capability/Access/ValueAccess.php | 41 +++++++++++++ .../Capability/Mutation/ValueMutation.php | 61 +++++++++++++++++++ .../Type/DataStructure/Collection/Set.php | 36 +++++++++++ src/Meta/Enum/MutationOutcome.php | 6 ++ 4 files changed, 144 insertions(+) create mode 100644 src/Boundary/Capability/Access/ValueAccess.php create mode 100644 src/Boundary/Capability/Mutation/ValueMutation.php create mode 100644 src/Boundary/Type/DataStructure/Collection/Set.php diff --git a/src/Boundary/Capability/Access/ValueAccess.php b/src/Boundary/Capability/Access/ValueAccess.php new file mode 100644 index 0000000..fd80457 --- /dev/null +++ b/src/Boundary/Capability/Access/ValueAccess.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 >=7.4 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Access; + +/** + * ### Defines value-based access + * + * Value access provides the ability to determine whether a specific value is present within an object. + * + * The capability defines the fundamental operation for value membership without prescribing how values are stored, + * compared, indexed, or located internally. + * @since 1.0.0 + * + * @template TValue + */ +interface ValueAccess { + + /** + * ### Checks whether a value exists + * @since 1.0.0 + * + * @param TValue $value

+ * The value to check. + *

+ * + * @return bool True if the value exists, false otherwise. + */ + public function contains (mixed $value):bool; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/ValueMutation.php b/src/Boundary/Capability/Mutation/ValueMutation.php new file mode 100644 index 0000000..f0be3e9 --- /dev/null +++ b/src/Boundary/Capability/Mutation/ValueMutation.php @@ -0,0 +1,61 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Meta\Enum\MutationOutcome; + +/** + * ### Defines value-based mutation + * + * Value mutation provides the ability to add and remove values using the value itself as the mutation target. + * + * The capability defines the fundamental mutation operations without prescribing how values are stored, compared, + * indexed, or modified internally. + * @since 1.0.0 + * + * @template TValue + */ +interface ValueMutation { + + /** + * ### Adds a value + * + * Adds a value to the sequence. If the value already exists, it is ignored. + * @since 1.0.0 + * + * @param TValue $value

+ * The value to add. + *

+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: CREATED if a new value was + * created, or ALREADY_EXISTS if the value already exists. + */ + public function add (mixed $value):MutationOutcome; + + /** + * ### Removes a value + * + * Removes a value from the sequence. If the value does not exist, it is ignored. + * @since 1.0.0 + * + * @param TValue $value

+ * The value to remove. + *

+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: REMOVED if a value was removed, + * or NOT_FOUND if the key does not exist. + */ + public function remove (mixed $value):MutationOutcome; + +} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Set.php b/src/Boundary/Type/DataStructure/Collection/Set.php new file mode 100644 index 0000000..d26152e --- /dev/null +++ b/src/Boundary/Type/DataStructure/Collection/Set.php @@ -0,0 +1,36 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Collection; + +use FireHub\Core\Boundary\Type\DataStructure\Classification\Unordered; +use FireHub\Core\Boundary\Type\DataStructure\Collection; +use FireHub\Core\Boundary\Capability\Access\ValueAccess; + +/** + * ### Defines the Set data structure + * + * Represents a collection of unique values where each value can occur at most once. + * + * A Set defines membership based on value equality and does not associate values with separate keys. + * + * The contract defines the fundamental semantics of a Set without prescribing how values are stored, how uniqueness + * is enforced, or how membership lookup is implemented internally. + * @since 1.0.0 + * + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Capability\Access\ValueAccess + */ +interface Set extends Unordered, Collection, ValueAccess {} \ No newline at end of file diff --git a/src/Meta/Enum/MutationOutcome.php b/src/Meta/Enum/MutationOutcome.php index aa41f9e..256a5f3 100644 --- a/src/Meta/Enum/MutationOutcome.php +++ b/src/Meta/Enum/MutationOutcome.php @@ -33,6 +33,12 @@ enum MutationOutcome { */ case UPDATED; + /** + * ### Entry Already Exists + * @since 1.0.0 + */ + case ALREADY_EXISTS; + /** * ### Entry Removed * @since 1.0.0 From 2e2441790bda4db46d5e10027b4d8bb24a5db12d Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 17 Sep 2026 12:02:20 +0200 Subject: [PATCH 074/118] Add `MultiplicityAccess`, `MultiplicityMutation`, `Bag`, and `DistinctMetrics` interfaces for multiplicity and distinct value operations **Details:** - Introduced the `MultiplicityAccess` interface to provide multiplicity-based value access, enabling frequency counting of specific values in objects. - Added the `MultiplicityMutation` interface to define mutation operations, including adding, removing, and clearing occurrences of values. - Defined the `Bag` interface as an unordered data structure supporting multiple occurrences of logically equal values, integrating `MultiplicityAccess`, `Unordered`, and `Collection` capabilities. - Implemented the `DistinctMetrics` interface for measuring the count of distinct values in data structures. - These additions enrich the FireHub Core ecosystem with modularity, extensibility, and contracts for working with data structures that distinguish between occurrences and distinct values, adhering to project standards of robust design and modern PHP practices. --- .../Capability/Access/MultiplicityAccess.php | 44 +++++++++++ .../Measurement/DistinctMetrics.php | 36 +++++++++ .../Mutation/MultiplicityMutation.php | 74 +++++++++++++++++++ .../Type/DataStructure/Collection/Bag.php | 40 ++++++++++ 4 files changed, 194 insertions(+) create mode 100644 src/Boundary/Capability/Access/MultiplicityAccess.php create mode 100644 src/Boundary/Capability/Measurement/DistinctMetrics.php create mode 100644 src/Boundary/Capability/Mutation/MultiplicityMutation.php create mode 100644 src/Boundary/Type/DataStructure/Collection/Bag.php diff --git a/src/Boundary/Capability/Access/MultiplicityAccess.php b/src/Boundary/Capability/Access/MultiplicityAccess.php new file mode 100644 index 0000000..4db35cf --- /dev/null +++ b/src/Boundary/Capability/Access/MultiplicityAccess.php @@ -0,0 +1,44 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Access; + +/** + * ### Defines multiplicity-based value access + * + * Multiplicity access provides the ability to determine whether a specific value is present within an object and + * retrieve the number of times that value occurs. + * + * The capability extends value-based access with occurrence counting without prescribing how values are stored, + * compared, indexed, or located internally. + * @since 1.0.0 + * + * @template TValue + * + * @extends \FireHub\Core\Boundary\Capability\Access\ValueAccess + */ +interface MultiplicityAccess extends ValueAccess { + + /** + * ### Gets the number of occurrences of a value + * @since 1.0.0 + * + * @param TValue $value

+ * The value whose occurrences should be counted. + *

+ * + * @return non-negative-int The number of occurrences of the specified value. + */ + public function frequency (mixed $value):int; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Measurement/DistinctMetrics.php b/src/Boundary/Capability/Measurement/DistinctMetrics.php new file mode 100644 index 0000000..fe3476b --- /dev/null +++ b/src/Boundary/Capability/Measurement/DistinctMetrics.php @@ -0,0 +1,36 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Measurement; + +/** + * ### Defines distinct-value measurement + * + * Distinct metrics extends general measurement with the ability to determine the number of logically distinct + * values represented by an object. + * + * The distinct size represents the number of unique values according to the equality semantics defined by the + * implementation and is independent of the total number of value occurrences. + * @since 1.0.0 + */ +interface DistinctMetrics extends Metrics { + + /** + * ### Gets the number of distinct values + * @since 1.0.0 + * + * @return non-negative-int The number of logically distinct values. + */ + public function distinctSize ():int; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/MultiplicityMutation.php b/src/Boundary/Capability/Mutation/MultiplicityMutation.php new file mode 100644 index 0000000..e326ac2 --- /dev/null +++ b/src/Boundary/Capability/Mutation/MultiplicityMutation.php @@ -0,0 +1,74 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +/** + * ### Defines multiplicity-based value mutation + * + * Multiplicity mutation provides the ability to add and remove a specified number of occurrences of a value and + * remove all occurrences of a value. + * + * The capability applies to objects whose mutation semantics allow logically equal values to occur multiple times. + * It does not prescribe how values, occurrence counts, or equality semantics are represented internally. + * @since 1.0.0 + * + * @template TValue + */ +interface MultiplicityMutation { + + /** + * ### Adds occurrences of a value + * @since 1.0.0 + * + * @param TValue $value

+ * The value whose occurrences should be added. + *

+ * + * @param positive-int $count

+ * The number of occurrences to add. + *

+ */ + public function add (mixed $value, int $count = 1):void; + + /** + * ### Removes occurrences of a value + * + * Removes up to the specified number of occurrences of the value. + * @since 1.0.0 + * + * @param TValue $value

+ * The value whose occurrences should be removed. + *

+ * + * @param positive-int $count

+ * The maximum number of occurrences to remove. + *

+ * + * @return non-negative-int The number of occurrences actually removed. + */ + public function remove (mixed $value, int $count = 1):int; + + /** + * ### Removes all occurrences of a value + * @since 1.0.0 + * + * @param TValue $value

+ * The value whose occurrences should be removed. + *

+ * + * @return non-negative-int The number of occurrences removed. + */ + public function removeAll (mixed $value):int; + +} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Bag.php b/src/Boundary/Type/DataStructure/Collection/Bag.php new file mode 100644 index 0000000..bd69cb1 --- /dev/null +++ b/src/Boundary/Type/DataStructure/Collection/Bag.php @@ -0,0 +1,40 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Collection; + +use FireHub\Core\Boundary\Type\DataStructure\Classification\Unordered; +use FireHub\Core\Boundary\Type\DataStructure\Collection; +use FireHub\Core\Boundary\Capability\Access\MultiplicityAccess; + +/** + * ### Defines the Bag data structure + * + * Represents an unordered collection of values where logically equal values may occur multiple times. + * + * A Bag preserves the multiplicity of its values without assigning positional or user-defined key semantics to + * individual occurrences. + * + * The number of occurrences of a particular value forms part of the observable semantics of the data structure, + * while the ordering of those occurrences does not. + * + * The contract defines the fundamental semantics of a Bag without prescribing how values, occurrence counts, + * equality, or storage are represented internally. + * @since 1.0.0 + * + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Capability\Access\MultiplicityAccess + */ +interface Bag extends Unordered, Collection, MultiplicityAccess {} \ No newline at end of file From 671d3762573ada70fbece1aaee6ac64ccb599e71 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 17 Sep 2026 12:10:14 +0200 Subject: [PATCH 075/118] Refactor `MultiplicityMutation` interface to return `MutationOutcome` **Details:** - Updated the `add`, `remove`, and `removeAll` methods in `MultiplicityMutation` to return `MutationOutcome` instead of primitive types for consistent mutation results. - Enhanced method documentation with detailed descriptions of possible enum values (`CREATED`, `ALREADY_EXISTS`, `REMOVED`, `UPDATED`, `NOT_FOUND`) for precise outcome semantics. - Added a `use` statement for the `MutationOutcome` enum to improve code clarity and maintainability. - Aligns with FireHub Core's design principles of modern PHP practices, robust type safety, and meaningful return types. --- .../Mutation/MultiplicityMutation.php | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/src/Boundary/Capability/Mutation/MultiplicityMutation.php b/src/Boundary/Capability/Mutation/MultiplicityMutation.php index e326ac2..355c89e 100644 --- a/src/Boundary/Capability/Mutation/MultiplicityMutation.php +++ b/src/Boundary/Capability/Mutation/MultiplicityMutation.php @@ -13,6 +13,8 @@ namespace FireHub\Core\Boundary\Capability\Mutation; +use FireHub\Core\Meta\Enum\MutationOutcome; + /** * ### Defines multiplicity-based value mutation * @@ -38,8 +40,11 @@ interface MultiplicityMutation { * @param positive-int $count

* The number of occurrences to add. *

+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: CREATED if a new value was created, + * or ALREADY_EXISTS if the value already exists. */ - public function add (mixed $value, int $count = 1):void; + public function add (mixed $value, int $count = 1):MutationOutcome; /** * ### Removes occurrences of a value @@ -55,9 +60,10 @@ public function add (mixed $value, int $count = 1):void; * The maximum number of occurrences to remove. *

* - * @return non-negative-int The number of occurrences actually removed. + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: REMOVED if last value was removed, + * UPDATED if value was removed but some are still left, or NOT_FOUND if the value does not exist. */ - public function remove (mixed $value, int $count = 1):int; + public function remove (mixed $value, int $count = 1):MutationOutcome; /** * ### Removes all occurrences of a value @@ -67,8 +73,9 @@ public function remove (mixed $value, int $count = 1):int; * The value whose occurrences should be removed. *

* - * @return non-negative-int The number of occurrences removed. + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: REMOVED if all values were removed, + * or NOT_FOUND if the value does not exist. */ - public function removeAll (mixed $value):int; + public function removeAll (mixed $value):MutationOutcome; } \ No newline at end of file From 800c4384964630a5d550340e7887680071b75893 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 17 Sep 2026 12:13:44 +0200 Subject: [PATCH 076/118] Clarify `MultiplicityMutation::add` outcome documentation **Details:** - Updated PHPDoc for the `add` method in `MultiplicityMutation` to replace the outcome `ALREADY_EXISTS` with `UPDATED` for scenarios where an existing value is updated with a new occurrence. - Aligns outcome terminology with the `MutationOutcome` enum semantics for greater precision and consistency in mutation operations. --- src/Boundary/Capability/Mutation/MultiplicityMutation.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Boundary/Capability/Mutation/MultiplicityMutation.php b/src/Boundary/Capability/Mutation/MultiplicityMutation.php index 355c89e..ff1eae7 100644 --- a/src/Boundary/Capability/Mutation/MultiplicityMutation.php +++ b/src/Boundary/Capability/Mutation/MultiplicityMutation.php @@ -42,7 +42,7 @@ interface MultiplicityMutation { *

* * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: CREATED if a new value was created, - * or ALREADY_EXISTS if the value already exists. + * or UPDATED if the value already exists a new occurrence was added. */ public function add (mixed $value, int $count = 1):MutationOutcome; From a78fa20baa96512719b588600ec3915f1c35a016 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 17 Sep 2026 13:50:01 +0200 Subject: [PATCH 077/118] Add `Stream` interface for lazy, non-materialized sequences **Details:** - Introduced the `Stream` interface in `Core-Standard/src/Boundary/Type/DataStructure/Stream.php` to define a contract for sequences of values that can be produced lazily and consumed incrementally. - Documented `Stream` characteristics, including support for finite, unbounded, or externally produced sequences without requiring full materialization in memory. - Extended `DataStructure` and `Enumerable` interfaces, specifying that a `Stream` does not guarantee reusable iteration, known size, or random access. - Enhances the FireHub Core ecosystem by enabling modular and extensible support for lazy and on-demand data streams, adhering to principles of clarity, robust design, and modern PHP practices. --- src/Boundary/Type/DataStructure/Stream.php | 39 ++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 src/Boundary/Type/DataStructure/Stream.php diff --git a/src/Boundary/Type/DataStructure/Stream.php b/src/Boundary/Type/DataStructure/Stream.php new file mode 100644 index 0000000..e1aaeda --- /dev/null +++ b/src/Boundary/Type/DataStructure/Stream.php @@ -0,0 +1,39 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure; + +use FireHub\Core\Boundary\Type\ { + DataStructure, Enumerable +}; + +/** + * ### Defines the Stream data structure + * + * Represents a sequence of values that may be produced lazily as they are consumed. + * + * A Stream does not require its complete contents to be materialized in memory and may represent finite, + * unbounded, or externally produced sequences of values. + * + * Unlike collections, a Stream does not imply reusable iteration, known size, random access, or mutable storage. + * Concrete implementations define how values are produced and whether the underlying source may be consumed more + * than once. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure + * @extends \FireHub\Core\Boundary\Type\Enumerable + */ +interface Stream extends DataStructure, Enumerable {} \ No newline at end of file From 29ed03c718fa9d05c277f2f3730f5f9e73da67d0 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 17 Sep 2026 15:31:34 +0200 Subject: [PATCH 078/118] Add `Record`, `Struct`, and `Tuple` interfaces for structured data representations **Details:** - Introduced the `Record` interface in `Core-Standard/src/Boundary/Type/DataStructure/Record.php` to define a contract for composite values made of logically related components, distinguishing it from collections. - Added the `Struct` interface in `Core-Standard/src/Boundary/Type/DataStructure/Record/Struct.php` to represent fixed-size keyed records with immutable key sets, extending `Record` and `KeyAccess`. - Implemented the `Tuple` interface in `Core-Standard/src/Boundary/Type/DataStructure/Record/Tuple.php` to define a fixed-size positional record with zero-based integer indexing, extending `Record`, `Linear`, and access-related interfaces. - Enhances the FireHub Core ecosystem by providing modular and extensible structures for logically grouped data, adhering to robust design and clarity principles. --- src/Boundary/Type/DataStructure/Record.php | 42 ++++++++++++++++++ .../Type/DataStructure/Record/Struct.php | 40 +++++++++++++++++ .../Type/DataStructure/Record/Tuple.php | 44 +++++++++++++++++++ 3 files changed, 126 insertions(+) create mode 100644 src/Boundary/Type/DataStructure/Record.php create mode 100644 src/Boundary/Type/DataStructure/Record/Struct.php create mode 100644 src/Boundary/Type/DataStructure/Record/Tuple.php diff --git a/src/Boundary/Type/DataStructure/Record.php b/src/Boundary/Type/DataStructure/Record.php new file mode 100644 index 0000000..ab4cf3e --- /dev/null +++ b/src/Boundary/Type/DataStructure/Record.php @@ -0,0 +1,42 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure; + +use FireHub\Core\Boundary\Type\ { + DataStructure, Enumerable +}; + +/** + * ### Defines the Record data structure + * + * A Record represents a structured value composed of a fixed set of logically related elements. + * + * Unlike a Collection, whose elements represent members of a collection, the elements of a Record represent + * individual components of a single composite value. + * + * This contract defines only the semantic foundation shared by Record data structures and does not prescribe how + * individual elements are identified, ordered, accessed, or represented. Concrete Record types may use positional, + * named, or other forms of element identification. + * + * Record implementations may further define structural characteristics and access capabilities appropriate to + * their semantics. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure + * @extends \FireHub\Core\Boundary\Type\Enumerable + */ +interface Record extends DataStructure, Enumerable {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Record/Struct.php b/src/Boundary/Type/DataStructure/Record/Struct.php new file mode 100644 index 0000000..be2a027 --- /dev/null +++ b/src/Boundary/Type/DataStructure/Record/Struct.php @@ -0,0 +1,40 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Record; + +use FireHub\Core\Boundary\Type\DataStructure\Record; +use FireHub\Core\Boundary\Capability\Access\KeyAccess; + +/** + * ### Defines the Struct data structure + * + * A Struct represents a fixed-size keyed Record whose elements are identified by integer or string keys. + * + * Each key identifies a distinct component of a single composite value and forms part of the Struct's defined + * structure. The set of keys remains fixed for the lifetime of the Struct. + * + * Unlike a Map, which represents a dynamically changing collection of key-value associations, a Struct represents + * a single structured value with a fixed set of keyed elements. Insertion and removal operations are therefore not + * part of the Struct contract. + * + * Struct elements may contain values of different types, represented collectively by the TValue template type. + * @since 1.0.0 + * + * @template TKey of array-key + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure\Record + * @extends \FireHub\Core\Boundary\Capability\Access\KeyAccess + */ +interface Struct extends Record, KeyAccess {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Record/Tuple.php b/src/Boundary/Type/DataStructure/Record/Tuple.php new file mode 100644 index 0000000..1fe45ae --- /dev/null +++ b/src/Boundary/Type/DataStructure/Record/Tuple.php @@ -0,0 +1,44 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Record; + +use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear; +use FireHub\Core\Boundary\Type\DataStructure\Record; +use FireHub\Core\Boundary\Capability\Access\ { + BoundaryAccess, IndexAccess +}; + +/** + * ### Defines the Tuple data structure + * + * A Tuple represents a fixed-size positional Record whose elements are identified by zero-based integer indexes. + * + * Elements are arranged in a defined linear order, and their positions form part of the Tuple structure. Unlike + * general-purpose Collections, a Tuple represents a single composite value composed of a fixed number of logically + * related elements. + * + * The number and positions of elements remain fixed for the lifetime of the Tuple. This contract does not provide + * capabilities for inserting or removing elements. + * + * Tuple values may be heterogeneous and are represented collectively by the TValue template type. + * @since 1.0.0 + * + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure\Record + * @extends \FireHub\Core\Boundary\Type\DataStructure\Classification\Linear + * @extends \FireHub\Core\Boundary\Capability\Access\BoundaryAccess + * @extends \FireHub\Core\Boundary\Capability\Access\IndexAccess + */ +interface Tuple extends Linear, Record, BoundaryAccess, IndexAccess {} \ No newline at end of file From bc82a19bcf4b5c1151edb715fd54f9426fdb477a Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 17 Sep 2026 15:37:03 +0200 Subject: [PATCH 079/118] Align `Struct` interface semantics with `Unordered` classification **Details:** - Added the `Unordered` interface to the `Struct` contract in `Core-Standard/src/Boundary/Type/DataStructure/Record/Struct.php`, aligning its definition with unordered classification semantics. - Removed the redundant `Linear` inheritance from the `Tuple` interface in `Core-Standard/src/Boundary/Type/DataStructure/Record/Tuple.php` to simplify its type hierarchy. - Enhances the FireHub Core ecosystem by refining structural classifications and ensuring adherence to clear and robust design principles. --- src/Boundary/Type/DataStructure/Record/Struct.php | 3 ++- src/Boundary/Type/DataStructure/Record/Tuple.php | 1 - 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Boundary/Type/DataStructure/Record/Struct.php b/src/Boundary/Type/DataStructure/Record/Struct.php index be2a027..d614b9f 100644 --- a/src/Boundary/Type/DataStructure/Record/Struct.php +++ b/src/Boundary/Type/DataStructure/Record/Struct.php @@ -13,6 +13,7 @@ namespace FireHub\Core\Boundary\Type\DataStructure\Record; +use FireHub\Core\Boundary\Type\DataStructure\Classification\Unordered; use FireHub\Core\Boundary\Type\DataStructure\Record; use FireHub\Core\Boundary\Capability\Access\KeyAccess; @@ -37,4 +38,4 @@ * @extends \FireHub\Core\Boundary\Type\DataStructure\Record * @extends \FireHub\Core\Boundary\Capability\Access\KeyAccess */ -interface Struct extends Record, KeyAccess {} \ No newline at end of file +interface Struct extends Unordered, Record, KeyAccess {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Record/Tuple.php b/src/Boundary/Type/DataStructure/Record/Tuple.php index 1fe45ae..497fe28 100644 --- a/src/Boundary/Type/DataStructure/Record/Tuple.php +++ b/src/Boundary/Type/DataStructure/Record/Tuple.php @@ -37,7 +37,6 @@ * @template TValue * * @extends \FireHub\Core\Boundary\Type\DataStructure\Record - * @extends \FireHub\Core\Boundary\Type\DataStructure\Classification\Linear * @extends \FireHub\Core\Boundary\Capability\Access\BoundaryAccess * @extends \FireHub\Core\Boundary\Capability\Access\IndexAccess */ From 597f192a97d79fd0b452da1b05d1ee22f04631d3 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 17 Sep 2026 15:47:29 +0200 Subject: [PATCH 080/118] Remove redundant `BoundaryAccess` inheritance from `Tuple` interface **Details:** - Eliminated the unnecessary `BoundaryAccess` import and inheritance from the `Tuple` interface in `Core-Standard/src/Boundary/Type/DataStructure/Record/Tuple.php`. - Streamlined the `Tuple` contract to focus solely on `IndexAccess` and other relevant classifications for fixed-size positional records. - Improves clarity and reduces complexity, aligning with FireHub's principles of modularity and precise type definitions. --- src/Boundary/Type/DataStructure/Record/Tuple.php | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/src/Boundary/Type/DataStructure/Record/Tuple.php b/src/Boundary/Type/DataStructure/Record/Tuple.php index 497fe28..32be986 100644 --- a/src/Boundary/Type/DataStructure/Record/Tuple.php +++ b/src/Boundary/Type/DataStructure/Record/Tuple.php @@ -15,9 +15,7 @@ use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear; use FireHub\Core\Boundary\Type\DataStructure\Record; -use FireHub\Core\Boundary\Capability\Access\ { - BoundaryAccess, IndexAccess -}; +use FireHub\Core\Boundary\Capability\Access\IndexAccess; /** * ### Defines the Tuple data structure @@ -37,7 +35,6 @@ * @template TValue * * @extends \FireHub\Core\Boundary\Type\DataStructure\Record - * @extends \FireHub\Core\Boundary\Capability\Access\BoundaryAccess * @extends \FireHub\Core\Boundary\Capability\Access\IndexAccess */ -interface Tuple extends Linear, Record, BoundaryAccess, IndexAccess {} \ No newline at end of file +interface Tuple extends Linear, Record, IndexAccess {} \ No newline at end of file From 6321d9c9a88a70aa44cae184b035096c7b831dc6 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 18 Sep 2026 08:20:08 +0200 Subject: [PATCH 081/118] Add `Metrics` capability to `Record` interface **Details:** - Extended the `Record` interface in `Core-Standard/src/Boundary/Type/DataStructure/Record.php` to include the `Metrics` capability. - Ensures that records can now support metric-related operations, enhancing modularity and functionality in alignment with FireHub's design principles. - Streamlines support for composite data structures with integrated metric capabilities, adhering to modern PHP practices and robust type definitions. --- src/Boundary/Type/DataStructure/Record.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/Boundary/Type/DataStructure/Record.php b/src/Boundary/Type/DataStructure/Record.php index ab4cf3e..dd14808 100644 --- a/src/Boundary/Type/DataStructure/Record.php +++ b/src/Boundary/Type/DataStructure/Record.php @@ -13,6 +13,7 @@ namespace FireHub\Core\Boundary\Type\DataStructure; +use FireHub\Core\Boundary\Capability\Measurement\Metrics; use FireHub\Core\Boundary\Type\ { DataStructure, Enumerable }; @@ -39,4 +40,4 @@ * @extends \FireHub\Core\Boundary\Type\DataStructure * @extends \FireHub\Core\Boundary\Type\Enumerable */ -interface Record extends DataStructure, Enumerable {} \ No newline at end of file +interface Record extends DataStructure, Enumerable, Metrics {} \ No newline at end of file From 6fc2beced746bae8ddd9cb8f0a343dec648e26f1 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 18 Sep 2026 09:38:51 +0200 Subject: [PATCH 082/118] Add `Freezable` and `Thawable` capabilities to support immutable and mutable state transitions **Details:** - Introduced the `Freezable` interface in `Core-Standard/src/Boundary/Capability/Freezable.php` to define a contract for objects that can transition to a frozen (immutable) state. - Includes methods `freeze()` for freezing the instance and `isFrozen()` for checking its state. - Ensures that frozen instances reject all state-modifying operations, adhering to one-way mutability. - Added the `Thawable` interface in `Core-Standard/src/Boundary/Capability/Thawable.php` to allow creating new mutable instances derived from a frozen object. - Includes the method `thaw()` to produce a distinct, modifiable instance without altering the original frozen object. - Enhances the FireHub Core ecosystem's modularity by enabling precise control over object state transitions, aligning with modern PHP practices and FireHub design principles. --- src/Boundary/Capability/Freezable.php | 49 +++++++++++++++++++++++++++ src/Boundary/Capability/Thawable.php | 41 ++++++++++++++++++++++ 2 files changed, 90 insertions(+) create mode 100644 src/Boundary/Capability/Freezable.php create mode 100644 src/Boundary/Capability/Thawable.php diff --git a/src/Boundary/Capability/Freezable.php b/src/Boundary/Capability/Freezable.php new file mode 100644 index 0000000..97bb7cc --- /dev/null +++ b/src/Boundary/Capability/Freezable.php @@ -0,0 +1,49 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability; + +/** + * ### Defines a contract for objects that can transition into a frozen state + * + * A freezable object is initially mutable and may transition into a frozen state using {@see self::freeze()}. + * + * Once frozen, operations that would modify the object's state must no longer be permitted. + * + * Freezing is a one-way state transition. Implementations must not restore mutability to the same instance after it + * has been frozen. + * @since 1.0.0 + */ +interface Freezable { + + /** + * ### Determines whether this instance is frozen + * @since 1.0.0 + * + * @return bool True if this instance is frozen, false otherwise. + */ + public function isFrozen ():bool; + + /** + * ### Freezes this instance + * + * After this operation completes, any operation that would modify the state of this instance must be rejected. + * + * Calling this method on an already frozen instance must have no additional effect. + * @since 1.0.0 + * + * @return $this This instance. + */ + public function freeze ():static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Thawable.php b/src/Boundary/Capability/Thawable.php new file mode 100644 index 0000000..f9a83f4 --- /dev/null +++ b/src/Boundary/Capability/Thawable.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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability; + +/** + * ### Defines a contract for objects that can produce a mutable instance + * + * A thawable object can create a new mutable instance derived from its current state without modifying the original + * instance. + * + * The returned instance represents the same logical state at the time of thawing but may maintain its state + * independently or share the underlying state when the implementation supports copy-on-write semantics. + * @since 1.0.0 + */ +interface Thawable { + + /** + * ### Creates a mutable instance + * + * Creates a new mutable instance derived from the current instance without modifying the state of the current + * instance. + * + * The returned instance must be mutable and distinct from the current instance. + * @since 1.0.0 + * + * @return static A new mutable instance. + */ + public function thaw ():static; + +} \ No newline at end of file From 6661e2ecc3dd4a35c063f793a06a2fb019e69ed0 Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 21 Sep 2026 09:50:33 +0200 Subject: [PATCH 083/118] Add `Filterable` and `Mappable` capabilities for value transformation operations **Details:** - Introduced the `Filterable` interface in `Core-Standard/src/Boundary/Capability/Transformation/Filterable.php` to define a contract for filtering values based on a predicate. - Includes the method `filter(callable $callback): static` for producing structures containing only values that satisfy the specified predicate. - Supports specific execution strategies (eager, lazy, etc.), aligning with FireHub modular design principles. - Added the `Mappable` interface in `Core-Standard/src/Boundary/Capability/Transformation/Mappable.php` to enable value transformation via customizable mapping operations. - Implements the `map(callable $callback): static` method, allowing transformation of each value based on a provided callback. - Enhances the FireHub Core ecosystem by providing robust, extens --- .../Capability/Transformation/Filterable.php | 47 ++++++++++++++++++ .../Capability/Transformation/Mappable.php | 49 +++++++++++++++++++ 2 files changed, 96 insertions(+) create mode 100644 src/Boundary/Capability/Transformation/Filterable.php create mode 100644 src/Boundary/Capability/Transformation/Mappable.php diff --git a/src/Boundary/Capability/Transformation/Filterable.php b/src/Boundary/Capability/Transformation/Filterable.php new file mode 100644 index 0000000..c3a5f17 --- /dev/null +++ b/src/Boundary/Capability/Transformation/Filterable.php @@ -0,0 +1,47 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +/** + * ### Defines value filtering capability + * + * Represents the capability of producing a structure containing only values that satisfy a specified predicate. + * + * Each value is evaluated by the specified callback and retained in the resulting structure when the callback + * evaluates to true. + * + * Implementations determine the concrete type, key semantics, and execution strategy of the resulting structure. + * Filtering may therefore be performed eagerly, lazily, or through another implementation-specific strategy. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface Filterable { + + /** + * ### Filters values + * + * Produces a structure containing only values that satisfy the specified predicate. + * @since 1.0.0 + * + * @param callable(TValue, TKey=):bool $callback

+ * Predicate used to determine whether each value should be retained. + *

+ * + * @return static The resulting structure containing the filtered values. + */ + public function filter (callable $callback):static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/Mappable.php b/src/Boundary/Capability/Transformation/Mappable.php new file mode 100644 index 0000000..a798fa8 --- /dev/null +++ b/src/Boundary/Capability/Transformation/Mappable.php @@ -0,0 +1,49 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +/** + * ### Defines value mapping capability + * + * Represents the capability of transforming the values of a structure using a mapping operation. + * + * Each value is passed to the specified callback and replaced in the resulting structure by the value produced by + * that callback. + * + * Implementations determine the concrete type and execution strategy of the resulting structure. Mapping may + * therefore be performed eagerly, lazily, or through another implementation-specific strategy. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface Mappable { + + /** + * ### Maps values + * + * Applies the specified mapping operation to each value. + * @since 1.0.0 + * + * @template TMapped + * + * @param callable(TValue, TKey=):TMapped $callback

+ * Mapping operation to apply to each value. + *

+ * + * @return static The resulting structure containing the mapped values. + */ + public function map (callable $callback):static; + +} \ No newline at end of file From 88c6818222299038488b12663f6129201ec8552f Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 21 Sep 2026 13:47:19 +0200 Subject: [PATCH 084/118] Refine `Mappable` interface return type for consistent value transformation **Details:** - Updated the `map` method in `Core-Standard/src/Boundary/Capability/Transformation/Mappable.php` to consistently use `TValue` as the return type for mapped values. - Removed the redundant template `TMapped`, simplifying method documentation while preserving functionality. - Ensures clarity and alignment with modern PHP practices and FireHub Core design principles. --- src/Boundary/Capability/Transformation/Mappable.php | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/Boundary/Capability/Transformation/Mappable.php b/src/Boundary/Capability/Transformation/Mappable.php index a798fa8..fefaa17 100644 --- a/src/Boundary/Capability/Transformation/Mappable.php +++ b/src/Boundary/Capability/Transformation/Mappable.php @@ -36,13 +36,11 @@ interface Mappable { * Applies the specified mapping operation to each value. * @since 1.0.0 * - * @template TMapped - * - * @param callable(TValue, TKey=):TMapped $callback

+ * @param callable(TValue, TKey=):TValue $callback

* Mapping operation to apply to each value. *

* - * @return static The resulting structure containing the mapped values. + * @return static The resulting structure containing the mapped values. */ public function map (callable $callback):static; From 8bbc921548ef1ca8e8cb1b54d2ec074910ad0b85 Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 21 Sep 2026 15:09:20 +0200 Subject: [PATCH 085/118] Add `Rejectable` capability for excluding elements based on predicates **Details:** - Introduced the `Rejectable` interface in `Core-Standard/src/Boundary/Capability/Transformation/Rejectable.php` to define a contract for element exclusion based on a predicate. - Includes the method `reject(callable $callback): static` for creating a transformed instance excluding elements that meet the predicate condition. - Extends the `Filterable` interface for consistent transformation capabilities within the FireHub Core ecosystem. - Enhances modularity and streamlines element transformation operations, adhering to modern PHP practices and FireHub design principles. --- .../Capability/Transformation/Rejectable.php | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 src/Boundary/Capability/Transformation/Rejectable.php diff --git a/src/Boundary/Capability/Transformation/Rejectable.php b/src/Boundary/Capability/Transformation/Rejectable.php new file mode 100644 index 0000000..b3aac80 --- /dev/null +++ b/src/Boundary/Capability/Transformation/Rejectable.php @@ -0,0 +1,44 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +/** + * ### Defines rejection capability + * + * Defines the ability to create a transformed instance containing only elements that do not satisfy a given + * predicate. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends \FireHub\Core\Boundary\Capability\Transformation\Filterable + */ +interface Rejectable extends Filterable { + + /** + * ### Rejects elements that satisfy the predicate + * + * Creates a transformed instance excluding elements for which the supplied callback evaluates to true. + * @since 1.0.0 + * + * @param callable(TValue, TKey=):bool $callback

+ * Predicate used to determine which elements should be rejected. + *

+ * + * @return static The transformed instance. + */ + public function reject (callable $callback):static; + +} \ No newline at end of file From 3c089b47d8c7df682ea929eec7ffc21af91db28e Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 25 Sep 2026 10:29:13 +0200 Subject: [PATCH 086/118] Add `Sortable` and `KeySortable` capabilities for data structure ordering **Details:** - Introduced the `Sortable` interface in `Core-Standard/src/Boundary/Capability/Transformation/Sortable.php` to define a contract for sorting values in a data structure. - Includes the method `sortWith(callable $comparator): static` for producing a sorted instance based on a custom comparator. - Ensures non-mutative ordering, returning a new instance while preserving the original. - Added the `KeySortable` interface in `Core-Standard/src/Boundary/Capability/Transformation/KeySortable.php` to enable sorting of entries by keys. - Implements the method `sortKeysWith(callable $comparator): static` for key-based ordering with user-defined comparison logic. - Enhances the FireHub Core ecosystem by supporting flexible and robust sorting strategies for both values and keys, adhering to modern PHP practices and design principles. --- .../Capability/Transformation/KeySortable.php | 48 +++++++++++++++++++ .../Capability/Transformation/Sortable.php | 48 +++++++++++++++++++ 2 files changed, 96 insertions(+) create mode 100644 src/Boundary/Capability/Transformation/KeySortable.php create mode 100644 src/Boundary/Capability/Transformation/Sortable.php diff --git a/src/Boundary/Capability/Transformation/KeySortable.php b/src/Boundary/Capability/Transformation/KeySortable.php new file mode 100644 index 0000000..f6252e0 --- /dev/null +++ b/src/Boundary/Capability/Transformation/KeySortable.php @@ -0,0 +1,48 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +/** + * ### Key sortable capability + * + * Defines a capability for producing an ordered representation of a data structure according to its keys. + * + * Implementations may provide specialized sorting strategies appropriate to their underlying representation, + * including optimized paths for natural ascending and descending key ordering. + * + * Sorting does not mutate the source instance. Instead, a new instance of the same concrete type is returned. + * @since 1.0.0 + * + * @template TKey + */ +interface KeySortable { + + /** + * ### Sorts keys using a comparator + * + * Produces a new instance whose entries are arranged according to the supplied key comparison callback. + * + * The callback must return a value less than zero when the first key should precede the second, zero when both + * keys compare equally, or a value greater than zero when the first key should follow the second. + * @since 1.0.0 + * + * @param callable(TKey, TKey):int<-1, 1> $comparator

+ * Callback used to compare two keys. + *

+ * + * @return static The key-sorted instance. + */ + public function sortKeysWith (callable $comparator):static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/Sortable.php b/src/Boundary/Capability/Transformation/Sortable.php new file mode 100644 index 0000000..0bf212c --- /dev/null +++ b/src/Boundary/Capability/Transformation/Sortable.php @@ -0,0 +1,48 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +/** + * ### Sortable capability + * + * Defines a capability for producing an ordered representation of a data structure. + * + * Implementations may provide specialized sorting strategies appropriate to their underlying representation, + * including optimized paths for natural ascending and descending ordering. + * + * Sorting does not mutate the source instance. Instead, a new instance of the same concrete type is returned. + * @since 1.0.0 + * + * @template TValue + */ +interface Sortable { + + /** + * ### Sorts values using a comparator + * + * Produces a new instance whose values are arranged according to the supplied comparison callback. + * + * The callback must return a value less than zero when the first value should precede the second, zero when both + * values compare equally, or a value greater than zero when the first value should follow the second. + * @since 1.0.0 + * + * @param callable(TValue, TValue):int<-1, 1> $comparator

+ * Callback used to compare two values. + *

+ * + * @return static The sorted instance. + */ + public function sortWith (callable $comparator):static; + +} \ No newline at end of file From 16633d29664ceabd2599220e35540c00191ac3c7 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 25 Sep 2026 12:06:19 +0200 Subject: [PATCH 087/118] Extend `Sortable` and `KeySortable` interfaces with default ordering functionality **Details:** - Added a new `sort(Order $order = Order::ASC): static` method in the `Sortable` interface to support sorting values in a specified order (ascending by default). - Introduced a `sortKeys(Order $order = Order::ASC): static` method in the `KeySortable` interface for sorting keys in a specified order (ascending by default). - Improved documentation in both interfaces to clarify the semantics of default ordering and the preservation of comparison mode consistency. - Enhances the usability and flexibility of sorting capabilities within the FireHub Core ecosystem, adhering to modern PHP practices and robust design principles. --- .../Capability/Transformation/KeySortable.php | 22 ++++++++++++++++--- .../Capability/Transformation/Sortable.php | 22 ++++++++++++++++--- 2 files changed, 38 insertions(+), 6 deletions(-) diff --git a/src/Boundary/Capability/Transformation/KeySortable.php b/src/Boundary/Capability/Transformation/KeySortable.php index f6252e0..30a7885 100644 --- a/src/Boundary/Capability/Transformation/KeySortable.php +++ b/src/Boundary/Capability/Transformation/KeySortable.php @@ -13,13 +13,15 @@ namespace FireHub\Core\Boundary\Capability\Transformation; +use FireHub\Core\Meta\Enum\Order; + /** * ### Key sortable capability * - * Defines a capability for producing an ordered representation of a data structure according to its keys. + * Defines a capability for producing an ordered representation of an instance according to its keys. * - * Implementations may provide specialized sorting strategies appropriate to their underlying representation, - * including optimized paths for natural ascending and descending key ordering. + * Implementations may provide specialized sorting strategies appropriate to their underlying representation while + * preserving the semantics of the requested comparison mode or comparison callback. * * Sorting does not mutate the source instance. Instead, a new instance of the same concrete type is returned. * @since 1.0.0 @@ -28,6 +30,20 @@ */ interface KeySortable { + /** + * ### Sorts keys + * + * Produces a new instance whose keys are arranged according to the specified ordering mode. + * @since 1.0.0 + * + * @param \FireHub\Core\Meta\Enum\Order $order [optional]

+ * Direction in which the keys are ordered. + *

+ * + * @return static The sorted instance. + */ + public function sortKeys (Order $order = Order::ASC):static; + /** * ### Sorts keys using a comparator * diff --git a/src/Boundary/Capability/Transformation/Sortable.php b/src/Boundary/Capability/Transformation/Sortable.php index 0bf212c..3b20d6b 100644 --- a/src/Boundary/Capability/Transformation/Sortable.php +++ b/src/Boundary/Capability/Transformation/Sortable.php @@ -13,13 +13,15 @@ namespace FireHub\Core\Boundary\Capability\Transformation; +use FireHub\Core\Meta\Enum\Order; + /** * ### Sortable capability * - * Defines a capability for producing an ordered representation of a data structure. + * Defines a capability for producing an ordered representation of an instance according to its values. * - * Implementations may provide specialized sorting strategies appropriate to their underlying representation, - * including optimized paths for natural ascending and descending ordering. + * Implementations may provide specialized sorting strategies appropriate to their underlying representation while + * preserving the semantics of the requested comparison mode or comparison callback. * * Sorting does not mutate the source instance. Instead, a new instance of the same concrete type is returned. * @since 1.0.0 @@ -28,6 +30,20 @@ */ interface Sortable { + /** + * ### Sorts values + * + * Produces a new instance whose values are arranged according to the specified ordering mode. + * @since 1.0.0 + * + * @param \FireHub\Core\Meta\Enum\Order $order [optional]

+ * Direction in which the values are ordered. + *

+ * + * @return static The sorted instance. + */ + public function sort (Order $order = Order::ASC):static; + /** * ### Sorts values using a comparator * From 49549aa33189261617835643c9a4cfe9554598ad Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 25 Sep 2026 14:46:05 +0200 Subject: [PATCH 088/118] Extend `Sortable` and `KeySortable` interfaces with custom sorting algorithm support **Details:** - Added support for customizable sorting algorithms in both the `Sortable` and `KeySortable` interfaces. - Updated the `sort` and `sortWith` methods in `Sortable` to accept an optional `SortAlgorithm` parameter. - Extended the `sortKeys` and `sortKeysWith` methods in `KeySortable` to include an optional `SortAlgorithm` parameter. - Introduced a new `SortAlgorithm` interface in `Core-Standard/src/Boundary/Algorithm/Sorting/SortAlgorithm.php`. - Defines a generalized contract for sorting strategies, supporting sequential access and swapping operations with user-defined comparators. - Enhanced sorting features in the FireHub Core ecosystem, allowing developers to choose tailored algorithms and adhere to flexible, reusable design principles. --- .../Algorithm/Sorting/SortAlgorithm.php | 58 +++++++++++++++++++ .../Capability/Transformation/KeySortable.php | 11 +++- .../Capability/Transformation/Sortable.php | 11 +++- 3 files changed, 76 insertions(+), 4 deletions(-) create mode 100644 src/Boundary/Algorithm/Sorting/SortAlgorithm.php diff --git a/src/Boundary/Algorithm/Sorting/SortAlgorithm.php b/src/Boundary/Algorithm/Sorting/SortAlgorithm.php new file mode 100644 index 0000000..ce9e20d --- /dev/null +++ b/src/Boundary/Algorithm/Sorting/SortAlgorithm.php @@ -0,0 +1,58 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Algorithm\Sorting; + +/** + * ### Sorting algorithm + * + * Defines a strategy for ordering elements within an indexed range. + * + * Elements are addressed internally by sequential positions, independently of the keys or indexes used by their + * underlying representation. This allows the algorithm to operate on sequential values, key-value entries, and other + * ordered representations without depending on their storage semantics. + * + * Sorting is performed in place through the supplied access and swap operations. + * @since 1.0.0 + * + * @template TElement + */ +interface SortAlgorithm { + + /** + * ### Sorts elements + * + * Rearranges the specified number of elements according to the supplied comparison callback. + * + * The callback must return a value less than zero when the first element should precede the second, zero when both + * elements compare equally, or a value greater than zero when the first element should follow the second. + * @since 1.0.0 + * + * @param non-negative-int $size

+ * Number of elements to sort. + *

+ * @param callable(non-negative-int):TElement $element

+ * Callback used to retrieve an element by its internal position. + *

+ * @param callable(non-negative-int, non-negative-int):void $swap

+ * Callback used to exchange two elements by their internal positions. + *

+ * @param callable(TElement, TElement):int $comparator

+ * Callback used to compare two elements. + *

+ * + * @return void + */ + public function sort (int $size, callable $element, callable $swap, callable $comparator):void; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/KeySortable.php b/src/Boundary/Capability/Transformation/KeySortable.php index 30a7885..1786ff6 100644 --- a/src/Boundary/Capability/Transformation/KeySortable.php +++ b/src/Boundary/Capability/Transformation/KeySortable.php @@ -13,6 +13,7 @@ namespace FireHub\Core\Boundary\Capability\Transformation; +use FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm; use FireHub\Core\Meta\Enum\Order; /** @@ -39,10 +40,13 @@ interface KeySortable { * @param \FireHub\Core\Meta\Enum\Order $order [optional]

* Direction in which the keys are ordered. *

+ * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm $algorithm

+ * Sorting algorithm to use, or null to use the implementation's default sorting strategy. + *

* * @return static The sorted instance. */ - public function sortKeys (Order $order = Order::ASC):static; + public function sortKeys (Order $order = Order::ASC, ?SortAlgorithm $algorithm = null):static; /** * ### Sorts keys using a comparator @@ -56,9 +60,12 @@ public function sortKeys (Order $order = Order::ASC):static; * @param callable(TKey, TKey):int<-1, 1> $comparator

* Callback used to compare two keys. *

+ * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm $algorithm

+ * Sorting algorithm to use, or null to use the implementation's default sorting strategy. + *

* * @return static The key-sorted instance. */ - public function sortKeysWith (callable $comparator):static; + public function sortKeysWith (callable $comparator, ?SortAlgorithm $algorithm = null):static; } \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/Sortable.php b/src/Boundary/Capability/Transformation/Sortable.php index 3b20d6b..70b8cfa 100644 --- a/src/Boundary/Capability/Transformation/Sortable.php +++ b/src/Boundary/Capability/Transformation/Sortable.php @@ -13,6 +13,7 @@ namespace FireHub\Core\Boundary\Capability\Transformation; +use FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm; use FireHub\Core\Meta\Enum\Order; /** @@ -39,10 +40,13 @@ interface Sortable { * @param \FireHub\Core\Meta\Enum\Order $order [optional]

* Direction in which the values are ordered. *

+ * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm $algorithm

+ * Sorting algorithm to use, or null to use the implementation's default sorting strategy. + *

* * @return static The sorted instance. */ - public function sort (Order $order = Order::ASC):static; + public function sort (Order $order = Order::ASC, ?SortAlgorithm $algorithm = null):static; /** * ### Sorts values using a comparator @@ -56,9 +60,12 @@ public function sort (Order $order = Order::ASC):static; * @param callable(TValue, TValue):int<-1, 1> $comparator

* Callback used to compare two values. *

+ * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm $algorithm

+ * Sorting algorithm to use, or null to use the implementation's default sorting strategy. + *

* * @return static The sorted instance. */ - public function sortWith (callable $comparator):static; + public function sortWith (callable $comparator, ?SortAlgorithm $algorithm = null):static; } \ No newline at end of file From 99c7acc5e99d33f34cedb91f602be6af5c5cf445 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 25 Sep 2026 14:57:06 +0200 Subject: [PATCH 089/118] Extend `SortAlgorithm` interface with element replacement capability **Details:** - Added a new `$set` callback parameter to the `sort` method in the `SortAlgorithm` interface. - Enables element replacement at a specific position during sorting. - Updated method signature in `Core-Standard/src/Boundary/Algorithm/Sorting/SortAlgorithm.php` to include the `$set` callback. - Enhances sorting flexibility by supporting direct element reassignment, aligning with modern PHP practices and the FireHub Core design principles. --- src/Boundary/Algorithm/Sorting/SortAlgorithm.php | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/Boundary/Algorithm/Sorting/SortAlgorithm.php b/src/Boundary/Algorithm/Sorting/SortAlgorithm.php index ce9e20d..f70fb46 100644 --- a/src/Boundary/Algorithm/Sorting/SortAlgorithm.php +++ b/src/Boundary/Algorithm/Sorting/SortAlgorithm.php @@ -44,6 +44,9 @@ interface SortAlgorithm { * @param callable(non-negative-int):TElement $element

* Callback used to retrieve an element by its internal position. *

+ * @param callable(non-negative-int, TElement):void $set

+ * Callback used to replace an element at its sequential position. + *

* @param callable(non-negative-int, non-negative-int):void $swap

* Callback used to exchange two elements by their internal positions. *

@@ -53,6 +56,6 @@ interface SortAlgorithm { * * @return void */ - public function sort (int $size, callable $element, callable $swap, callable $comparator):void; + public function sort (int $size, callable $element, callable $set, callable $swap, callable $comparator):void; } \ No newline at end of file From 3a0e2f555e1d0e9e405318612553fba10b9090dd Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 28 Sep 2026 10:40:33 +0200 Subject: [PATCH 090/118] Add `DistributionSortable` and `DistributionSortAlgorithm` capabilities for distribution-based ordering **Details:** - Introduced the `DistributionSortable` interface in `Core-Standard/src/Boundary/Capability/Transformation/DistributionSortable.php` to define a contract for sorting values using distribution sorting algorithms. - Includes the method `distributionSort(DistributionSortAlgorithm $algorithm, callable $key): static` for ordering values based on extracted integer distribution keys. - Supports non-comparison-based sorting, leveraging custom implementation flexibility for value access, reordering, and storage. - Added the `DistributionSortAlgorithm` interface in `Core-Standard/src/Boundary/Algorithm/Sorting/DistributionSortAlgorithm.php` to standardize distribution sorting strategies. - Provides the method `sort(int $size, callable $element, callable $set, callable $key): void` for element distribution based on integer keys derived from their values. - Enhances modularity, allowing algorithms to define specific distribution methods with support for range and format requirements. - Expands the FireHub Core ecosystem's sorting capabilities beyond comparison-driven approaches, adhering to efficient, reusable design principles. --- .../Sorting/DistributionSortAlgorithm.php | 57 +++++++++++++++++++ .../Transformation/DistributionSortable.php | 53 +++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 src/Boundary/Algorithm/Sorting/DistributionSortAlgorithm.php create mode 100644 src/Boundary/Capability/Transformation/DistributionSortable.php diff --git a/src/Boundary/Algorithm/Sorting/DistributionSortAlgorithm.php b/src/Boundary/Algorithm/Sorting/DistributionSortAlgorithm.php new file mode 100644 index 0000000..3d82b7e --- /dev/null +++ b/src/Boundary/Algorithm/Sorting/DistributionSortAlgorithm.php @@ -0,0 +1,57 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Algorithm\Sorting; + +/** + * ### Defines a distribution sorting algorithm + * + * Defines the contract for non-comparison sorting algorithms that distribute elements according to integer keys + * extracted from their values. + * + * Unlike comparison-based sorting algorithms, distribution sorting algorithms do not determine ordering by repeatedly + * comparing pairs of elements. Instead, they use the structure of the extracted integer keys to distribute elements + * into their resulting order. + * + * Implementations may impose additional requirements on the extracted keys, such as restrictions on the supported + * key range, representation, or distribution. + * @since 1.0.0 + * + * @template TElement + */ +interface DistributionSortAlgorithm { + + /** + * ### Sorts elements + * + * Sorts elements addressed by sequential positions according to integer keys extracted from their values. + * @since 1.0.0 + * + * @param non-negative-int $size

+ * Number of elements to sort. + *

+ * @param callable(non-negative-int):TElement $element

+ * Callback used to retrieve an element by its sequential position. + *

+ * @param callable(non-negative-int, TElement):void $set

+ * Callback used to replace an element at its sequential position. + *

+ * @param callable(TElement):int $key

+ * Callback used to extract the integer distribution key from an element. + *

+ * + * @return void + */ + public function sort (int $size, callable $element, callable $set, callable $key):void; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/DistributionSortable.php b/src/Boundary/Capability/Transformation/DistributionSortable.php new file mode 100644 index 0000000..b1a0a32 --- /dev/null +++ b/src/Boundary/Capability/Transformation/DistributionSortable.php @@ -0,0 +1,53 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +use FireHub\Core\Boundary\Algorithm\Sorting\DistributionSortAlgorithm; + +/** + * ### Defines distribution sorting capability + * + * Defines the capability for producing a representation whose values are ordered using a distribution sorting + * algorithm. + * + * Unlike comparison-based sorting, distribution sorting derives ordering from integer keys extracted from individual + * values rather than by comparing pairs of values. + * + * Implementations determine how values are accessed, reordered, and stored while the supplied algorithm determines + * the distribution strategy used to establish their resulting order. + * @since 1.0.0 + * + * @template TValue + */ +interface DistributionSortable { + + /** + * ### Sorts values using a distribution sorting algorithm + * + * Produces a representation whose values are ordered according to integer keys extracted from each value by the + * supplied key extractor. + * @since 1.0.0 + * + * @param \FireHub\Core\Boundary\Algorithm\Sorting\DistributionSortAlgorithm $algorithm

+ * Distribution sorting algorithm used to order the values. + *

+ * @param callable(TValue):int $key

+ * Callback used to extract the integer distribution key from each value. + *

+ * + * @return static Sorted representation. + */ + public function distributionSort (DistributionSortAlgorithm $algorithm, callable $key):static; + +} \ No newline at end of file From 7df6942b4d3f2067cd295efeb9400fb55afa9ea7 Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 28 Sep 2026 12:30:05 +0200 Subject: [PATCH 091/118] Refine `DistributionSortable` and `DistributionSortAlgorithm` for enhanced numeric key support **Details:** - Updated `DistributionSortable::distributionSort` method to support key extractors returning `int|float` types, improving flexibility for distribution-based sorting operations. - Adjusted documentation in `DistributionSortable` and `DistributionSortAlgorithm` to reflect support for numeric keys, replacing references to integer-only keys with `int|float` where applicable. - Added a new `TKey` template in `DistributionSortAlgorithm` and updated the `sort` method's `$key` callback to accommodate numeric key types. - Enhances sorting versatility by broadening support for numeric distribution keys, adhering to FireHub's commitment to reusable and flexible design principles. --- .../Sorting/DistributionSortAlgorithm.php | 14 ++++++-------- .../Transformation/DistributionSortable.php | 4 +++- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/Boundary/Algorithm/Sorting/DistributionSortAlgorithm.php b/src/Boundary/Algorithm/Sorting/DistributionSortAlgorithm.php index 3d82b7e..f2afdbd 100644 --- a/src/Boundary/Algorithm/Sorting/DistributionSortAlgorithm.php +++ b/src/Boundary/Algorithm/Sorting/DistributionSortAlgorithm.php @@ -14,20 +14,18 @@ namespace FireHub\Core\Boundary\Algorithm\Sorting; /** - * ### Defines a distribution sorting algorithm + * ### Defines a distribution sorting algorithm * - * Defines the contract for non-comparison sorting algorithms that distribute elements according to integer keys + * Defines the contract for non-comparison sorting algorithms that distribute elements according to numeric keys * extracted from their values. * * Unlike comparison-based sorting algorithms, distribution sorting algorithms do not determine ordering by repeatedly - * comparing pairs of elements. Instead, they use the structure of the extracted integer keys to distribute elements - * into their resulting order. - * - * Implementations may impose additional requirements on the extracted keys, such as restrictions on the supported - * key range, representation, or distribution. + * comparing pairs of elements. Instead, they use the structure or distribution of extracted numeric keys to place + * elements into their resulting order. * @since 1.0.0 * * @template TElement + * @template TKey of int|float */ interface DistributionSortAlgorithm { @@ -46,7 +44,7 @@ interface DistributionSortAlgorithm { * @param callable(non-negative-int, TElement):void $set

* Callback used to replace an element at its sequential position. *

- * @param callable(TElement):int $key

+ * @param callable(TElement):TKey $key

* Callback used to extract the integer distribution key from an element. *

* diff --git a/src/Boundary/Capability/Transformation/DistributionSortable.php b/src/Boundary/Capability/Transformation/DistributionSortable.php index b1a0a32..4c6ac6d 100644 --- a/src/Boundary/Capability/Transformation/DistributionSortable.php +++ b/src/Boundary/Capability/Transformation/DistributionSortable.php @@ -39,7 +39,9 @@ interface DistributionSortable { * supplied key extractor. * @since 1.0.0 * - * @param \FireHub\Core\Boundary\Algorithm\Sorting\DistributionSortAlgorithm $algorithm

+ * @template TKey of int|float + * + * @param \FireHub\Core\Boundary\Algorithm\Sorting\DistributionSortAlgorithm $algorithm

* Distribution sorting algorithm used to order the values. *

* @param callable(TValue):int $key

From 935aa9ee6f3e406dea258d55482d0e831f44e30d Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 28 Sep 2026 15:25:39 +0200 Subject: [PATCH 092/118] Mark `$algorithm` parameter as `[optional]` in `Sortable` and `KeySortable` interfaces **Details:** - Updated the PHPDoc in `sort` and `sortWith` methods of `Sortable` to clarify that the `$algorithm` parameter is optional. - Modified the PHPDoc in `sortKeys` and `sortKeysWith` methods of `KeySortable` to similarly indicate the `$algorithm` parameter as optional. - Improves documentation accuracy for developers utilizing custom sorting algorithms, ensuring better alignment with the intended design. --- src/Boundary/Capability/Transformation/KeySortable.php | 4 ++-- src/Boundary/Capability/Transformation/Sortable.php | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/Boundary/Capability/Transformation/KeySortable.php b/src/Boundary/Capability/Transformation/KeySortable.php index 1786ff6..626bcc9 100644 --- a/src/Boundary/Capability/Transformation/KeySortable.php +++ b/src/Boundary/Capability/Transformation/KeySortable.php @@ -40,7 +40,7 @@ interface KeySortable { * @param \FireHub\Core\Meta\Enum\Order $order [optional]

* Direction in which the keys are ordered. *

- * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm $algorithm

+ * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm $algorithm [optional]

* Sorting algorithm to use, or null to use the implementation's default sorting strategy. *

* @@ -60,7 +60,7 @@ public function sortKeys (Order $order = Order::ASC, ?SortAlgorithm $algorithm = * @param callable(TKey, TKey):int<-1, 1> $comparator

* Callback used to compare two keys. *

- * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm $algorithm

+ * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm $algorithm [optional]

* Sorting algorithm to use, or null to use the implementation's default sorting strategy. *

* diff --git a/src/Boundary/Capability/Transformation/Sortable.php b/src/Boundary/Capability/Transformation/Sortable.php index 70b8cfa..5bb7632 100644 --- a/src/Boundary/Capability/Transformation/Sortable.php +++ b/src/Boundary/Capability/Transformation/Sortable.php @@ -40,7 +40,7 @@ interface Sortable { * @param \FireHub\Core\Meta\Enum\Order $order [optional]

* Direction in which the values are ordered. *

- * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm $algorithm

+ * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm $algorithm [optional]

* Sorting algorithm to use, or null to use the implementation's default sorting strategy. *

* @@ -60,7 +60,7 @@ public function sort (Order $order = Order::ASC, ?SortAlgorithm $algorithm = nul * @param callable(TValue, TValue):int<-1, 1> $comparator

* Callback used to compare two values. *

- * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm $algorithm

+ * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm $algorithm [optional]

* Sorting algorithm to use, or null to use the implementation's default sorting strategy. *

* From 623b3fbac5510e2cc3d0ec8c7cf7abbe637aa3ec Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 29 Sep 2026 08:41:15 +0200 Subject: [PATCH 093/118] Update `NativeRuntime` class to require PHP 8.2 and use `readonly` **Details:** - Updated the required PHP version in the class-level PHPDoc to `>=8.2` to align with modern PHP features. - Changed the `NativeRuntime` class to `readonly`, ensuring immutability for its properties. - Enhances compatibility with PHP 8.2 features and promotes safer class design practices. --- src/Boundary/Runtime/NativeRuntime.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Boundary/Runtime/NativeRuntime.php b/src/Boundary/Runtime/NativeRuntime.php index bdb68bc..f1ab87f 100644 --- a/src/Boundary/Runtime/NativeRuntime.php +++ b/src/Boundary/Runtime/NativeRuntime.php @@ -7,7 +7,7 @@ * @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.0 + * @php-version >=8.2 * @package Core */ @@ -26,7 +26,7 @@ * * @since 1.0.0 */ -abstract class NativeRuntime { +abstract readonly class NativeRuntime { /** * ### Prevent instantiation of this class From a4f36c2c251c52220c9f6971d6f974fc0811eba6 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 29 Sep 2026 15:32:02 +0200 Subject: [PATCH 094/118] Add `start` and `end` methods to `Period` for temporal boundary access **Details:** - Introduced an abstract `start` method to retrieve the start of the period as a `DateTime` object. - Added an abstract `end` method to retrieve the end of the period as a `DateTime` object. - Enhances the `Period` class with explicit boundary accessors, simplifying period manipulation and ensuring consistency with temporal data handling practices. --- src/Type/Temporal/Period.php | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/Type/Temporal/Period.php b/src/Type/Temporal/Period.php index 2bc533c..12901e1 100644 --- a/src/Type/Temporal/Period.php +++ b/src/Type/Temporal/Period.php @@ -34,6 +34,22 @@ */ abstract readonly class Period extends ValueObject implements Stringable { + /** + * ### Gets the start of the period + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Temporal\DateTime The start of the period. + */ + abstract public function start ():DateTime; + + /** + * ### Gets the end of the period + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Temporal\DateTime The end of the period. + */ + abstract public function end ():DateTime; + /** * ### Returns the duration of the period * @since 1.0.0 From aaa17cdf46d76176cbad31c02d36a70032715200 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 29 Sep 2026 15:45:15 +0200 Subject: [PATCH 095/118] "Add InvalidIntervalTimespanException and update Interval with Enumerable interface Introduced `InvalidIntervalTimespanException` class to handle cases of invalid interval timespans. Updated the `Interval` abstract class to implement the `Enumerable` interface and refined its type template for improved type safety and extensibility." --- src/Type/Temporal/Interval.php | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/Type/Temporal/Interval.php b/src/Type/Temporal/Interval.php index 53f9682..ed4f350 100644 --- a/src/Type/Temporal/Interval.php +++ b/src/Type/Temporal/Interval.php @@ -13,6 +13,7 @@ namespace FireHub\Core\Type\Temporal; +use FireHub\Core\Boundary\Type\Enumerable; use FireHub\Core\Type\ValueObject; /** @@ -27,11 +28,12 @@ * belong to higher-level layers such as Foundation. * @since 1.0.0 * - * @template TValue of array + * @template TValue of array{period: non-empty-string, timespan: numeric-string, start_inclusive: bool, end_inclusive: bool} * * @extends \FireHub\Core\Type\ValueObject + * @implements \FireHub\Core\Boundary\Type\Enumerable> */ -abstract readonly class Interval extends ValueObject { +abstract readonly class Interval extends ValueObject implements Enumerable { /** * @inheritDoc From 32cd0ea6b7e83b436688bd0273ff5fcf0c279499 Mon Sep 17 00:00:00 2001 From: Riddick Date: Wed, 30 Sep 2026 15:40:10 +0200 Subject: [PATCH 096/118] Add `Concatenable` and `Mergeable` interfaces for transformation capabilities **Details:** - Introduced the `Concatenable` interface in `Core-Standard/src/Boundary/Capability/Transformation/Concatenable.php`: - Defines the `concat(iterable $values): static` method for creating a new instance containing concatenated values while preserving iteration order. - Enhances the ecosystem with support for non-mutative concatenation of data structures. - Added the `Mergeable` interface in `Core-Standard/src/Boundary/Capability/Transformation/Mergeable.php`: - Defines the `merge(iterable $values): static` method for producing a new instance containing merged key-value associations, replacing conflicting keys with values from the provided source. - Promotes flexibility and --- .../Transformation/Concatenable.php | 42 ++++++++++++++++ .../Capability/Transformation/Mergeable.php | 49 +++++++++++++++++++ 2 files changed, 91 insertions(+) create mode 100644 src/Boundary/Capability/Transformation/Concatenable.php create mode 100644 src/Boundary/Capability/Transformation/Mergeable.php diff --git a/src/Boundary/Capability/Transformation/Concatenable.php b/src/Boundary/Capability/Transformation/Concatenable.php new file mode 100644 index 0000000..a889a72 --- /dev/null +++ b/src/Boundary/Capability/Transformation/Concatenable.php @@ -0,0 +1,42 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +/** + * ### Defines concatenation capability + * + * Defines the capability for producing a structure containing the values of the current structure followed by the + * values provided by another iterable source. + * @since 1.0.0 + * + * @template TValue + */ +interface Concatenable { + + /** + * ### Concatenates values + * + * Creates a new instance containing the values of the current structure followed by the specified values while + * preserving their iteration order. + * @since 1.0.0 + * + * @param iterable $values

+ * The values to concatenate. + *

+ * + * @return static A new instance containing the concatenated values. + */ + public function concat (iterable $values):static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/Mergeable.php b/src/Boundary/Capability/Transformation/Mergeable.php new file mode 100644 index 0000000..8bbdebf --- /dev/null +++ b/src/Boundary/Capability/Transformation/Mergeable.php @@ -0,0 +1,49 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +/** + * ### Defines merging capability + * + * Defines the capability for producing a new instance containing the key-value associations of the current + * structure merged with the key-value associations provided by another iterable source. + * + * When the provided source contains a key that already exists within the current structure, the value from the + * provided source replaces the existing value. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface Mergeable { + + /** + * ### Merges key-value associations + * + * Creates a new instance containing the key-value associations of the current structure together with the + * associations provided by the specified iterable source. + * + * Existing associations whose keys are also present in the provided source are replaced by the corresponding + * values from that source. + * @since 1.0.0 + * + * @param iterable $values

+ * The key-value associations to merge. + *

+ * + * @return static A new instance containing the merged key-value associations. + */ + public function merge (iterable $values):static; + +} \ No newline at end of file From 757755eb6f9f215f4c7bc98261da822d21e9fb43 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 1 Oct 2026 13:56:38 +0200 Subject: [PATCH 097/118] Add `KeyMappable` interface for key transformation capabilities **Details:** - Introduced the `KeyMappable` interface in `Core-Standard/src/Boundary/Capability/Transformation/KeyMappable.php`: - Defines the method `mapKeys(callable $callback): static` for transforming keys of a data structure while preserving associated values. - Supports handling of key collisions when transforming multiple keys into a single key. - Enhances the FireHub Core ecosystem with flexible, reusable design for key mapping transformations, promoting non-mutative operations and adherence to modern PHP standards. --- .../Capability/Transformation/KeyMappable.php | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 src/Boundary/Capability/Transformation/KeyMappable.php diff --git a/src/Boundary/Capability/Transformation/KeyMappable.php b/src/Boundary/Capability/Transformation/KeyMappable.php new file mode 100644 index 0000000..43a5474 --- /dev/null +++ b/src/Boundary/Capability/Transformation/KeyMappable.php @@ -0,0 +1,45 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +/** + * ### Defines key mapping transformation + * + * Key mapping provides the ability to transform the keys of a data structure while preserving their associated + * values. + * + * Implementations define how collisions are handled when multiple keys are transformed into the same key. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface KeyMappable { + + /** + * ### Maps keys using the specified callback + * + * Creates a transformed representation by applying the specified callback to each key while preserving the + * value associated with that key. + * @since 1.0.0 + * + * @param callable(TKey, TValue=):TKey $callback

+ * Callback used to transform each key. + *

+ * + * @return static The resulting structure containing the mapped keys. + */ + public function mapKeys (callable $callback):static; + +} \ No newline at end of file From f5ade29fb9bf6b8f2442eba994115528cf8eabcb Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 1 Oct 2026 15:15:01 +0200 Subject: [PATCH 098/118] Add `IndexReplacement` and `KeyReplacement` interfaces for mutation capabilities **Details:** - Introduced the `IndexReplacement` interface in `Core-Standard/src/Boundary/Capability/Mutation/IndexReplacement.php`: - Defines the `replace(int $index, mixed $value): MutationOutcome` method for replacing values at specific integer indices without altering the data structure. - Ensures compliance with non-creation and non-removal constraints by preserving the structure and reporting `NOT_FOUND` for invalid indices. - Added the `KeyReplacement` interface in `Core-Standard/src/Boundary/Capability/Mutation/KeyReplacement.php`: - Implements the `replace(mixed $key, mixed $value): MutationOutcome` method for updating values associated with a key while maintaining the keyed structure. - Guards against key creation or removal and returns `NOT_FOUND` for nonexistent keys. - Enhances the FireHub Core ecosystem by introducing standardized mutation interfaces for index-based and key-based replacement, adhering to modern PHP design principles and ensuring extensibility. --- .../Capability/Mutation/IndexReplacement.php | 51 ++++++++++++++++++ .../Capability/Mutation/KeyReplacement.php | 52 +++++++++++++++++++ 2 files changed, 103 insertions(+) create mode 100644 src/Boundary/Capability/Mutation/IndexReplacement.php create mode 100644 src/Boundary/Capability/Mutation/KeyReplacement.php diff --git a/src/Boundary/Capability/Mutation/IndexReplacement.php b/src/Boundary/Capability/Mutation/IndexReplacement.php new file mode 100644 index 0000000..d905903 --- /dev/null +++ b/src/Boundary/Capability/Mutation/IndexReplacement.php @@ -0,0 +1,51 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Meta\Enum\MutationOutcome; + +/** + * ### Defines indexed replacement of values + * + * Indexed replacement provides the ability to replace an existing value identified by an integer index without + * changing the structure in which the value is stored. + * + * The capability does not permit creation or removal of indexed values. Implementations preserve their existing + * indexed structure and report NOT_FOUND when the specified index does not exist. + * @since 1.0.0 + * + * @template TValue + */ +interface IndexReplacement { + + /** + * ### Replaces the value at the specified index + * + * Replaces the existing value associated with the specified index without creating a new index or otherwise + * changing the indexed structure. + * @since 1.0.0 + * + * @param int $index

+ * The index whose value should be replaced. + *

+ * @param TValue $value

+ * The replacement value. + *

+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the replacement: UPDATED if the value was + * replaced, or NOT_FOUND if the index does not exist. + */ + public function replace (int $index, mixed $value):MutationOutcome; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/KeyReplacement.php b/src/Boundary/Capability/Mutation/KeyReplacement.php new file mode 100644 index 0000000..39af173 --- /dev/null +++ b/src/Boundary/Capability/Mutation/KeyReplacement.php @@ -0,0 +1,52 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Meta\Enum\MutationOutcome; + +/** + * ### Defines key-based replacement of values + * + * Key replacement provides the ability to replace an existing value identified by its key without changing the + * keyed structure in which the value is stored. + * + * The capability does not permit creation or removal of keyed values. Implementations preserve their existing set + * of keys and report NOT_FOUND when the specified key does not exist. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface KeyReplacement { + + /** + * ### Replaces the value associated with the specified key + * + * Replaces the existing value associated with the specified key without creating a new key or otherwise + * changing the keyed structure. + * @since 1.0.0 + * + * @param TKey $key

+ * The key whose associated value should be replaced. + *

+ * @param TValue $value

+ * The replacement value. + *

+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the replacement: UPDATED if the value was + * replaced, or NOT_FOUND if the key does not exist. + */ + public function replace (mixed $key, mixed $value):MutationOutcome; + +} \ No newline at end of file From ab71354e70e57205177ebb4781334fe37e8e9b2a Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 2 Oct 2026 09:56:14 +0200 Subject: [PATCH 099/118] Add `RandomSelectable` interface for random value selection capabilities **Details:** - Introduced the `RandomSelectable` interface in `Core-Standard/src/Boundary/Capability/Query/RandomSelectable.php`: - Defines the `random(): Maybe` method to select a single random value without modifying the data structure. - Adds the `sample(int $size): static` method to select a random sample of values, ensuring values are selected without replacement. - Updated PHPDoc for precision in method descriptions. - Refined documentation in the `KeyMappable` interface, revising language for clarity and conciseness. - Enhances the FireHub Core ecosystem with standardized random selection capabilities and improved documentation for key transformation operations. --- .../Capability/Query/RandomSelectable.php | 59 +++++++++++++++++++ .../Capability/Transformation/KeyMappable.php | 2 +- 2 files changed, 60 insertions(+), 1 deletion(-) create mode 100644 src/Boundary/Capability/Query/RandomSelectable.php diff --git a/src/Boundary/Capability/Query/RandomSelectable.php b/src/Boundary/Capability/Query/RandomSelectable.php new file mode 100644 index 0000000..3701e65 --- /dev/null +++ b/src/Boundary/Capability/Query/RandomSelectable.php @@ -0,0 +1,59 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Query; + +use FireHub\Core\Type\Maybe; + +/** + * ### Defines random selection of values + * + * Random selection provides the ability to select one or more values from a data structure without modifying its + * contents. + * + * Implementations determine how randomness is produced and how values participate in selection according to the + * semantics of the implementing data structure. + * @since 1.0.0 + * + * @template TValue + */ +interface RandomSelectable { + + /** + * ### Selects a random value + * + * Selects and returns one randomly chosen value from the data structure without modifying its contents. + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Maybe The selected value, or none if no value can be selected. + */ + public function random ():Maybe; + + /** + * ### Selects a random sample + * + * Selects up to the specified number of randomly chosen values from the data structure without modifying its + * contents. + * + * Values are selected without replacement, so the same selectable element is not selected more than once. + * @since 1.0.0 + * + * @param non-negative-int $size

+ * The maximum number of values to select. + *

+ * + * @return static A structure containing the randomly selected values. + */ + public function sample (int $size):static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/KeyMappable.php b/src/Boundary/Capability/Transformation/KeyMappable.php index 43a5474..8e4aa66 100644 --- a/src/Boundary/Capability/Transformation/KeyMappable.php +++ b/src/Boundary/Capability/Transformation/KeyMappable.php @@ -16,7 +16,7 @@ /** * ### Defines key mapping transformation * - * Key mapping provides the ability to transform the keys of a data structure while preserving their associated + * Key mapping provides the ability to transform the keys of a structure while preserving their associated * values. * * Implementations define how collisions are handled when multiple keys are transformed into the same key. From c593480f8becfe77a0f1d8a1e76399857ac3bf8d Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 2 Oct 2026 10:03:19 +0200 Subject: [PATCH 100/118] Expand return type in `RandomSelectable::random` for mixed value support **Details:** - Updated the PHPDoc of the `random` method in the `RandomSelectable` interface to include `mixed` in the return type: `Maybe`. - Enhances flexibility by allowing the method to accommodate a broader range of value types, improving compatibility across use cases. - Aligns with FireHub Core's commitment to robust and reusable interface design. --- src/Boundary/Capability/Query/RandomSelectable.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Boundary/Capability/Query/RandomSelectable.php b/src/Boundary/Capability/Query/RandomSelectable.php index 3701e65..e8bb1d8 100644 --- a/src/Boundary/Capability/Query/RandomSelectable.php +++ b/src/Boundary/Capability/Query/RandomSelectable.php @@ -35,7 +35,7 @@ interface RandomSelectable { * Selects and returns one randomly chosen value from the data structure without modifying its contents. * @since 1.0.0 * - * @return \FireHub\Core\Type\Maybe The selected value, or none if no value can be selected. + * @return \FireHub\Core\Type\Maybe The selected value, or none if no value can be selected. */ public function random ():Maybe; From e3ed304ded4e0b0d20530db0d1a69e31de3ae94b Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 2 Oct 2026 13:34:26 +0200 Subject: [PATCH 101/118] Add `Entry` value object for key-value pair representation **Details:** - Introduced the `Entry` class in `Core-Standard/src/Type/DataStructure/Map/Entry.php`: - Represents immutable key-value associations as standalone value objects. - Includes a strongly typed `value()` method returning an array with `key` and `value`. - Enhances the FireHub Core ecosystem with a dedicated, reusable abstraction for key-value pairs, promoting immutability and robust design practices. --- src/Type/DataStructure/Map/Entry.php | 70 ++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 src/Type/DataStructure/Map/Entry.php diff --git a/src/Type/DataStructure/Map/Entry.php b/src/Type/DataStructure/Map/Entry.php new file mode 100644 index 0000000..0c83e6a --- /dev/null +++ b/src/Type/DataStructure/Map/Entry.php @@ -0,0 +1,70 @@ + + * @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\DataStructure\Map; + +use FireHub\Core\Type\ValueObject; + +/** + * ### Map entry + * + * Represents an immutable key-value entry belonging to a map. + * + * A map entry groups a key together with its associated value and represents that association as a single value + * object. It provides a strongly typed representation of an individual map entry when the key and value need to be + * passed, returned, or otherwise handled together. + * + * The entry does not provide map storage or lookup behavior and does not maintain any relationship with the map from + * which it originated. It represents only the key-value association itself. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends ValueObject + */ +final readonly class Entry extends ValueObject { + + /** + * ### Constructor + * @since 1.0.0 + * + * @param TKey $key

+ * The entry key. + *

+ * @param TValue $value

+ * The entry value. + *

+ * + * @return void + */ + public function __construct ( + public mixed $key, + public mixed $value + ) {} + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():array { + + return [ + 'key' => $this->key, + 'value' => $this->value + ]; + + } + +} \ No newline at end of file From 09a09853a3af9498a86297857449e81a3aa9f349 Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 5 Oct 2026 10:07:00 +0200 Subject: [PATCH 102/118] Add `Hierarchical` and `Tree` interfaces for hierarchical data structure classification **Details:** - Introduced the `Hierarchical` interface in `Core-Standard/src/Boundary/Type/DataStructure/Classification/Hierarchical.php`: - Defines a classification for data structures organized hierarchically through parent-child relationships. - Focuses on organizational topology without imposing constraints on representation, traversal, or storage. - Added the `Tree` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Tree.php`: - Implements `Hierarchical` and extends the `Collection` interface. - Defines the structure of a tree as a hierarchical, acyclic collection, organizing elements with a single root, parent-child relationships, and leaf nodes for elements without children. - Does not prescribe branching factors, traversal strategies, balancing, or mutation behaviors. - Enhances the FireHub Core ecosystem with flexible, reusable abstractions for hierarchical data structures, promoting extensibility and robust design practices. --- .../Classification/Hierarchical.php | 26 ++++++++++++ .../Type/DataStructure/Collection/Tree.php | 40 +++++++++++++++++++ 2 files changed, 66 insertions(+) create mode 100644 src/Boundary/Type/DataStructure/Classification/Hierarchical.php create mode 100644 src/Boundary/Type/DataStructure/Collection/Tree.php diff --git a/src/Boundary/Type/DataStructure/Classification/Hierarchical.php b/src/Boundary/Type/DataStructure/Classification/Hierarchical.php new file mode 100644 index 0000000..cf0ffa6 --- /dev/null +++ b/src/Boundary/Type/DataStructure/Classification/Hierarchical.php @@ -0,0 +1,26 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Classification; + +/** + * ### Identifies a data structure whose values are organized hierarchically + * + * A hierarchical data structure organizes values through parent-child relationships, forming one or more levels of + * structural descent. + * + * This classification describes organizational topology and does not prescribe node representation, branching + * constraints, traversal strategy, ordering, balancing, or storage implementation. + * @since 1.0.0 + */ +interface Hierarchical {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Tree.php b/src/Boundary/Type/DataStructure/Collection/Tree.php new file mode 100644 index 0000000..ee281c3 --- /dev/null +++ b/src/Boundary/Type/DataStructure/Collection/Tree.php @@ -0,0 +1,40 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Collection; + +use FireHub\Core\Boundary\Type\DataStructure\Classification\Hierarchical; +use FireHub\Core\Boundary\Type\DataStructure\Collection; + +/** + * ### Defines a tree data structure + * + * A tree is a hierarchical collection whose elements are organized through parent-child relationships around a + * single root. + * + * Each element, except the root, has exactly one parent and may have zero or more children. Elements without + * children are the leaves. The structure is acyclic and every element is reachable from the root. + * + * This contract defines the structural identity of a tree without prescribing branching constraints, traversal + * order, node representation, mutation behavior, balancing rules, ordering semantics, or storage implementation. + * + * Specialized tree structures may impose additional invariants such as a fixed branching factor, value ordering, + * balancing, or search semantics. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + */ +interface Tree extends Hierarchical, Collection {} \ No newline at end of file From 69ae54aa0cac6306b40bf4a97a2318f491365789 Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 5 Oct 2026 13:16:17 +0200 Subject: [PATCH 103/118] Add hierarchical capabilities and tree-related abstractions **Details:** - Introduced hierarchical interface capabilities in the `Core-Standard` module. - Added the following interfaces for flexible and reusable data structure design: - `AncestorIteration` and `DescendantIteration` for traversing hierarchical structures. - `RootAccess` and `ChildAccess` for accessing key structural elements. - `Depth` and --- .../Capability/Access/ChildAccess.php | 44 +++++++ src/Boundary/Capability/Access/RootAccess.php | 41 +++++++ src/Boundary/Capability/AncestorIteration.php | 44 +++++++ .../Capability/DescendantIteration.php | 44 +++++++ src/Boundary/Capability/Measurement/Depth.php | 37 ++++++ .../Capability/Measurement/Height.php | 37 ++++++ .../Type/DataStructure/Collection/Tree.php | 10 +- .../DataStructure/Collection/Tree/Node.php | 116 ++++++++++++++++++ 8 files changed, 372 insertions(+), 1 deletion(-) create mode 100644 src/Boundary/Capability/Access/ChildAccess.php create mode 100644 src/Boundary/Capability/Access/RootAccess.php create mode 100644 src/Boundary/Capability/AncestorIteration.php create mode 100644 src/Boundary/Capability/DescendantIteration.php create mode 100644 src/Boundary/Capability/Measurement/Depth.php create mode 100644 src/Boundary/Capability/Measurement/Height.php create mode 100644 src/Boundary/Type/DataStructure/Collection/Tree/Node.php diff --git a/src/Boundary/Capability/Access/ChildAccess.php b/src/Boundary/Capability/Access/ChildAccess.php new file mode 100644 index 0000000..49e0b49 --- /dev/null +++ b/src/Boundary/Capability/Access/ChildAccess.php @@ -0,0 +1,44 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Access; + +use FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node; + +/** + * ### Defines access to child elements + * + * Provides access to the direct children of an element within a hierarchical structure. + * + * This capability exposes only immediate children. Descendants below the first child level are not included. + * @since 1.0.0 + * + * @template TValue + */ +interface ChildAccess { + + /** + * ### Gets the children + * + * Returns the direct children of the specified element in their structural order. + * @since 1.0.0 + * + * @param \FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node $parent

+ * Parent whose direct children to retrieve. + *

+ * + * @return iterable> Direct children. + */ + public function children (Node $parent):iterable; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Access/RootAccess.php b/src/Boundary/Capability/Access/RootAccess.php new file mode 100644 index 0000000..4552333 --- /dev/null +++ b/src/Boundary/Capability/Access/RootAccess.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.1 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Access; + +use FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node; + +/** + * ### Defines access to a root + * + * Provides access to the root of a hierarchical structure. + * + * The capability does not prescribe how the root is represented or how the underlying hierarchy is stored. + * @since 1.0.0 + * + * @template TValue + */ +interface RootAccess { + + /** + * ### Gets the root + * + * Returns the root of the structure or null when the structure is empty. + * @since 1.0.0 + * + * @return null|\FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node Root, or null when no root + * exists. + */ + public function root ():?Node; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/AncestorIteration.php b/src/Boundary/Capability/AncestorIteration.php new file mode 100644 index 0000000..20c481c --- /dev/null +++ b/src/Boundary/Capability/AncestorIteration.php @@ -0,0 +1,44 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability; + +/** + * ### Defines ancestor iteration + * + * Provides iteration over the ancestors of an element within a hierarchical structure. + * + * The element itself is not included in the iteration. + * @since 1.0.0 + * + * @template TValue + */ +interface AncestorIteration { + + /** + * ### Iterates over ancestors + * + * Iterates over the ancestors of the specified element, starting with its immediate parent and continuing toward + * the root. + * @since 1.0.0 + * + * @param \FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node $node

+ * Element whose ancestors to iterate over. + *

+ * + * @return iterable> Ancestors + * ordered from the immediate parent toward the root. + */ + public function ancestors (mixed $node):iterable; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/DescendantIteration.php b/src/Boundary/Capability/DescendantIteration.php new file mode 100644 index 0000000..7689dc8 --- /dev/null +++ b/src/Boundary/Capability/DescendantIteration.php @@ -0,0 +1,44 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability; + +/** + * ### Defines descendant iteration + * + * Provides iteration over the descendants of an element within a hierarchical structure. + * + * The element itself is not included in the iteration. The capability does not prescribe the traversal strategy used + * to visit descendants. + * @since 1.0.0 + * + * @template TValue + */ +interface DescendantIteration { + + /** + * ### Iterates over descendants + * + * Iterates over all descendants of the specified element. + * @since 1.0.0 + * + * @param \FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node $node

+ * Element whose descendants to iterate over. + *

+ * + * @return iterable> Descendant nodes in pre-order + * depth-first traversal order. + */ + public function descendants (mixed $node):iterable; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Measurement/Depth.php b/src/Boundary/Capability/Measurement/Depth.php new file mode 100644 index 0000000..f5c014c --- /dev/null +++ b/src/Boundary/Capability/Measurement/Depth.php @@ -0,0 +1,37 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Measurement; + +/** + * ### Defines depth measurement + * + * Provides the ability to determine the depth of an element within a hierarchical structure. + * + * Depth represents the number of structural edges between an element and the root. The root therefore has a depth + * of zero. + * @since 1.0.0 + */ +interface Depth { + + /** + * ### Gets the depth + * + * Returns the number of structural edges between this element and the root. + * @since 1.0.0 + * + * @return non-negative-int Depth of the element. + */ + public function depth ():int; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Measurement/Height.php b/src/Boundary/Capability/Measurement/Height.php new file mode 100644 index 0000000..7c4dc2f --- /dev/null +++ b/src/Boundary/Capability/Measurement/Height.php @@ -0,0 +1,37 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Measurement; + +/** + * ### Defines height measurement + * + * Provides the ability to determine the height of a hierarchical structure or element. + * + * Height represents the maximum number of structural edges between the measured element and any leaf below it. A + * leaf therefore has a height of zero. + * @since 1.0.0 + */ +interface Height { + + /** + * ### Gets the height + * + * Returns the maximum number of structural edges between this element and any leaf below it. + * @since 1.0.0 + * + * @return non-negative-int Height. + */ + public function height ():int; + +} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Tree.php b/src/Boundary/Type/DataStructure/Collection/Tree.php index ee281c3..8b455c8 100644 --- a/src/Boundary/Type/DataStructure/Collection/Tree.php +++ b/src/Boundary/Type/DataStructure/Collection/Tree.php @@ -15,6 +15,10 @@ use FireHub\Core\Boundary\Type\DataStructure\Classification\Hierarchical; use FireHub\Core\Boundary\Type\DataStructure\Collection; +use FireHub\Core\Boundary\Capability\ { + Access\ChildAccess, Access\RootAccess, + AncestorIteration, DescendantIteration, +}; /** * ### Defines a tree data structure @@ -36,5 +40,9 @@ * @template TValue * * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Capability\AncestorIteration + * @extends \FireHub\Core\Boundary\Capability\DescendantIteration + * @extends \FireHub\Core\Boundary\Capability\Access\RootAccess + * @extends \FireHub\Core\Boundary\Capability\Access\ChildAccess */ -interface Tree extends Hierarchical, Collection {} \ No newline at end of file +interface Tree extends Hierarchical, Collection, AncestorIteration, DescendantIteration, RootAccess, ChildAccess {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Tree/Node.php b/src/Boundary/Type/DataStructure/Collection/Tree/Node.php new file mode 100644 index 0000000..acc3473 --- /dev/null +++ b/src/Boundary/Type/DataStructure/Collection/Tree/Node.php @@ -0,0 +1,116 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Collection\Tree; + +use FireHub\Core\Boundary\Capability\Measurement\ { + Depth, Height +}; + +/** + * ### Tree node + * + * Represents a structural position within a tree data structure. + * + * A tree node contains a value and provides structural navigation to its parent, children, and adjacent siblings. + * Node identity is independent of the stored value, allowing multiple nodes containing equal values to represent + * distinct positions within the same tree. + * + * The node exposes its depth and height as structural measurements relative to the hierarchy it belongs to. + * @since 1.0.0 + * + * @template TValue + */ +interface Node extends Depth, Height { + + /** + * ### Checks whether this node is the root + * + * Determines whether this node represents the root of its tree. + * @since 1.0.0 + * + * @return bool True if this node is the root, false otherwise. + */ + public function isRoot ():bool; + + /** + * ### Checks whether this node is a leaf + * + * Determines whether this node has no child nodes. + * @since 1.0.0 + * + * @return bool True if this node is a leaf, false otherwise. + */ + public function isLeaf ():bool; + + /** + * ### Gets the value + * + * Returns the value stored by this node. + * @since 1.0.0 + * + * @return TValue Stored value. + */ + public function value ():mixed; + + /** + * ### Gets the parent + * + * Returns the parent node, or null when this node is the root. + * @since 1.0.0 + * + * @return null|static Parent node, or null for the root. + */ + public function parent ():?static; + + /** + * ### Gets the first child + * + * Returns the first direct child node, or null when this node has no children. + * @since 1.0.0 + * + * @return null|static First child node, or null when no children exist. + */ + public function firstChild ():?static; + + /** + * ### Gets the last child + * + * Returns the last direct child node, or null when this node has no children. + * @since 1.0.0 + * + * @return null|static Last child node, or null when no children exist. + */ + public function lastChild ():?static; + + /** + * ### Gets the previous sibling + * + * Returns the immediately preceding sibling node, or null when this node is the first child or root. + * @since 1.0.0 + * + * @return null|static Previous sibling node, or null when none exists. + */ + public function previousSibling ():?static; + + /** + * ### Gets the next sibling + * + * Returns the immediately following sibling node, or null when this node is the last child or root. + * @since 1.0.0 + * + * @return null|static Next sibling node, or null when none exists. + */ + public function nextSibling ():?static; + +} \ No newline at end of file From 314940eedadd36144f9ab94dd29689f52de206fc Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 5 Oct 2026 13:16:33 +0200 Subject: [PATCH 104/118] No changes made; removed unnecessary whitespace in `Tree.php` imports. **Details:** - Cleaned up formatting in the `use` statement block by removing an extra trailing comma. - Maintains codebase consistency and improves readability without functional changes. --- src/Boundary/Type/DataStructure/Collection/Tree.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Boundary/Type/DataStructure/Collection/Tree.php b/src/Boundary/Type/DataStructure/Collection/Tree.php index 8b455c8..d098cfc 100644 --- a/src/Boundary/Type/DataStructure/Collection/Tree.php +++ b/src/Boundary/Type/DataStructure/Collection/Tree.php @@ -17,7 +17,7 @@ use FireHub\Core\Boundary\Type\DataStructure\Collection; use FireHub\Core\Boundary\Capability\ { Access\ChildAccess, Access\RootAccess, - AncestorIteration, DescendantIteration, + AncestorIteration, DescendantIteration }; /** From ffa8a7be8daf89e2d18af4ad85da012a92fb8103 Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 5 Oct 2026 13:22:34 +0200 Subject: [PATCH 105/118] "Refine `AncestorIteration` and `DescendantIteration` signatures to enforce type safety **Details:** - Updated the `descendants` and `ancestors` method signatures to accept a `Node` type instead of `mixed`. - Added `use FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node` statements to both interfaces for proper type reference. - Improves consistency and ensures stricter type checking in hierarchical traversal capabilities." --- src/Boundary/Capability/AncestorIteration.php | 4 +++- src/Boundary/Capability/DescendantIteration.php | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/src/Boundary/Capability/AncestorIteration.php b/src/Boundary/Capability/AncestorIteration.php index 20c481c..0429585 100644 --- a/src/Boundary/Capability/AncestorIteration.php +++ b/src/Boundary/Capability/AncestorIteration.php @@ -13,6 +13,8 @@ namespace FireHub\Core\Boundary\Capability; +use FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node; + /** * ### Defines ancestor iteration * @@ -39,6 +41,6 @@ interface AncestorIteration { * @return iterable> Ancestors * ordered from the immediate parent toward the root. */ - public function ancestors (mixed $node):iterable; + public function ancestors (Node $node):iterable; } \ No newline at end of file diff --git a/src/Boundary/Capability/DescendantIteration.php b/src/Boundary/Capability/DescendantIteration.php index 7689dc8..547f614 100644 --- a/src/Boundary/Capability/DescendantIteration.php +++ b/src/Boundary/Capability/DescendantIteration.php @@ -13,6 +13,8 @@ namespace FireHub\Core\Boundary\Capability; +use FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node; + /** * ### Defines descendant iteration * @@ -39,6 +41,6 @@ interface DescendantIteration { * @return iterable> Descendant nodes in pre-order * depth-first traversal order. */ - public function descendants (mixed $node):iterable; + public function descendants (Node $node):iterable; } \ No newline at end of file From 1f2adeac4cf1405a3fb32a955999592acfd52ec7 Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 5 Oct 2026 13:30:34 +0200 Subject: [PATCH 106/118] "Add `Depth` and `Height` capabilities to `Tree` interface **Details:** - Updated `Tree.php` to include `Depth` and `Height` capabilities for measuring tree structure properties. - Enhanced the `Tree` interface by appending `Depth` and `Height` to its list of implemented capabilities. - Improves the flexibility of hierarchical data structures by enabling depth and height measurement features." --- src/Boundary/Type/DataStructure/Collection/Tree.php | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/Boundary/Type/DataStructure/Collection/Tree.php b/src/Boundary/Type/DataStructure/Collection/Tree.php index d098cfc..c9ebcdf 100644 --- a/src/Boundary/Type/DataStructure/Collection/Tree.php +++ b/src/Boundary/Type/DataStructure/Collection/Tree.php @@ -17,6 +17,7 @@ use FireHub\Core\Boundary\Type\DataStructure\Collection; use FireHub\Core\Boundary\Capability\ { Access\ChildAccess, Access\RootAccess, + Measurement\Depth, Measurement\Height, AncestorIteration, DescendantIteration }; @@ -45,4 +46,5 @@ * @extends \FireHub\Core\Boundary\Capability\Access\RootAccess * @extends \FireHub\Core\Boundary\Capability\Access\ChildAccess */ -interface Tree extends Hierarchical, Collection, AncestorIteration, DescendantIteration, RootAccess, ChildAccess {} \ No newline at end of file +interface Tree extends Hierarchical, Collection, AncestorIteration, DescendantIteration, RootAccess, ChildAccess, Depth, + Height {} \ No newline at end of file From bb13982ce6b6a65481fc366eb69f2781753c7784 Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 5 Oct 2026 13:39:12 +0200 Subject: [PATCH 107/118] Add `SiblingIteration` interface and refine PHPDoc in `DescendantIteration` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Details:** - Introduced the `SiblingIteration` interface in `Core-Standard/src/Boundary/Capability/SiblingIteration.php`: - Defines the `siblings(Node $node): iterable` method for iterating over sibling nodes within a hierarchical structure. - Excludes the specified node itself and ensures root nodes are excluded as they have no siblings. - Enhances hierarchical traversal capabilities by introducing sibling-specific iteration. - Updated PHPDoc in `DescendantIteration`: - Refined multi-line format of the `@return` annotation for readability and consistency. - Improved documentation clarity for descendant iteration in pre-order depth-first traversal. - Elevates the FireHub Core ecosystem’s support for hierarchical structures with an expanded and well-documented API. --- .../Capability/DescendantIteration.php | 4 +- src/Boundary/Capability/SiblingIteration.php | 47 +++++++++++++++++++ 2 files changed, 49 insertions(+), 2 deletions(-) create mode 100644 src/Boundary/Capability/SiblingIteration.php diff --git a/src/Boundary/Capability/DescendantIteration.php b/src/Boundary/Capability/DescendantIteration.php index 547f614..dabf5bf 100644 --- a/src/Boundary/Capability/DescendantIteration.php +++ b/src/Boundary/Capability/DescendantIteration.php @@ -38,8 +38,8 @@ interface DescendantIteration { * Element whose descendants to iterate over. *

* - * @return iterable> Descendant nodes in pre-order - * depth-first traversal order. + * @return iterable> Descendant nodes + * in pre-order depth-first traversal order. */ public function descendants (Node $node):iterable; diff --git a/src/Boundary/Capability/SiblingIteration.php b/src/Boundary/Capability/SiblingIteration.php new file mode 100644 index 0000000..974befc --- /dev/null +++ b/src/Boundary/Capability/SiblingIteration.php @@ -0,0 +1,47 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability; + +use FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node; + +/** + * ### Defines sibling iteration + * + * Provides iteration over the siblings of a node within a hierarchical structure. + * + * The specified node itself is not included in the iteration. + * @since 1.0.0 + * + * @template TValue + */ +interface SiblingIteration { + + /** + * ### Iterates over siblings + * + * Iterates over all nodes that share the same parent as the specified node while preserving their structural + * order. + * + * The specified node itself is excluded from the iteration. A root node has no siblings. + * @since 1.0.0 + * + * @param \FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node $node

+ * Node whose siblings to iterate over. + *

+ * + * @return iterable> Sibling nodes. + */ + public function siblings (Node $node):iterable; + +} \ No newline at end of file From b69936670619587676928b1648eaa7c068b8c5fd Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 5 Oct 2026 13:40:15 +0200 Subject: [PATCH 108/118] Add `SiblingIteration` to `Tree` interface **Details:** - Extended the `Tree` interface to include the `SiblingIteration` capability for iterating over sibling nodes in hierarchical structures. - Updated PHPDoc annotations to reflect the addition of `SiblingIteration`. - Enhances hierarchical data traversal by supporting sibling-level iteration, improving flexibility in tree-based operations. --- src/Boundary/Type/DataStructure/Collection/Tree.php | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/Boundary/Type/DataStructure/Collection/Tree.php b/src/Boundary/Type/DataStructure/Collection/Tree.php index c9ebcdf..e072477 100644 --- a/src/Boundary/Type/DataStructure/Collection/Tree.php +++ b/src/Boundary/Type/DataStructure/Collection/Tree.php @@ -18,7 +18,7 @@ use FireHub\Core\Boundary\Capability\ { Access\ChildAccess, Access\RootAccess, Measurement\Depth, Measurement\Height, - AncestorIteration, DescendantIteration + AncestorIteration, DescendantIteration, SiblingIteration }; /** @@ -45,6 +45,7 @@ * @extends \FireHub\Core\Boundary\Capability\DescendantIteration * @extends \FireHub\Core\Boundary\Capability\Access\RootAccess * @extends \FireHub\Core\Boundary\Capability\Access\ChildAccess + * @extends \FireHub\Core\Boundary\Capability\SiblingIteration */ -interface Tree extends Hierarchical, Collection, AncestorIteration, DescendantIteration, RootAccess, ChildAccess, Depth, - Height {} \ No newline at end of file +interface Tree extends Hierarchical, Collection, AncestorIteration, DescendantIteration, SiblingIteration, RootAccess, + ChildAccess, Depth, Height {} \ No newline at end of file From c99b9267194d4efc35146ea42ab2198ebdace023 Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 5 Oct 2026 15:01:21 +0200 Subject: [PATCH 109/118] Remove tree-related hierarchical abstractions from Core-Standard **Details:** - Deleted the following interfaces and abstractions related to hierarchical data structures: - `Tree`, `Node`, `AncestorIteration`, `DescendantIteration`, `SiblingIteration` - `RootAccess`, `ChildAccess` - `Depth`, `Height` - Removed corresponding PHPDoc annotations and type references across the deleted files. - This change simplifies the FireHub Core ecosystem by eliminating unused or redundant hierarchical capabilities from the codebase. --- .../Capability/Access/ChildAccess.php | 44 ------- src/Boundary/Capability/Access/RootAccess.php | 41 ------- src/Boundary/Capability/AncestorIteration.php | 46 ------- .../Capability/DescendantIteration.php | 46 ------- src/Boundary/Capability/Measurement/Depth.php | 37 ------ .../Capability/Measurement/Height.php | 37 ------ src/Boundary/Capability/SiblingIteration.php | 47 ------- .../Type/DataStructure/Collection/Tree.php | 51 -------- .../DataStructure/Collection/Tree/Node.php | 116 ------------------ 9 files changed, 465 deletions(-) delete mode 100644 src/Boundary/Capability/Access/ChildAccess.php delete mode 100644 src/Boundary/Capability/Access/RootAccess.php delete mode 100644 src/Boundary/Capability/AncestorIteration.php delete mode 100644 src/Boundary/Capability/DescendantIteration.php delete mode 100644 src/Boundary/Capability/Measurement/Depth.php delete mode 100644 src/Boundary/Capability/Measurement/Height.php delete mode 100644 src/Boundary/Capability/SiblingIteration.php delete mode 100644 src/Boundary/Type/DataStructure/Collection/Tree.php delete mode 100644 src/Boundary/Type/DataStructure/Collection/Tree/Node.php diff --git a/src/Boundary/Capability/Access/ChildAccess.php b/src/Boundary/Capability/Access/ChildAccess.php deleted file mode 100644 index 49e0b49..0000000 --- a/src/Boundary/Capability/Access/ChildAccess.php +++ /dev/null @@ -1,44 +0,0 @@ - - * @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 Core - */ - -namespace FireHub\Core\Boundary\Capability\Access; - -use FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node; - -/** - * ### Defines access to child elements - * - * Provides access to the direct children of an element within a hierarchical structure. - * - * This capability exposes only immediate children. Descendants below the first child level are not included. - * @since 1.0.0 - * - * @template TValue - */ -interface ChildAccess { - - /** - * ### Gets the children - * - * Returns the direct children of the specified element in their structural order. - * @since 1.0.0 - * - * @param \FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node $parent

- * Parent whose direct children to retrieve. - *

- * - * @return iterable> Direct children. - */ - public function children (Node $parent):iterable; - -} \ No newline at end of file diff --git a/src/Boundary/Capability/Access/RootAccess.php b/src/Boundary/Capability/Access/RootAccess.php deleted file mode 100644 index 4552333..0000000 --- a/src/Boundary/Capability/Access/RootAccess.php +++ /dev/null @@ -1,41 +0,0 @@ - - * @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.1 - * @package Core - */ - -namespace FireHub\Core\Boundary\Capability\Access; - -use FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node; - -/** - * ### Defines access to a root - * - * Provides access to the root of a hierarchical structure. - * - * The capability does not prescribe how the root is represented or how the underlying hierarchy is stored. - * @since 1.0.0 - * - * @template TValue - */ -interface RootAccess { - - /** - * ### Gets the root - * - * Returns the root of the structure or null when the structure is empty. - * @since 1.0.0 - * - * @return null|\FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node Root, or null when no root - * exists. - */ - public function root ():?Node; - -} \ No newline at end of file diff --git a/src/Boundary/Capability/AncestorIteration.php b/src/Boundary/Capability/AncestorIteration.php deleted file mode 100644 index 0429585..0000000 --- a/src/Boundary/Capability/AncestorIteration.php +++ /dev/null @@ -1,46 +0,0 @@ - - * @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 Core - */ - -namespace FireHub\Core\Boundary\Capability; - -use FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node; - -/** - * ### Defines ancestor iteration - * - * Provides iteration over the ancestors of an element within a hierarchical structure. - * - * The element itself is not included in the iteration. - * @since 1.0.0 - * - * @template TValue - */ -interface AncestorIteration { - - /** - * ### Iterates over ancestors - * - * Iterates over the ancestors of the specified element, starting with its immediate parent and continuing toward - * the root. - * @since 1.0.0 - * - * @param \FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node $node

- * Element whose ancestors to iterate over. - *

- * - * @return iterable> Ancestors - * ordered from the immediate parent toward the root. - */ - public function ancestors (Node $node):iterable; - -} \ No newline at end of file diff --git a/src/Boundary/Capability/DescendantIteration.php b/src/Boundary/Capability/DescendantIteration.php deleted file mode 100644 index dabf5bf..0000000 --- a/src/Boundary/Capability/DescendantIteration.php +++ /dev/null @@ -1,46 +0,0 @@ - - * @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 Core - */ - -namespace FireHub\Core\Boundary\Capability; - -use FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node; - -/** - * ### Defines descendant iteration - * - * Provides iteration over the descendants of an element within a hierarchical structure. - * - * The element itself is not included in the iteration. The capability does not prescribe the traversal strategy used - * to visit descendants. - * @since 1.0.0 - * - * @template TValue - */ -interface DescendantIteration { - - /** - * ### Iterates over descendants - * - * Iterates over all descendants of the specified element. - * @since 1.0.0 - * - * @param \FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node $node

- * Element whose descendants to iterate over. - *

- * - * @return iterable> Descendant nodes - * in pre-order depth-first traversal order. - */ - public function descendants (Node $node):iterable; - -} \ No newline at end of file diff --git a/src/Boundary/Capability/Measurement/Depth.php b/src/Boundary/Capability/Measurement/Depth.php deleted file mode 100644 index f5c014c..0000000 --- a/src/Boundary/Capability/Measurement/Depth.php +++ /dev/null @@ -1,37 +0,0 @@ - - * @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 Core - */ - -namespace FireHub\Core\Boundary\Capability\Measurement; - -/** - * ### Defines depth measurement - * - * Provides the ability to determine the depth of an element within a hierarchical structure. - * - * Depth represents the number of structural edges between an element and the root. The root therefore has a depth - * of zero. - * @since 1.0.0 - */ -interface Depth { - - /** - * ### Gets the depth - * - * Returns the number of structural edges between this element and the root. - * @since 1.0.0 - * - * @return non-negative-int Depth of the element. - */ - public function depth ():int; - -} \ No newline at end of file diff --git a/src/Boundary/Capability/Measurement/Height.php b/src/Boundary/Capability/Measurement/Height.php deleted file mode 100644 index 7c4dc2f..0000000 --- a/src/Boundary/Capability/Measurement/Height.php +++ /dev/null @@ -1,37 +0,0 @@ - - * @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 Core - */ - -namespace FireHub\Core\Boundary\Capability\Measurement; - -/** - * ### Defines height measurement - * - * Provides the ability to determine the height of a hierarchical structure or element. - * - * Height represents the maximum number of structural edges between the measured element and any leaf below it. A - * leaf therefore has a height of zero. - * @since 1.0.0 - */ -interface Height { - - /** - * ### Gets the height - * - * Returns the maximum number of structural edges between this element and any leaf below it. - * @since 1.0.0 - * - * @return non-negative-int Height. - */ - public function height ():int; - -} \ No newline at end of file diff --git a/src/Boundary/Capability/SiblingIteration.php b/src/Boundary/Capability/SiblingIteration.php deleted file mode 100644 index 974befc..0000000 --- a/src/Boundary/Capability/SiblingIteration.php +++ /dev/null @@ -1,47 +0,0 @@ - - * @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 Core - */ - -namespace FireHub\Core\Boundary\Capability; - -use FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node; - -/** - * ### Defines sibling iteration - * - * Provides iteration over the siblings of a node within a hierarchical structure. - * - * The specified node itself is not included in the iteration. - * @since 1.0.0 - * - * @template TValue - */ -interface SiblingIteration { - - /** - * ### Iterates over siblings - * - * Iterates over all nodes that share the same parent as the specified node while preserving their structural - * order. - * - * The specified node itself is excluded from the iteration. A root node has no siblings. - * @since 1.0.0 - * - * @param \FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node $node

- * Node whose siblings to iterate over. - *

- * - * @return iterable> Sibling nodes. - */ - public function siblings (Node $node):iterable; - -} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Tree.php b/src/Boundary/Type/DataStructure/Collection/Tree.php deleted file mode 100644 index e072477..0000000 --- a/src/Boundary/Type/DataStructure/Collection/Tree.php +++ /dev/null @@ -1,51 +0,0 @@ - - * @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.0 - * @package Core - */ - -namespace FireHub\Core\Boundary\Type\DataStructure\Collection; - -use FireHub\Core\Boundary\Type\DataStructure\Classification\Hierarchical; -use FireHub\Core\Boundary\Type\DataStructure\Collection; -use FireHub\Core\Boundary\Capability\ { - Access\ChildAccess, Access\RootAccess, - Measurement\Depth, Measurement\Height, - AncestorIteration, DescendantIteration, SiblingIteration -}; - -/** - * ### Defines a tree data structure - * - * A tree is a hierarchical collection whose elements are organized through parent-child relationships around a - * single root. - * - * Each element, except the root, has exactly one parent and may have zero or more children. Elements without - * children are the leaves. The structure is acyclic and every element is reachable from the root. - * - * This contract defines the structural identity of a tree without prescribing branching constraints, traversal - * order, node representation, mutation behavior, balancing rules, ordering semantics, or storage implementation. - * - * Specialized tree structures may impose additional invariants such as a fixed branching factor, value ordering, - * balancing, or search semantics. - * @since 1.0.0 - * - * @template TKey - * @template TValue - * - * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection - * @extends \FireHub\Core\Boundary\Capability\AncestorIteration - * @extends \FireHub\Core\Boundary\Capability\DescendantIteration - * @extends \FireHub\Core\Boundary\Capability\Access\RootAccess - * @extends \FireHub\Core\Boundary\Capability\Access\ChildAccess - * @extends \FireHub\Core\Boundary\Capability\SiblingIteration - */ -interface Tree extends Hierarchical, Collection, AncestorIteration, DescendantIteration, SiblingIteration, RootAccess, - ChildAccess, Depth, Height {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/Tree/Node.php b/src/Boundary/Type/DataStructure/Collection/Tree/Node.php deleted file mode 100644 index acc3473..0000000 --- a/src/Boundary/Type/DataStructure/Collection/Tree/Node.php +++ /dev/null @@ -1,116 +0,0 @@ - - * @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.0 - * @package Core - */ - -namespace FireHub\Core\Boundary\Type\DataStructure\Collection\Tree; - -use FireHub\Core\Boundary\Capability\Measurement\ { - Depth, Height -}; - -/** - * ### Tree node - * - * Represents a structural position within a tree data structure. - * - * A tree node contains a value and provides structural navigation to its parent, children, and adjacent siblings. - * Node identity is independent of the stored value, allowing multiple nodes containing equal values to represent - * distinct positions within the same tree. - * - * The node exposes its depth and height as structural measurements relative to the hierarchy it belongs to. - * @since 1.0.0 - * - * @template TValue - */ -interface Node extends Depth, Height { - - /** - * ### Checks whether this node is the root - * - * Determines whether this node represents the root of its tree. - * @since 1.0.0 - * - * @return bool True if this node is the root, false otherwise. - */ - public function isRoot ():bool; - - /** - * ### Checks whether this node is a leaf - * - * Determines whether this node has no child nodes. - * @since 1.0.0 - * - * @return bool True if this node is a leaf, false otherwise. - */ - public function isLeaf ():bool; - - /** - * ### Gets the value - * - * Returns the value stored by this node. - * @since 1.0.0 - * - * @return TValue Stored value. - */ - public function value ():mixed; - - /** - * ### Gets the parent - * - * Returns the parent node, or null when this node is the root. - * @since 1.0.0 - * - * @return null|static Parent node, or null for the root. - */ - public function parent ():?static; - - /** - * ### Gets the first child - * - * Returns the first direct child node, or null when this node has no children. - * @since 1.0.0 - * - * @return null|static First child node, or null when no children exist. - */ - public function firstChild ():?static; - - /** - * ### Gets the last child - * - * Returns the last direct child node, or null when this node has no children. - * @since 1.0.0 - * - * @return null|static Last child node, or null when no children exist. - */ - public function lastChild ():?static; - - /** - * ### Gets the previous sibling - * - * Returns the immediately preceding sibling node, or null when this node is the first child or root. - * @since 1.0.0 - * - * @return null|static Previous sibling node, or null when none exists. - */ - public function previousSibling ():?static; - - /** - * ### Gets the next sibling - * - * Returns the immediately following sibling node, or null when this node is the last child or root. - * @since 1.0.0 - * - * @return null|static Next sibling node, or null when none exists. - */ - public function nextSibling ():?static; - -} \ No newline at end of file From 343a4533c2c0532ef1f9225b718cd4bd985b269b Mon Sep 17 00:00:00 2001 From: Riddick Date: Wed, 7 Oct 2026 08:55:32 +0200 Subject: [PATCH 110/118] Add `Searchable` interface for value lookup capability **Details:** - Introduced the `Searchable` interface in `Core-Standard/src/Boundary/Capability/Query/Searchable.php`: - Defines the `search(mixed $value): mixed` method for locating values within a data structure. - Returns a search result if a match exists or `null` otherwise. - Promotes flexibility by not enforcing specific search, comparison, or result representation logic. - Includes support for customizable value (`TValue`) and result (`TResult`) types. - Enhances the FireHub Core ecosystem with a reusable abstraction for value search capabilities. --- src/Boundary/Capability/Query/Searchable.php | 43 ++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 src/Boundary/Capability/Query/Searchable.php diff --git a/src/Boundary/Capability/Query/Searchable.php b/src/Boundary/Capability/Query/Searchable.php new file mode 100644 index 0000000..df30a9c --- /dev/null +++ b/src/Boundary/Capability/Query/Searchable.php @@ -0,0 +1,43 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Query; + +/** + * ### Defines value searching + * + * Provides the ability to search for a value and return a result identifying the matching value or its location + * within a data structure. + * + * The capability does not prescribe how values are searched, compared, stored, or represented, nor does it + * prescribe the representation of a successful search result. + * @since 1.0.0 + * + * @template TValue + * @template TResult + */ +interface Searchable { + + /** + * ### Searches for a value + * + * Searches for the specified value and returns the corresponding search result when a match exists. + * @since 1.0.0 + * + * @param TValue $value Value to search for. + * + * @return null|TResult Search result if the value was found, null otherwise. + */ + public function search (mixed $value):mixed; + +} \ No newline at end of file From 33a50a72a5abc36ab08868a822cb67dc78f762e7 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 9 Oct 2026 08:41:37 +0200 Subject: [PATCH 111/118] Import `Linear` classification in `Stream` data structure **Details:** - Added the `use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear` statement to `Stream.php`. - Prepares the `Stream` data structure to utilize the `Linear` classification for future enhancements or functionality. --- src/Boundary/Type/DataStructure/Stream.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/Boundary/Type/DataStructure/Stream.php b/src/Boundary/Type/DataStructure/Stream.php index e1aaeda..b40e460 100644 --- a/src/Boundary/Type/DataStructure/Stream.php +++ b/src/Boundary/Type/DataStructure/Stream.php @@ -13,6 +13,7 @@ namespace FireHub\Core\Boundary\Type\DataStructure; +use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear; use FireHub\Core\Boundary\Type\ { DataStructure, Enumerable }; @@ -36,4 +37,4 @@ * @extends \FireHub\Core\Boundary\Type\DataStructure * @extends \FireHub\Core\Boundary\Type\Enumerable */ -interface Stream extends DataStructure, Enumerable {} \ No newline at end of file +interface Stream extends DataStructure, Enumerable, Linear {} \ No newline at end of file From 76f5b35abf604958d56efd923b636ac9b5c55d02 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 9 Oct 2026 08:43:58 +0200 Subject: [PATCH 112/118] Reorder `use` statements for classification imports in `Stream.php` **Details:** - Moved `use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear` to follow alphabetical order within import statements. - Improves code readability and maintains consistency in import organization across the codebase. --- src/Boundary/Type/DataStructure/Stream.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Boundary/Type/DataStructure/Stream.php b/src/Boundary/Type/DataStructure/Stream.php index b40e460..4ebe418 100644 --- a/src/Boundary/Type/DataStructure/Stream.php +++ b/src/Boundary/Type/DataStructure/Stream.php @@ -13,10 +13,10 @@ namespace FireHub\Core\Boundary\Type\DataStructure; -use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear; use FireHub\Core\Boundary\Type\ { DataStructure, Enumerable }; +use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear; /** * ### Defines the Stream data structure From 1607b847a3ad4103fbce3a0d59bbd9e46881d396 Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 9 Oct 2026 12:14:40 +0200 Subject: [PATCH 113/118] **Rename `InvalidUtf8Exception` to `InvalidEncodingException` and update references** - **Changes**: - Renamed `InvalidUtf8Exception` to `InvalidEncodingException` in the `Foundation\Str\Exception` namespace: - The new class now represents errors related to invalid string encodings more broadly, not limited to UTF-8. - Refactored references in the `Utf8` class: - Updated exceptions thrown when invalid string encoding or content is detected. - **Rationale**: - Generalizes exception handling to support broader encoding-related errors beyond UTF-8. - Aligns naming conventions with increased flexibility for encoding-related validations. - Enhances clarity and future maintainability by deprecating an overly specific exception. --- .../Capability/Conversion/Arrayable.php | 2 +- .../Capability/Conversion/Charable.php | 42 ++++++++++++++++++ .../Capability/Conversion/Jsonable.php | 2 +- .../Capability/Conversion/Strable.php | 44 +++++++++++++++++++ src/Type/Str.php | 14 ++---- 5 files changed, 91 insertions(+), 13 deletions(-) create mode 100644 src/Boundary/Capability/Conversion/Charable.php create mode 100644 src/Boundary/Capability/Conversion/Strable.php diff --git a/src/Boundary/Capability/Conversion/Arrayable.php b/src/Boundary/Capability/Conversion/Arrayable.php index be601fa..777c715 100644 --- a/src/Boundary/Capability/Conversion/Arrayable.php +++ b/src/Boundary/Capability/Conversion/Arrayable.php @@ -7,7 +7,7 @@ * @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 + * @php-version >=7.0 * @package Core */ diff --git a/src/Boundary/Capability/Conversion/Charable.php b/src/Boundary/Capability/Conversion/Charable.php new file mode 100644 index 0000000..d3a0920 --- /dev/null +++ b/src/Boundary/Capability/Conversion/Charable.php @@ -0,0 +1,42 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Conversion; + +/** + * ### Defines conversion to character Value Objects + * + * Provides the ability to convert an object into an ordered list of FireHub character Value Objects. + * + * Each resulting element represents a single logical character according to the character model defined by the + * implementing class. + * + * The capability defines the conversion contract without prescribing the source representation, character + * encoding, or concrete character implementation. + * + * The resulting list preserves the logical ordering of characters in the source object. + * @since 1.0.0 + */ +interface Charable { + + /** + * ### Converts the object to a list of character Value Objects + * + * Returns an ordered list of FireHub character Value Objects representing the object's character sequence. + * @since 1.0.0 + * + * @return list<\FireHub\Core\Type\Char> The resulting character Value Objects. + */ + public function toChars ():array; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Conversion/Jsonable.php b/src/Boundary/Capability/Conversion/Jsonable.php index 0dd0ce3..f279d67 100644 --- a/src/Boundary/Capability/Conversion/Jsonable.php +++ b/src/Boundary/Capability/Conversion/Jsonable.php @@ -7,7 +7,7 @@ * @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 + * @php-version >=7.0 * @package Core */ diff --git a/src/Boundary/Capability/Conversion/Strable.php b/src/Boundary/Capability/Conversion/Strable.php new file mode 100644 index 0000000..4102f20 --- /dev/null +++ b/src/Boundary/Capability/Conversion/Strable.php @@ -0,0 +1,44 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Conversion; + +use FireHub\Core\Type\Str; + +/** + * ### Defines conversion to a string Value Object + * + * Provides the ability to convert an object into a FireHub string Value Object. + * + * The capability defines the conversion contract without prescribing how the string representation is constructed, + * which character encoding is used, or which concrete string implementation is returned. + * + * Implementations may construct the resulting string from stored values, logical elements, internal segments, or + * other representations while preserving the semantic meaning of the source object. + * @since 1.0.0 + */ +interface Strable { + + /** + * ### Converts the object to a string Value Object + * + * Returns a FireHub string Value Object representing the object's string content. + * + * The concrete string implementation and character encoding are determined by the implementing class. + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Str The resulting string Value Object. + */ + public function toStr ():Str; + +} \ No newline at end of file diff --git a/src/Type/Str.php b/src/Type/Str.php index 84b6c38..8ecb701 100644 --- a/src/Type/Str.php +++ b/src/Type/Str.php @@ -13,6 +13,8 @@ namespace FireHub\Core\Type; +use FireHub\Core\Boundary\Capability\Conversion\Charable; + /** * ### Defines the base string Value Object type within the FireHub ecosystem * @@ -29,14 +31,4 @@ * * @extends \FireHub\Core\Type\StringValue */ -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 +abstract readonly class Str extends StringValue implements Charable {} \ No newline at end of file From 340b377d08beff2d7a8425b0742b502f422be52b Mon Sep 17 00:00:00 2001 From: Riddick Date: Fri, 9 Oct 2026 13:51:47 +0200 Subject: [PATCH 114/118] **Add `IndexInsertion` interface for value insertion capability** - **Details**: - Introduced the `IndexInsertion` interface in `Core-Standard/src/Boundary/Capability/Mutation/IndexInsertion.php`: - Defines the `insertAt(int $index, mixed $value): MutationOutcome` method for inserting values at a specific index within an ordered collection. - Supports prepending, appending, or inserting at valid indices while maintaining order and shifting elements. - Returns a `MutationOutcome` to indicate whether the insertion was successful (`CREATED`) or failed due to an invalid index (`NOT_FOUND`). - Incorporates comprehensive PHPDoc annotations outlining usage, behavior, and constraints. - **Rationale**: - Adds a reusable abstraction for index-based insertion to the FireHub Core ecosystem. - Enables standardized, clear, and extensible handling of ordered collection modifications. - Improves maintainability and future scaling with a modular design pattern. --- .../Capability/Mutation/IndexInsertion.php | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 src/Boundary/Capability/Mutation/IndexInsertion.php diff --git a/src/Boundary/Capability/Mutation/IndexInsertion.php b/src/Boundary/Capability/Mutation/IndexInsertion.php new file mode 100644 index 0000000..a2f4528 --- /dev/null +++ b/src/Boundary/Capability/Mutation/IndexInsertion.php @@ -0,0 +1,66 @@ + + * @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.1 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Meta\Enum\MutationOutcome; + +/** + * ### Defines indexed insertion of values + * + * Indexed insertion provides the ability to insert a single value at a specified position within an ordered + * collection. + * + * Inserting a value shifts the existing element at the specified index, along with all later elements, one position + * toward the end of the collection while preserving their relative order. + * + * The insertion index may refer to an existing element or the position immediately following the last element. + * Inserting at index zero prepends the value, while inserting at the collection size appends it. + * + * The capability defines the logical behavior of indexed insertion without prescribing how values are stored, + * organized, or shifted internally. + * + * Each insertion operation reports its result through a MutationOutcome value. + * @since 1.0.0 + * + * @template TValue + */ +interface IndexInsertion { + + /** + * ### Inserts a value at the specified index + * + * Inserts a single value before the element currently occupying the specified index. + * + * Existing elements at and after the insertion position are shifted one index toward the end of the collection. + * Their relative ordering remains unchanged. + * + * An index equal to the collection size appends the value. Negative indexes and indexes greater than the + * collection size are invalid and do not modify the collection. + * + * A successful insertion increases the collection size by exactly one element. + * @since 1.0.0 + * + * @param int $index

+ * Zero-based insertion index. + *

+ * @param TValue $value

+ * Value to insert. + *

+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the replacement: CREATED if the value was + * inserted, or NOT_FOUND if the index does not exist. + */ + public function insertAt (int $index, mixed $value):MutationOutcome; + +} \ No newline at end of file From 46f3b9d3aa59f7273d02d2a2d294afafaa8cb2fe Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 12 Oct 2026 12:39:42 +0200 Subject: [PATCH 115/118] Add `Insertion` interface for general value insertion capability - **Details**: - Introduced the `Insertion` interface in `Core-Standard/src/Boundary/Capability/Mutation/Insertion.php`: - Defines the `insert(mixed ...$values): void` method for inserting one or more values into a data structure. - Leaves the positioning of inserted values up to the organizational rules of the implementing structure. - Includes comprehensive PHPDoc annotations outlining usage, behavior, and constraints. - Provides a flexible abstraction to handle generic data structure insertions while adhering to their internal rules. - **Rationale**: - Enhances the FireHub Core ecosystem with a reusable interface for general data insertion operations. - Promotes modularity and extensibility for future-proof data structure handling. - Lays a strong foundation for standardized mutation capabilities across various structures. --- .../Capability/Mutation/Insertion.php | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 src/Boundary/Capability/Mutation/Insertion.php diff --git a/src/Boundary/Capability/Mutation/Insertion.php b/src/Boundary/Capability/Mutation/Insertion.php new file mode 100644 index 0000000..9c36600 --- /dev/null +++ b/src/Boundary/Capability/Mutation/Insertion.php @@ -0,0 +1,45 @@ + + * @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 Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +/** + * ### Defines insertion of values into a data structure + * + * Insertion defines the ability to add values to a data structure without prescribing their resulting positions. + * + * The capability allows the implementing structure to determine how inserted values are organized according + * to its ordering rules, structural constraints, or storage representation. + * @since 1.0.0 + * + * @template TValue + */ +interface Insertion { + + /** + * ### Inserts values into the data structure + * + * Inserts one or more values according to the organizational rules of the implementing structure. + * + * The operation does not guarantee that inserted values occupy the front, back, or any particular position. + * @since 1.0.0 + * + * @param TValue ...$values

+ * Values to insert. + *

+ * + * @return void + */ + public function insert (mixed ...$values):void; + +} \ No newline at end of file From fb0a9e25dda6097bc1504e71a2c16e6566b5a044 Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 12 Oct 2026 12:55:35 +0200 Subject: [PATCH 116/118] Add `Heap` and `PriorityQueue` abstractions to the Core data structures **Details**: - Introduced the `Heap` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Heap.php`: - Defines a heap data structure, focusing on maintaining priority relationships between elements. - Supports extensibility for specialized heap implementations by abstracting branching factors, comparison strategies, and ordering semantics. - Implements key characteristics of hierarchical and collection-based structures with front-access capabilities. - Introduced the `PriorityQueue` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/PriorityQueue.php`: - Defines a priority queue, where retrieval order is determined by element priority rather than insertion order. - Abstracts priority assignment, comparison, and ordering without requiring specific internal representations. - Implements key characteristics of linear and collection-based structures with front-access capabilities. **Rationale**: - Expands the FireHub Core ecosystem with abstractions for two critical data structures to support priority-based organization and access. - Improves modularity, enabling developers to build reusable and extensible heap and priority queue implementations in conformance with shared boundaries. - Establishes a strong groundwork for future extensions, operational constraints, and specialized prioritization rules. --- .../Type/DataStructure/Collection/Heap.php | 44 +++++++++++++++++++ .../Collection/PriorityQueue.php | 44 +++++++++++++++++++ 2 files changed, 88 insertions(+) create mode 100644 src/Boundary/Type/DataStructure/Collection/Heap.php create mode 100644 src/Boundary/Type/DataStructure/Collection/PriorityQueue.php diff --git a/src/Boundary/Type/DataStructure/Collection/Heap.php b/src/Boundary/Type/DataStructure/Collection/Heap.php new file mode 100644 index 0000000..e77b66d --- /dev/null +++ b/src/Boundary/Type/DataStructure/Collection/Heap.php @@ -0,0 +1,44 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Collection; + +use FireHub\Core\Boundary\Capability\Access\FrontAccess; +use FireHub\Core\Boundary\Type\DataStructure\Classification\Hierarchical; +use FireHub\Core\Boundary\Type\DataStructure\Collection; + +/** + * ### Defines a heap data structure + * + * Represents a collection of elements organized according to a heap-ordering invariant. + * + * A heap maintains a priority relationship between its elements, ensuring that an element with the highest + * precedence according to the heap's ordering rules is available at the top of the structure. The ordering + * relationship may be defined by natural value ordering, a comparator, or another implementation-specific + * priority strategy. + * + * This contract defines the fundamental characteristics shared by heap-based data structures without prescribing + * how elements are represented, accessed, traversed, or modified. It does not impose a particular branching factor, + * internal storage representation, comparison strategy, or requirement for globally sorted iteration. + * + * Specialized heap contracts may extend this abstraction to define additional structural constraints, ordering + * semantics, merging capabilities, or operational guarantees appropriate to their particular implementation. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Capability\Access\FrontAccess + */ +interface Heap extends Hierarchical, Collection, FrontAccess {} \ No newline at end of file diff --git a/src/Boundary/Type/DataStructure/Collection/PriorityQueue.php b/src/Boundary/Type/DataStructure/Collection/PriorityQueue.php new file mode 100644 index 0000000..34c4826 --- /dev/null +++ b/src/Boundary/Type/DataStructure/Collection/PriorityQueue.php @@ -0,0 +1,44 @@ + + * @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.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Type\DataStructure\Collection; + +use FireHub\Core\Boundary\Capability\Access\FrontAccess; +use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear; +use FireHub\Core\Boundary\Type\DataStructure\Collection; + +/** + * ### Defines a priority queue data structure + * + * Represents a linear collection of elements organized according to their assigned priorities. + * + * A priority queue determines the order in which elements become available for retrieval based on their relative + * priorities rather than their insertion order. Elements with higher precedence are selected before elements with + * lower precedence, according to the priority ordering rules established by the implementation. + * + * This contract defines the fundamental characteristics shared by priority queue data structures without + * prescribing how priorities are represented, compared, assigned, or maintained. It does not impose a particular + * internal storage representation, ordering direction, stability guarantee for equal priorities, or requirement + * for globally sorted iteration. + * + * Specialized priority queue contracts may extend this abstraction to define additional priority management, + * ordering semantics, stability guarantees, or operational capabilities appropriate to their implementation. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends \FireHub\Core\Boundary\Type\DataStructure\Collection + * @extends \FireHub\Core\Boundary\Capability\Access\FrontAccess + */ +interface PriorityQueue extends Linear, Collection, FrontAccess {} \ No newline at end of file From 61f3500d2a68acf7bc9ee4df4ab1ef2242c2507f Mon Sep 17 00:00:00 2001 From: Riddick Date: Mon, 12 Oct 2026 13:36:57 +0200 Subject: [PATCH 117/118] Add `Entry` value object to `PriorityQueue` data structure **Details**: - Introduced the `Entry` class in `Core-Standard/src/Type/DataStructure/PriorityQueue/Entry.php`: - Represents an immutable priority-value association for use in priority queues. - Implements a strongly typed value object to maintain a priority and its associated value as a single unit. - Includes methods to retrieve the priority and value pair in array format. - Enhances the modularity and clarity of the `PriorityQueue` abstraction by providing a dedicated implementation for priority-value entries. --- .../DataStructure/PriorityQueue/Entry.php | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 src/Type/DataStructure/PriorityQueue/Entry.php diff --git a/src/Type/DataStructure/PriorityQueue/Entry.php b/src/Type/DataStructure/PriorityQueue/Entry.php new file mode 100644 index 0000000..0fb9d7e --- /dev/null +++ b/src/Type/DataStructure/PriorityQueue/Entry.php @@ -0,0 +1,70 @@ + + * @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\DataStructure\PriorityQueue; + +use FireHub\Core\Type\ValueObject; + +/** + * ### Priority queue entry + * + * Represents an immutable priority-value entry belonging to a priority queue. + * + * A priority queue entry groups a priority together with its associated value and represents that association as a + * single value object. It provides a strongly typed representation of an individual priority queue entry when the + * priority and value need to be passed, returned, or otherwise handled together. + * + * The entry does not provide priority queue storage or ordering behavior and does not maintain any relationship with + * the priority queue from which it originated. It represents only the priority-value association itself. + * @since 1.0.0 + * + * @template TPriority + * @template TValue + * + * @extends ValueObject + */ +final readonly class Entry extends ValueObject { + + /** + * ### Constructor + * @since 1.0.0 + * + * @param TPriority $priority

+ * The entry priority. + *

+ * @param TValue $value

+ * The entry value. + *

+ * + * @return void + */ + public function __construct ( + public mixed $priority, + public mixed $value + ) {} + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():array { + + return [ + 'priority' => $this->priority, + 'value' => $this->value + ]; + + } + +} \ No newline at end of file From af0f64c815fe2be703b5200774ab3d9115271874 Mon Sep 17 00:00:00 2001 From: Riddick Date: Tue, 13 Oct 2026 09:54:33 +0200 Subject: [PATCH 118/118] Update README badges and restructure branch documentation for develop **Details**: - Updated branch references in README badges from `architecture/foundation-support` to `develop`: - Includes badges for PHPStan, PHPUnit, Codecov, and GitHub activity. - Adjusted commit comparison links to reflect `master` vs. `develop` instead of `develop` vs. `architecture/foundation-support`. - Reorganized branch documentation: - Clarified the purpose and stability guarantees of the `develop` branch. - Removed outdated milestones, pull request details, and related branch information. - Condensed architectural notes and shifted focus to `develop` as the main integration branch. - Improved clarity and alignment between README content and current branch structure. --- README.md | 121 ++++++++++++++++-------------------------------------- 1 file changed, 35 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index fc07a8d..a734470 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=architecture%2Ffoundation-support)](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%2Ffoundation-support)](https://github.com/The-FireHub-Project/Core-Standard/actions/workflows/PHPUnit.yml) -[![Codecov](https://codecov.io/gh/The-FireHub-Project/Core-Standard/branch/architecture%2Ffoundation-support/graph/badge.svg?token=XW2YEONF51)](https://app.codecov.io/gh/The-FireHub-Project/Core-Standard/tree/architecture%2Ffoundation-support) +[![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)

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

@@ -49,98 +49,47 @@ Standard provides the base classes, kernel, domain layer, and minimal runtime ut --- -## FireHub Icon Foundation Support – Development Branch +## FireHub Icon Development Branch -⚠️ **This is the `development` branch** +⚠️ **This is the `develop` 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 -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: +The `develop` branch is the **primary integration branch** for all ongoing development. -Core -↓ -Foundation -↓ -Runtime +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 -where Core defines contracts, Foundation implements developer APIs, and Runtime provides execution primitives. +All **release branches** are created **from `develop`**. -## FireHub Icon Core Concept +## Stability Guarantee -Introduce minimal Core contracts for fundamental high-level abstractions while keeping implementation details outside the Core layer. +❌ No backward compatibility guarantee +❌ APIs may change without notice +❌ Behavior may be incomplete or inconsistent +❌ Breaking changes are expected -Core contracts represent stable architectural concepts and define only the behavior required by the ecosystem. +This branch is intended **only for contributors and advanced testers**. -Foundation implementations provide the complete developer experience through: +## FireHub Icon Composer Usage (Not Recommended) -- Object-oriented APIs -- Immutable value-based objects where applicable -- Fluent interfaces -- Rich domain-oriented operations +For internal testing only: -The Core layer defines what an abstraction is, while Foundation defines how developers use it. +```json +{ + "require": { + "the-firehub-project/core-standard": "dev-develop" + } +} +``` +⚠️ Never use dev-develop in production. ## FireHub Icon Authors and Contributors @@ -157,4 +106,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). \ No newline at end of file +For more details, read the full license [here](./LICENSE).