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 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 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 new file mode 100644 index 0000000..84b6c38 --- /dev/null +++ b/src/Type/Str.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.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\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 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 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