From 23086d101bd2240a0341f2107f49f27c6ebb3e94 Mon Sep 17 00:00:00 2001 From: Riddick Date: Wed, 24 Jun 2026 14:32:15 +0200 Subject: [PATCH 01/10] Update README to reflect the new error and exception abstraction branch **Details:** - Updated badge links and branch references to point to the `architecture/error-exception-base` branch. - Adjusted branch purpose and overview to describe the introduction of a **core error and exception abstraction layer**. - Added detailed sections explaining architectural goals, core concepts, and the FireHub-native error system. - Introduced related milestone, pull request, and repository metadata to enhance clarity on progress and objectives. - This update formalizes the foundation for structured error handling in the FireHub ecosystem and prepares it for future architectural expansions. --- README.md | 110 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 78 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 6a6e86b..46d0125 100644 --- a/README.md +++ b/README.md @@ -23,19 +23,19 @@

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

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

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

+ +### Milestone + +

+ + GitHub milestone details +

+ ## FireHub Icon Branch Purpose -The `develop` branch is the **primary integration branch** for all ongoing development. +This branch introduces the **core error and exception abstraction layer** for the FireHub Core-Standard ecosystem. + +It defines how all framework-level failures are represented, structured, and propagated across the FireHub architecture, establishing a unified foundation for error handling across: + +- Core Standard +- Core Professional +- Core Enterprise +- Runtime Foundation (consumers and execution layer) +- Testing infrastructure + +This is a foundational architectural step that replaces direct dependency on PHP native `\Error` and `\Exception` usage inside FireHub Core. + +## FireHub Icon Architectural Goal + +Establish a **unified FireHub-native error handling model** that: -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 +- Separates system-level errors from domain-level exceptions +- Provides consistent inheritance roots for all framework failures +- Decouples FireHub from direct PHP `Throwable` hierarchy usage +- Enables structured and extensible error classification in future layers (Runtime, Adapters, Capabilities) +- Ensures predictable error propagation across all FireHub components -All **release branches** are created **from `develop`**. +This layer becomes the **contractual foundation** for all error handling inside the FireHub ecosystem. -## 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 +A FireHub Error System is defined as: -This branch is intended **only for contributors and advanced testers**. +> A structured, framework-level abstraction over PHP’s native error and exception system, designed to enforce consistent failure semantics across all architectural layers. -## FireHub Icon Composer Usage (Not Recommended) +It introduces two primary abstractions: -For internal testing only: +- `FireHub\Core\Error\FireHubError` → system-level and structural failures +- `FireHub\Core\Error\FireHubException` → runtime and domain-level failures -```json -{ - "require": { - "the-firehub-project/core-standard": "dev-develop" - } -} -``` -⚠️ Never use dev-develop in production. +Together they form the **FireHub error contract layer**, ensuring all failures are typed, predictable, and architecturally consistent. ## FireHub Icon Authors and Contributors @@ -102,4 +148,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 94db6f7450f70d31cad785a0a73fb0596fa3ed9c Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 25 Jun 2026 09:55:47 +0200 Subject: [PATCH 02/10] Introduce core exception hierarchy and add comprehensive unit tests **Details:** - Added a `FireHubException` base class along with specialized subtypes (`DomainException`, `RuntimeException`, `ValidationException`, etc.) to establish a structured exception hierarchy for the FireHub ecosystem. - Introduced `Code` value object as a type-safe representation of error codes with invariant enforcement. - Implemented concrete exceptions such as `InvalidCodeValueException` to handle specific invariant violations. - Refactored `ValueObject` to incorporate stricter exception handling and validation mechanisms. - Updated existing `ValueObject` tests to use the new exception types and replaced generic exceptions with FireHub-native ones. - Added unit tests for: - `DomainException`, `RuntimeException`, `SecurityException`, and other exception subtypes. - `Code` value object validation and functionality. - Dummy exception stubs for base test scenarios. - Enhanced test coverage and enforced consistent exception handling, laying a foundation for robust error management in the framework. --- src/Exception/Code.php | 67 +++++++++++++++++ src/Exception/Domain/ValidationException.php | 28 +++++++ src/Exception/DomainException.php | 60 +++++++++++++++ src/Exception/FireHubException.php | 50 +++++++++++++ .../Invariant/InvalidCodeValueException.php | 36 +++++++++ .../Runtime/System/InvariantException.php | 28 +++++++ src/Exception/Runtime/SystemException.php | 29 ++++++++ src/Exception/RuntimeException.php | 58 +++++++++++++++ src/Exception/SecurityException.php | 58 +++++++++++++++ src/Type/Exception/ValueObjectException.php | 27 +++++++ src/Type/ValueObject.php | 22 +++++- .../Stubs/Exception/DummyDomainException.php | 22 ++++++ tests/Stubs/Exception/DummyException.php | 22 ++++++ .../Stubs/Exception/DummyRuntimeException.php | 22 ++++++ .../Exception/DummySecurityException.php | 22 ++++++ tests/Stubs/Type/DummyIntVO.php | 4 +- tests/Stubs/Type/DummyStringVO.php | 4 +- tests/Unit/Exception/CodeTest.php | 72 ++++++++++++++++++ tests/Unit/Exception/DomainExceptionTest.php | 63 ++++++++++++++++ tests/Unit/Exception/FireHubExceptionTest.php | 74 +++++++++++++++++++ tests/Unit/Exception/RuntimeExceptionTest.php | 63 ++++++++++++++++ .../Unit/Exception/SecurityExceptionTest.php | 63 ++++++++++++++++ tests/Unit/Type/ValueObjectTest.php | 4 +- 23 files changed, 890 insertions(+), 8 deletions(-) create mode 100644 src/Exception/Code.php create mode 100644 src/Exception/Domain/ValidationException.php create mode 100644 src/Exception/DomainException.php create mode 100644 src/Exception/FireHubException.php create mode 100644 src/Exception/Runtime/System/Invariant/InvalidCodeValueException.php create mode 100644 src/Exception/Runtime/System/InvariantException.php create mode 100644 src/Exception/Runtime/SystemException.php create mode 100644 src/Exception/RuntimeException.php create mode 100644 src/Exception/SecurityException.php create mode 100644 src/Type/Exception/ValueObjectException.php create mode 100644 tests/Stubs/Exception/DummyDomainException.php create mode 100644 tests/Stubs/Exception/DummyException.php create mode 100644 tests/Stubs/Exception/DummyRuntimeException.php create mode 100644 tests/Stubs/Exception/DummySecurityException.php create mode 100644 tests/Unit/Exception/CodeTest.php create mode 100644 tests/Unit/Exception/DomainExceptionTest.php create mode 100644 tests/Unit/Exception/FireHubExceptionTest.php create mode 100644 tests/Unit/Exception/RuntimeExceptionTest.php create mode 100644 tests/Unit/Exception/SecurityExceptionTest.php diff --git a/src/Exception/Code.php b/src/Exception/Code.php new file mode 100644 index 0000000..1ea5514 --- /dev/null +++ b/src/Exception/Code.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.2 + * @package Core + */ + +namespace FireHub\Core\Exception; + +use FireHub\Core\Type\ValueObject; +use FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodeValueException; + +/** + * ### Error code value object + * @since 1.0.0 + * + * @template TValue of int + * + * @extends \FireHub\Core\Type\ValueObject + */ +final readonly class Code extends ValueObject { + + /** + * ### Constructor + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\ValueObject::guard() As a guard. + * + * @param TValue $value

+ * The error code. + *

+ * + * @throws \FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodeValueException 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, + fn() => new InvalidCodeValueException('Value must be positive.') + ); + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():int { + + return $this->value; + + } + +} \ No newline at end of file diff --git a/src/Exception/Domain/ValidationException.php b/src/Exception/Domain/ValidationException.php new file mode 100644 index 0000000..b44cb79 --- /dev/null +++ b/src/Exception/Domain/ValidationException.php @@ -0,0 +1,28 @@ + + * @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\Domain; + +use FireHub\Core\Exception\DomainException; + +/** + * ### Domain Validation FireHub Exception + * + * Thrown when input data fails structural or semantic validation rules defined by the system or domain layer. + * + * - Invalid DTO input + * - Missing required fields + * - Type mismatch in value objects + * @since 1.0.0 + */ +abstract class ValidationException extends DomainException {} \ No newline at end of file diff --git a/src/Exception/DomainException.php b/src/Exception/DomainException.php new file mode 100644 index 0000000..3815466 --- /dev/null +++ b/src/Exception/DomainException.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.0 + * @package Core + */ + +namespace FireHub\Core\Exception; + +use Throwable; + +/** + * ### Domain FireHub Exception + * + * Represents violations of business rules or domain invariants. + * + * These exceptions indicate that the operation is logically invalid within the domain context, but not a system failure. + * + * - Invalid state transition + * - Rule violation + * - Constraint failure + * @since 1.0.0 + */ +abstract class DomainException extends FireHubException { + + /** + * ### Constructor + * @since 1.0.0 + * + * @uses \FireHub\Core\Exception\Code::value() As a exception code. + * + * @param string $message [optional]

+ * The Exception message to throw. + *

+ * @param null|\FireHub\Core\Exception\Code $code [optional]

+ * The Exception code. + *

+ * @param null|Throwable $previous [optional]

+ * he previous throwable used for the exception chaining. + *

+ * + * @return void + */ + public function __construct (string $message = '', ?Code $code = null, ?Throwable $previous = null) { + + parent::__construct( + $message, + $code?->value() ?? 0, + $previous + ); + + } + +} \ No newline at end of file diff --git a/src/Exception/FireHubException.php b/src/Exception/FireHubException.php new file mode 100644 index 0000000..df79e14 --- /dev/null +++ b/src/Exception/FireHubException.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 >=7.0 + * @package Core + */ + +namespace FireHub\Core\Exception; + +use Exception, Throwable; + +/** + * ### Base FireHub Exception + * + * Represents a recoverable or expected exceptional condition within the FireHub framework. + * + * All framework-specific exceptions MUST extend this class instead of using \Exception directly. + * @since 1.0.0 + */ +abstract class FireHubException extends Exception { + + /** + * ### Constructor + * @since 1.0.0 + * + * @param string $message [optional]

+ * The Exception message to throw. + *

+ * @param int $code [optional]

+ * The Exception code. + *

+ * @param null|Throwable $previous [optional]

+ * he previous throwable used for the exception chaining. + *

+ * + * @return void + */ + public function __construct (string $message = '', int $code = 0, ?Throwable $previous = null) { + + parent::__construct($message, $code, $previous); + + } + +} \ No newline at end of file diff --git a/src/Exception/Runtime/System/Invariant/InvalidCodeValueException.php b/src/Exception/Runtime/System/Invariant/InvalidCodeValueException.php new file mode 100644 index 0000000..789f552 --- /dev/null +++ b/src/Exception/Runtime/System/Invariant/InvalidCodeValueException.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\Exception\Runtime\System\Invariant; + +use FireHub\Core\Exception\Runtime\System\InvariantException; + +/** + * ### Invalid Code Value Exception + * + * Represents a violation of the invariants required by the FireHub Code Value Object. + * + * This exception is thrown when an invalid value is used to construct or maintain a valid exception code within the + * FireHub exception system. + * + * Typical causes include: + * - Negative error codes + * - Zero values when prohibited by the framework + * - Values outside the supported error code range + * - Any state that would result in an invalid Code Value Object + * + * This exception indicates a programming error or framework contract violation rather than a recoverable business or + * validation failure. + * @since 1.0.0 + */ +class InvalidCodeValueException extends InvariantException {} \ No newline at end of file diff --git a/src/Exception/Runtime/System/InvariantException.php b/src/Exception/Runtime/System/InvariantException.php new file mode 100644 index 0000000..326ae7b --- /dev/null +++ b/src/Exception/Runtime/System/InvariantException.php @@ -0,0 +1,28 @@ + + * @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; + +use FireHub\Core\Exception\Runtime\SystemException; + +/** + * ### Invariant System FireHub Exception + * + * Represents a violation of an internal system or framework invariant within the FireHub ecosystem. + * + * - Invalid format + * - Empty code + * - Illegal state + * @since 1.0.0 + */ +abstract class InvariantException extends SystemException {} \ No newline at end of file diff --git a/src/Exception/Runtime/SystemException.php b/src/Exception/Runtime/SystemException.php new file mode 100644 index 0000000..9d86fb4 --- /dev/null +++ b/src/Exception/Runtime/SystemException.php @@ -0,0 +1,29 @@ + + * @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; + +use FireHub\Core\Exception\RuntimeException; + +/** + * ### System Runtime FireHub Exception + * + * Represents infrastructure or environment-level failures that originate from external systems or framework boundaries. + * + * - File system failure + * - Network failure + * - DB connection failure + * - I/O errors + * @since 1.0.0 + */ +abstract class SystemException extends RuntimeException {} \ No newline at end of file diff --git a/src/Exception/RuntimeException.php b/src/Exception/RuntimeException.php new file mode 100644 index 0000000..2098110 --- /dev/null +++ b/src/Exception/RuntimeException.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.0 + * @package Core + */ + +namespace FireHub\Core\Exception; + +use Throwable; + +/** + * ### Runtime FireHub Exception + * + * Represents unexpected runtime failures that occur during execution but are not related to business logic or validation. + * + * - Service unavailable + * - Unexpected null state + * - Internal computation failure + * @since 1.0.0 + */ +abstract class RuntimeException extends FireHubException { + + /** + * ### Constructor + * @since 1.0.0 + * + * @uses \FireHub\Core\Exception\Code::value() As a exception code. + * + * @param string $message [optional]

+ * The Exception message to throw. + *

+ * @param null|\FireHub\Core\Exception\Code $code [optional]

+ * The Exception code. + *

+ * @param null|Throwable $previous [optional]

+ * he previous throwable used for the exception chaining. + *

+ * + * @return void + */ + public function __construct (string $message = '', ?Code $code = null, ?Throwable $previous = null) { + + parent::__construct( + $message, + $code?->value() ?? 0, + $previous + ); + + } + +} \ No newline at end of file diff --git a/src/Exception/SecurityException.php b/src/Exception/SecurityException.php new file mode 100644 index 0000000..08e51dc --- /dev/null +++ b/src/Exception/SecurityException.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.0 + * @package Core + */ + +namespace FireHub\Core\Exception; + +use Throwable; + +/** + * ### Security FireHub Exception + * + * Represents security-related violations such as unauthorized access, permission denial, or integrity violations. + * + * - Unauthorized access + * - Invalid token + * - Forbidden operation + * @since 1.0.0 + */ +abstract class SecurityException extends FireHubException { + + /** + * ### Constructor + * @since 1.0.0 + * + * @uses \FireHub\Core\Exception\Code::value() As a exception code. + * + * @param string $message [optional]

+ * The Exception message to throw. + *

+ * @param null|\FireHub\Core\Exception\Code $code [optional]

+ * The Exception code. + *

+ * @param null|Throwable $previous [optional]

+ * he previous throwable used for the exception chaining. + *

+ * + * @return void + */ + public function __construct (string $message = '', ?Code $code = null, ?Throwable $previous = null) { + + parent::__construct( + $message, + $code?->value() ?? 0, + $previous + ); + + } + +} \ No newline at end of file diff --git a/src/Type/Exception/ValueObjectException.php b/src/Type/Exception/ValueObjectException.php new file mode 100644 index 0000000..a8661f8 --- /dev/null +++ b/src/Type/Exception/ValueObjectException.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 >=7.0 + * @package Core + */ + +namespace FireHub\Core\Type\Exception; + +use FireHub\Core\Exception\Runtime\System\InvariantException; + +/** + * ### Value Object invariant violation + * + * Thrown when a Value Object breaks its defined invariant rules. + * + * This exception indicates a programming contract violation inside the Value Object layer, meaning the object has + * been constructed or mutated with an invalid state that is not allowed under its invariants. + * @since 1.0.0 + */ +class ValueObjectException extends InvariantException {} \ No newline at end of file diff --git a/src/Type/ValueObject.php b/src/Type/ValueObject.php index 34f0ba8..d69f879 100644 --- a/src/Type/ValueObject.php +++ b/src/Type/ValueObject.php @@ -13,6 +13,9 @@ namespace FireHub\Core\Type; +use FireHub\Core\Exception\FireHubException; +use FireHub\Core\Type\Exception\ValueObjectException; + /** * ### Base Value Object * @@ -87,14 +90,29 @@ final public function sameAs (self $other):bool { * @param callable():bool $condition

* The validation condition to evaluate. *

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

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

* Exception to be thrown when the condition fails. *

+ * + * @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 */ final protected function guard (callable $condition, callable $exception):void { - if ($condition() === false) throw $exception(); + if ($condition() === false) { + + $e = $exception(); + + if (!$e instanceof FireHubException) + throw new ValueObjectException( + 'Guard exception must return instance of FireHubException.' + ); + + throw $e; + + } } diff --git a/tests/Stubs/Exception/DummyDomainException.php b/tests/Stubs/Exception/DummyDomainException.php new file mode 100644 index 0000000..7cc8508 --- /dev/null +++ b/tests/Stubs/Exception/DummyDomainException.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\Tests\Core\Stubs\Exception; + +use FireHub\Core\Exception\DomainException; + +/** + * ### Dummy Domain Exception + * @since 1.0.0 + */ +class DummyDomainException extends DomainException {} \ No newline at end of file diff --git a/tests/Stubs/Exception/DummyException.php b/tests/Stubs/Exception/DummyException.php new file mode 100644 index 0000000..513700e --- /dev/null +++ b/tests/Stubs/Exception/DummyException.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\Tests\Core\Stubs\Exception; + +use FireHub\Core\Exception\FireHubException; + +/** + * ### Dummy Exception + * @since 1.0.0 + */ +class DummyException extends FireHubException {} \ No newline at end of file diff --git a/tests/Stubs/Exception/DummyRuntimeException.php b/tests/Stubs/Exception/DummyRuntimeException.php new file mode 100644 index 0000000..98bd3a3 --- /dev/null +++ b/tests/Stubs/Exception/DummyRuntimeException.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\Tests\Core\Stubs\Exception; + +use FireHub\Core\Exception\RuntimeException; + +/** + * ### Dummy Runtime Exception + * @since 1.0.0 + */ +class DummyRuntimeException extends RuntimeException {} \ No newline at end of file diff --git a/tests/Stubs/Exception/DummySecurityException.php b/tests/Stubs/Exception/DummySecurityException.php new file mode 100644 index 0000000..45e67e1 --- /dev/null +++ b/tests/Stubs/Exception/DummySecurityException.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\Tests\Core\Stubs\Exception; + +use FireHub\Core\Exception\SecurityException; + +/** + * ### Dummy Security Exception + * @since 1.0.0 + */ +class DummySecurityException extends SecurityException {} \ No newline at end of file diff --git a/tests/Stubs/Type/DummyIntVO.php b/tests/Stubs/Type/DummyIntVO.php index 28537cb..78cfa77 100644 --- a/tests/Stubs/Type/DummyIntVO.php +++ b/tests/Stubs/Type/DummyIntVO.php @@ -14,7 +14,7 @@ namespace FireHub\Tests\Core\Stubs\Type; use FireHub\Core\Type\ValueObject; -use InvalidArgumentException; +use FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodeValueException; /** * ### Dummy int Value Object @@ -36,7 +36,7 @@ public function __construct ( $this->guard( fn() => $this->value > 0, - fn() => new InvalidArgumentException('Value must be positive.') + fn() => new InvalidCodeValueException('Value must be positive.') ); } diff --git a/tests/Stubs/Type/DummyStringVO.php b/tests/Stubs/Type/DummyStringVO.php index a4e9be0..e37ecc5 100644 --- a/tests/Stubs/Type/DummyStringVO.php +++ b/tests/Stubs/Type/DummyStringVO.php @@ -14,7 +14,7 @@ namespace FireHub\Tests\Core\Stubs\Type; use FireHub\Core\Type\ValueObject; -use InvalidArgumentException; +use FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodeValueException; /** * ### Dummy string Value Object @@ -36,7 +36,7 @@ public function __construct ( $this->guard( fn() => $this->value !== '', - fn() => new InvalidArgumentException('Value cannot be empty.') + fn() => new InvalidCodeValueException('Value cannot be empty.') ); } diff --git a/tests/Unit/Exception/CodeTest.php b/tests/Unit/Exception/CodeTest.php new file mode 100644 index 0000000..e01b940 --- /dev/null +++ b/tests/Unit/Exception/CodeTest.php @@ -0,0 +1,72 @@ + + * @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\Tests + */ + +namespace FireHub\Tests\Core\Unit\Exception; + +use FireHub\Testing\FireHubTestCase; +use FireHub\Core\Exception\Code; +use FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodeValueException; +use PHPUnit\Framework\Attributes\ { + CoversClass, Group, Small, TestWith +}; + +/** + * ### Test Error code value object + * @since 1.0.0 + */ +#[Small] +#[Group('exception')] +#[CoversClass(Code::class)] +final class CodeTest extends FireHubTestCase { + + /** + * @since 1.0.0 + * + * @param int $value + * + * @throws \FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodeValueException + * @throws \FireHub\Core\Exception\FireHubException + * @throws \FireHub\Core\Type\Exception\ValueObjectException + * + * @return void + */ + #[TestWith([10])] + #[TestWith([0])] + public function testValue (int $value):void { + + $code = new Code($value); + + self::assertSame($value, $code->value()); + + } + + /** + * @since 1.0.0 + * + * @param int $value + * + * @throws \FireHub\Core\Exception\FireHubException + * @throws \FireHub\Core\Type\Exception\ValueObjectException + * + * @return void + */ + #[TestWith([-1])] + public function testCreateWithInvalidValue (int $value):void { + + $this->expectException(InvalidCodeValueException::class); + + new Code($value); + + } + +} \ No newline at end of file diff --git a/tests/Unit/Exception/DomainExceptionTest.php b/tests/Unit/Exception/DomainExceptionTest.php new file mode 100644 index 0000000..2b90207 --- /dev/null +++ b/tests/Unit/Exception/DomainExceptionTest.php @@ -0,0 +1,63 @@ + + * @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\Tests + */ + +namespace FireHub\Tests\Core\Unit\Exception; + +use FireHub\Testing\FireHubTestCase; +use FireHub\Core\Exception\DomainException; +use FireHub\Core\Exception\Code; +use FireHub\Tests\Core\Stubs\Exception\DummyDomainException; +use PHPUnit\Framework\Attributes\ { + CoversClass, Group, Small, TestWith +}; + +/** + * ### Test Domain FireHub Exception + * @since 1.0.0 + */ +#[Small] +#[Group('exception')] +#[CoversClass(DomainException::class)] +final class DomainExceptionTest extends FireHubTestCase { + + /** + * @since 1.0.0 + * + * @param string $message + * @param int $code + * + * @throws \FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodeValueException + * @throws \FireHub\Core\Exception\FireHubException + * @throws \FireHub\Core\Type\Exception\ValueObjectException + * + * @return void + */ + #[TestWith(['error message', 123])] + #[TestWith(['', 0])] + public function testCreate (string $message, int $code):void { + + $previous = new DummyDomainException('previous'); + + $exception = new DummyDomainException( + $message, + new Code($code), + $previous + ); + + $this->assertSame($message, $exception->getMessage()); + $this->assertSame($code, $exception->getCode()); + $this->assertSame($previous, $exception->getPrevious()); + + } + +} \ No newline at end of file diff --git a/tests/Unit/Exception/FireHubExceptionTest.php b/tests/Unit/Exception/FireHubExceptionTest.php new file mode 100644 index 0000000..a0347c1 --- /dev/null +++ b/tests/Unit/Exception/FireHubExceptionTest.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.0 + * @package Core\Tests + */ + +namespace FireHub\Tests\Core\Unit\Exception; + +use FireHub\Testing\FireHubTestCase; +use FireHub\Core\Exception\FireHubException; +use FireHub\Tests\Core\Stubs\Exception\DummyException; +use PHPUnit\Framework\Attributes\ { + CoversClass, Group, Small, TestWith +}; + +/** + * ### Test Base FireHub Exception + * @since 1.0.0 + */ +#[Small] +#[Group('exception')] +#[CoversClass(FireHubException::class)] +final class FireHubExceptionTest extends FireHubTestCase { + + /** + * @since 1.0.0 + * + * @param string $message + * @param int $code + * + * @return void + */ + #[TestWith(['error message', 123])] + #[TestWith(['', 0])] + public function testCreate (string $message, int $code):void { + + $previous = new DummyException('previous'); + + $exception = new DummyException( + $message, + $code, + $previous + ); + + $this->assertSame($message, $exception->getMessage()); + $this->assertSame($code, $exception->getCode()); + $this->assertSame($previous, $exception->getPrevious()); + + } + + /** + * @since 1.0.0 + * + * @return void + */ + public function testItSupportsExceptionChaining ():void { + + $root = new DummyException('root', 0); + $mid = new DummyException('mid', 0, $root); + $top = new DummyException('top', 0, $mid); + + $this->assertSame($mid, $top->getPrevious()); + $this->assertSame($root, $top->getPrevious()->getPrevious()); + + } + +} \ No newline at end of file diff --git a/tests/Unit/Exception/RuntimeExceptionTest.php b/tests/Unit/Exception/RuntimeExceptionTest.php new file mode 100644 index 0000000..c4c85d7 --- /dev/null +++ b/tests/Unit/Exception/RuntimeExceptionTest.php @@ -0,0 +1,63 @@ + + * @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\Tests + */ + +namespace FireHub\Tests\Core\Unit\Exception; + +use FireHub\Testing\FireHubTestCase; +use FireHub\Core\Exception\RuntimeException; +use FireHub\Core\Exception\Code; +use FireHub\Tests\Core\Stubs\Exception\DummyRuntimeException; +use PHPUnit\Framework\Attributes\ { + CoversClass, Group, Small, TestWith +}; + +/** + * ### Test Runtime FireHub Exception + * @since 1.0.0 + */ +#[Small] +#[Group('exception')] +#[CoversClass(RuntimeException::class)] +final class RuntimeExceptionTest extends FireHubTestCase { + + /** + * @since 1.0.0 + * + * @param string $message + * @param int $code + * + * @throws \FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodeValueException + * @throws \FireHub\Core\Exception\FireHubException + * @throws \FireHub\Core\Type\Exception\ValueObjectException + * + * @return void + */ + #[TestWith(['error message', 123])] + #[TestWith(['', 0])] + public function testCreate (string $message, int $code):void { + + $previous = new DummyRuntimeException('previous'); + + $exception = new DummyRuntimeException( + $message, + new Code($code), + $previous + ); + + $this->assertSame($message, $exception->getMessage()); + $this->assertSame($code, $exception->getCode()); + $this->assertSame($previous, $exception->getPrevious()); + + } + +} \ No newline at end of file diff --git a/tests/Unit/Exception/SecurityExceptionTest.php b/tests/Unit/Exception/SecurityExceptionTest.php new file mode 100644 index 0000000..909dcf0 --- /dev/null +++ b/tests/Unit/Exception/SecurityExceptionTest.php @@ -0,0 +1,63 @@ + + * @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\Tests + */ + +namespace FireHub\Tests\Core\Unit\Exception; + +use FireHub\Testing\FireHubTestCase; +use FireHub\Core\Exception\SecurityException; +use FireHub\Core\Exception\Code; +use FireHub\Tests\Core\Stubs\Exception\DummySecurityException; +use PHPUnit\Framework\Attributes\ { + CoversClass, Group, Small, TestWith +}; + +/** + * ### Test Security FireHub Exception + * @since 1.0.0 + */ +#[Small] +#[Group('exception')] +#[CoversClass(SecurityException::class)] +final class SecurityExceptionTest extends FireHubTestCase { + + /** + * @since 1.0.0 + * + * @param string $message + * @param int $code + * + * @throws \FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodeValueException + * @throws \FireHub\Core\Exception\FireHubException + * @throws \FireHub\Core\Type\Exception\ValueObjectException + * + * @return void + */ + #[TestWith(['error message', 123])] + #[TestWith(['', 0])] + public function testCreate (string $message, int $code):void { + + $previous = new DummySecurityException('previous'); + + $exception = new DummySecurityException( + $message, + new Code($code), + $previous + ); + + $this->assertSame($message, $exception->getMessage()); + $this->assertSame($code, $exception->getCode()); + $this->assertSame($previous, $exception->getPrevious()); + + } + +} \ No newline at end of file diff --git a/tests/Unit/Type/ValueObjectTest.php b/tests/Unit/Type/ValueObjectTest.php index a4682a1..b1c1383 100644 --- a/tests/Unit/Type/ValueObjectTest.php +++ b/tests/Unit/Type/ValueObjectTest.php @@ -47,7 +47,7 @@ public function testEquals (string $a, string $b, bool $expected):void { $a = new DummyStringVO($a); $b = new DummyStringVO($b); - $this::assertEquals($expected, $a->equals($b)); + $this::assertSame($expected, $a->equals($b)); } @@ -67,7 +67,7 @@ public function testSameAs (string $a, string $b, bool $expected):void { $a = new $a; $b = new $b; - $this::assertEquals($expected, $a->sameAs($b)); + $this::assertSame($expected, $a->sameAs($b)); } From f7aca27e9614e5ef6740ff2addd92220e1fc1952 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 25 Jun 2026 10:45:57 +0200 Subject: [PATCH 03/10] Add Codecov CI workflow and configuration for coverage reporting **Details:** - Introduced a GitHub Actions workflow (`Codecov.yml`) to automate code coverage reporting on pull requests targeting `master`, `develop`, and versioned branches (`v*`). - Integrated reusable workflow from the central repository to streamline maintenance and enforce consistency. - Added `codecov.yaml` to configure coverage thresholds: - Set a project-wide target of 70%. - Defined higher coverage targets (80%) for `Exception` and `Type` modules to promote critical code robustness. - Utilized GitHub and Codecov tokens for secure authentication. This enhances the repository with automated coverage tracking, enforces quality targets, and ensures visibility into test reliability across critical components. --- .github/codecov.yaml | 24 ++++++++++++++++++++++++ .github/workflows/Codecov.yml | 21 +++++++++++++++++++++ 2 files changed, 45 insertions(+) create mode 100644 .github/codecov.yaml create mode 100644 .github/workflows/Codecov.yml diff --git a/.github/codecov.yaml b/.github/codecov.yaml new file mode 100644 index 0000000..9457102 --- /dev/null +++ b/.github/codecov.yaml @@ -0,0 +1,24 @@ +coverage: + status: + project: + default: + target: 70% + +component_management: + default_rules: + statuses: + - type: project + target: auto + individual_components: + - component_id: module_exception + name: exception + paths: + - "src/Exception/**" + coverage: + target: 80% + - component_id: module_type + name: type + paths: + - "src/Type/**" + coverage: + target: 80% \ No newline at end of file diff --git a/.github/workflows/Codecov.yml b/.github/workflows/Codecov.yml new file mode 100644 index 0000000..aedcf0e --- /dev/null +++ b/.github/workflows/Codecov.yml @@ -0,0 +1,21 @@ +name: Code Coverage + +on: + pull_request: + branches: + - master + - develop + - 'v*' + +permissions: read-all + +jobs: + build: + uses: The-FireHub-Project/.github/.github/workflows/Codecov.yml@master + with: + phpVersion: '8.5' + phpExtensions: ${{ vars.PHP_EXTENSIONS }} + tools: "phpunit:13.x" + secrets: + GH_TOKEN: ${{ secrets.GH_TOKEN }} + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} \ No newline at end of file From 7ce85d8e39970e38c0d2f9e147180d611ea60a03 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 25 Jun 2026 11:59:24 +0200 Subject: [PATCH 04/10] Update PHPUnit configuration and refine Codecov workflow **Details:** - Enhanced `phpunit.xml` by adding `integration` and `smoke` test suites, expanding the testing scope beyond unit tests. - Updated the Codecov workflow (`Codecov.yml`) to monitor release branches with the pattern `release/v*` instead of `v*`, ensuring consistency with branching conventions. - These changes improve test organization and maintain alignment with the repository's versioning strategy. --- .github/workflows/Codecov.yml | 2 +- phpunit.xml | 6 ++++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/workflows/Codecov.yml b/.github/workflows/Codecov.yml index aedcf0e..8ee4b44 100644 --- a/.github/workflows/Codecov.yml +++ b/.github/workflows/Codecov.yml @@ -5,7 +5,7 @@ on: branches: - master - develop - - 'v*' + - 'release/v*' permissions: read-all diff --git a/phpunit.xml b/phpunit.xml index 27667c4..fc18d34 100644 --- a/phpunit.xml +++ b/phpunit.xml @@ -7,6 +7,12 @@ tests/Unit + + tests/Integration + + + tests/Smoke + From 7aa365828dc7fc3362330e61aade0ee24aa1c11f Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 25 Jun 2026 12:00:57 +0200 Subject: [PATCH 05/10] Add `.gitkeep` files for Smoke and Integration test directories **Details:** - Added `.gitkeep` files to `Core-Standard/tests/Smoke` and `Core-Standard/tests/Integration` directories to ensure the inclusion of empty directories in the repository. - These changes prepare the structure for future development of smoke and integration tests, aligning with the expanded testing strategy outlined in previous commits. --- tests/Integration/.gitkeep | 0 tests/Smoke/.gitkeep | 0 2 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 tests/Integration/.gitkeep create mode 100644 tests/Smoke/.gitkeep diff --git a/tests/Integration/.gitkeep b/tests/Integration/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tests/Smoke/.gitkeep b/tests/Smoke/.gitkeep new file mode 100644 index 0000000..e69de29 From 7bce3f18e477333220a49d59e1375c16a4bafdc5 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 25 Jun 2026 12:35:22 +0200 Subject: [PATCH 06/10] Remove Smoke and Integration test suites from PHPUnit and adjust Codecov workflow **Details:** - Deleted `smoke` and `integration` test suites from `phpunit.xml` as part of simplifying the test structure to focus solely on the `unit` suite. - Updated the Codecov workflow (`Codecov.yml`) to reflect this change by specifying the `suits` parameter as `["unit"]`. - Removed `.gitkeep` files from `tests/Integration` and `tests/Smoke` directories, as these test categories are no longer included. This cleanup streamlines test management and aligns testing and coverage workflows with the current project focus. --- .github/workflows/Codecov.yml | 1 + phpunit.xml | 6 ------ tests/Integration/.gitkeep | 0 tests/Smoke/.gitkeep | 0 4 files changed, 1 insertion(+), 6 deletions(-) delete mode 100644 tests/Integration/.gitkeep delete mode 100644 tests/Smoke/.gitkeep diff --git a/.github/workflows/Codecov.yml b/.github/workflows/Codecov.yml index 8ee4b44..43f8eae 100644 --- a/.github/workflows/Codecov.yml +++ b/.github/workflows/Codecov.yml @@ -16,6 +16,7 @@ jobs: phpVersion: '8.5' phpExtensions: ${{ vars.PHP_EXTENSIONS }} tools: "phpunit:13.x" + suits: '["unit"]' secrets: GH_TOKEN: ${{ secrets.GH_TOKEN }} CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} \ No newline at end of file diff --git a/phpunit.xml b/phpunit.xml index fc18d34..27667c4 100644 --- a/phpunit.xml +++ b/phpunit.xml @@ -7,12 +7,6 @@ tests/Unit - - tests/Integration - - - tests/Smoke - diff --git a/tests/Integration/.gitkeep b/tests/Integration/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/tests/Smoke/.gitkeep b/tests/Smoke/.gitkeep deleted file mode 100644 index e69de29..0000000 From 1eb4f6746966f247ea14d3b7fa7ee5b8b0758034 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 25 Jun 2026 12:36:16 +0200 Subject: [PATCH 07/10] Fix typo in Codecov workflow `suites` parameter **Details:** - Corrected a typo in the `Codecov.yml` file, changing `suits` to `suites` under the Codecov configuration. - Ensures proper functionality and alignment with the expected configuration syntax. --- .github/workflows/Codecov.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/Codecov.yml b/.github/workflows/Codecov.yml index 43f8eae..1d2e0f8 100644 --- a/.github/workflows/Codecov.yml +++ b/.github/workflows/Codecov.yml @@ -16,7 +16,7 @@ jobs: phpVersion: '8.5' phpExtensions: ${{ vars.PHP_EXTENSIONS }} tools: "phpunit:13.x" - suits: '["unit"]' + suites: '["unit"]' secrets: GH_TOKEN: ${{ secrets.GH_TOKEN }} CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} \ No newline at end of file From 2c51ca5940e92053b8662b21f623c4bfeef3c8f7 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 25 Jun 2026 13:15:27 +0200 Subject: [PATCH 08/10] Update README to include CI and Codecov badges for error-exception-base branch **Details:** - Added badges for PHPStan, PHPUnit, and Codecov workflows to the README file. - Linked the badges to their respective GitHub Actions workflows and Codecov report for the `architecture/error-exception-base` branch. - Enhances visibility into CI status and coverage metrics directly from the project documentation. --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 46d0125..d4833d0 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,10 @@ /> +[![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) +

Date: Thu, 25 Jun 2026 13:34:10 +0200 Subject: [PATCH 09/10] Add `DummyVOInvalidGuardException` and `DummyNotFireHubException` stubs with enhanced `ValueObject` exception handling tests **Details:** - Introduced `DummyVOInvalidGuardException` stub for validating value objects with guard clause testing. - Added `DummyNotFireHubException` to simulate custom exception scenarios in tests. - Extended `ValueObjectTest` with a test case for invalid guard clause validation, expecting `ValueObjectException`. - Updated `DummyStringVO` and `DummyIntVO` to include new FireHub-native exception types in their constructors. - These changes expand test coverage, ensure stricter validation, and align tests with the project's exception hierarchy structure. --- .../Exception/DummyNotFireHubException.php | 22 +++++++ tests/Stubs/Type/DummyIntVO.php | 4 ++ tests/Stubs/Type/DummyStringVO.php | 4 ++ .../Type/DummyVOInvalidGuardException.php | 59 +++++++++++++++++++ tests/Unit/Type/ValueObjectTest.php | 16 ++++- 5 files changed, 104 insertions(+), 1 deletion(-) create mode 100644 tests/Stubs/Exception/DummyNotFireHubException.php create mode 100644 tests/Stubs/Type/DummyVOInvalidGuardException.php diff --git a/tests/Stubs/Exception/DummyNotFireHubException.php b/tests/Stubs/Exception/DummyNotFireHubException.php new file mode 100644 index 0000000..009ee71 --- /dev/null +++ b/tests/Stubs/Exception/DummyNotFireHubException.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\Tests\Core\Stubs\Exception; + +use Exception; + +/** + * ### Dummy Not FireHub Exception + * @since 1.0.0 + */ +class DummyNotFireHubException extends Exception {} \ No newline at end of file diff --git a/tests/Stubs/Type/DummyIntVO.php b/tests/Stubs/Type/DummyIntVO.php index 78cfa77..b864cc9 100644 --- a/tests/Stubs/Type/DummyIntVO.php +++ b/tests/Stubs/Type/DummyIntVO.php @@ -28,6 +28,10 @@ * * @param int $value * + * @throws \FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodeValueException + * @throws \FireHub\Core\Exception\FireHubException + * @throws \FireHub\Core\Type\Exception\ValueObjectException + * * @return void */ public function __construct ( diff --git a/tests/Stubs/Type/DummyStringVO.php b/tests/Stubs/Type/DummyStringVO.php index e37ecc5..6664879 100644 --- a/tests/Stubs/Type/DummyStringVO.php +++ b/tests/Stubs/Type/DummyStringVO.php @@ -28,6 +28,10 @@ * * @param string $value * + * @throws \FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodeValueException + * @throws \FireHub\Core\Exception\FireHubException + * @throws \FireHub\Core\Type\Exception\ValueObjectException + * * @return void */ public function __construct ( diff --git a/tests/Stubs/Type/DummyVOInvalidGuardException.php b/tests/Stubs/Type/DummyVOInvalidGuardException.php new file mode 100644 index 0000000..3884f7c --- /dev/null +++ b/tests/Stubs/Type/DummyVOInvalidGuardException.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.2 + * @package Core\Tests + */ + +namespace FireHub\Tests\Core\Stubs\Type; + +use FireHub\Core\Type\ValueObject; +use FireHub\Tests\Core\Stubs\Exception\DummyNotFireHubException; + +/** + * ### Dummy Value Object with invalid guard exception + * @since 1.0.0 + */ +readonly class DummyVOInvalidGuardException extends ValueObject { + + /** + * ### Constructor + * @since 1.0.0 + * + * @param string $value + * + * @throws \FireHub\Tests\Core\Stubs\Exception\DummyException + * @throws \FireHub\Core\Exception\FireHubException + * @throws \FireHub\Core\Type\Exception\ValueObjectException + * + * @return void + */ + public function __construct ( + private string $value = 'default' + ) { + + $this->guard( + fn() => $this->value !== '', + fn() => new DummyNotFireHubException('Value cannot be empty.') + ); + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():string { + + return $this->value; + + } + +} \ No newline at end of file diff --git a/tests/Unit/Type/ValueObjectTest.php b/tests/Unit/Type/ValueObjectTest.php index b1c1383..ae10af6 100644 --- a/tests/Unit/Type/ValueObjectTest.php +++ b/tests/Unit/Type/ValueObjectTest.php @@ -15,8 +15,9 @@ use FireHub\Testing\FireHubTestCase; use FireHub\Core\Type\ValueObject; +use FireHub\Core\Type\Exception\ValueObjectException; use FireHub\Tests\Core\Stubs\Type\ { - DummyIntVO, DummyStringVO + DummyIntVO, DummyStringVO, DummyVOInvalidGuardException }; use PHPUnit\Framework\Attributes\ { CoversClass, Group, Small, TestWith @@ -71,4 +72,17 @@ public function testSameAs (string $a, string $b, bool $expected):void { } + /** + * @since 1.0.0 + * + * @return void + */ + public function testCreateWithInvalidValue ():void { + + $this->expectException(ValueObjectException::class); + + new DummyVOInvalidGuardException(''); + + } + } \ No newline at end of file From b165cfd754dfa80df873ec8a6320b392f535dce5 Mon Sep 17 00:00:00 2001 From: Riddick Date: Thu, 25 Jun 2026 13:47:43 +0200 Subject: [PATCH 10/10] Back to develop README.md --- README.md | 116 ++++++++++++++++-------------------------------------- 1 file changed, 35 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index d4833d0..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%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=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,93 +49,47 @@ Standard provides the base classes, kernel, domain layer, and minimal runtime ut --- -## FireHub Icon Error And Exception Base Abstraction – 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 -This branch introduces the **core error and exception abstraction layer** for the FireHub Core-Standard ecosystem. - -It defines how all framework-level failures are represented, structured, and propagated across the FireHub architecture, establishing a unified foundation for error handling across: - -- Core Standard -- Core Professional -- Core Enterprise -- Runtime Foundation (consumers and execution layer) -- Testing infrastructure - -This is a foundational architectural step that replaces direct dependency on PHP native `\Error` and `\Exception` usage inside FireHub Core. - -## FireHub Icon Architectural Goal - -Establish a **unified FireHub-native error handling model** that: +The `develop` branch is the **primary integration branch** for all ongoing development. -- Separates system-level errors from domain-level exceptions -- Provides consistent inheritance roots for all framework failures -- Decouples FireHub from direct PHP `Throwable` hierarchy usage -- Enables structured and extensible error classification in future layers (Runtime, Adapters, Capabilities) -- Ensures predictable error propagation across all FireHub components +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 -This layer becomes the **contractual foundation** for all error handling inside the FireHub ecosystem. +All **release branches** are created **from `develop`**. -## FireHub Icon Core Concept +## Stability Guarantee -A FireHub Error System is defined as: +❌ No backward compatibility guarantee +❌ APIs may change without notice +❌ Behavior may be incomplete or inconsistent +❌ Breaking changes are expected -> A structured, framework-level abstraction over PHP’s native error and exception system, designed to enforce consistent failure semantics across all architectural layers. +This branch is intended **only for contributors and advanced testers**. -It introduces two primary abstractions: +## FireHub Icon Composer Usage (Not Recommended) -- `FireHub\Core\Error\FireHubError` → system-level and structural failures -- `FireHub\Core\Error\FireHubException` → runtime and domain-level failures +For internal testing only: -Together they form the **FireHub error contract layer**, ensuring all failures are typed, predictable, and architecturally consistent. +```json +{ + "require": { + "the-firehub-project/core-standard": "dev-develop" + } +} +``` +⚠️ Never use dev-develop in production. ## FireHub Icon Authors and Contributors @@ -152,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).