Introduce Error and Exception base abstractions

.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%

.github/workflows/Codecov.yml

@@ -0,0 +1,22 @@
+name: Code Coverage
+
+on:
+  pull_request:
+    branches:
+      - master
+      - develop
+      - 'release/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"
+      suites: '["unit"]'
+    secrets:
+      GH_TOKEN: ${{ secrets.GH_TOKEN }}
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

README.md

@@ -22,6 +22,10 @@
   /></a>
 </h1>
 
+[![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)
+
 <p>
   <a href="https://github.com/The-FireHub-Project/Core-Standard/commits/develop/">
     <img

src/Exception/Code.php

@@ -0,0 +1,67 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @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<TValue>
+ */
+final readonly class Code extends ValueObject {
+
+    /**
+     * ### Constructor
+     * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Type\ValueObject::guard() As a guard.
+     *
+     * @param TValue $value <p>
+     * The error code.
+     * </p>
+     *
+     * @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;
+
+    }
+
+}

src/Exception/Domain/ValidationException.php

@@ -0,0 +1,28 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @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 {}

src/Exception/DomainException.php

@@ -0,0 +1,60 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @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] <p>
+     * The Exception message to throw.
+     * </p>
+     * @param null|\FireHub\Core\Exception\Code<non-negative-int> $code [optional] <p>
+     * The Exception code.
+     * </p>
+     * @param null|Throwable $previous [optional] <p>
+     * he previous throwable used for the exception chaining.
+     * </p>
+     *
+     * @return void
+     */
+    public function __construct (string $message = '', ?Code $code = null, ?Throwable $previous = null) {
+
+        parent::__construct(
+            $message,
+            $code?->value() ?? 0,
+            $previous
+        );
+
+    }
+
+}

src/Exception/FireHubException.php

@@ -0,0 +1,50 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @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] <p>
+     * The Exception message to throw.
+     * </p>
+     * @param int $code [optional] <p>
+     * The Exception code.
+     * </p>
+     * @param null|Throwable $previous [optional] <p>
+     * he previous throwable used for the exception chaining.
+     * </p>
+     *
+     * @return void
+     */
+    public function __construct (string $message = '', int $code = 0, ?Throwable $previous = null) {
+
+        parent::__construct($message, $code, $previous);
+
+    }
+
+}

src/Exception/Runtime/System/Invariant/InvalidCodeValueException.php

@@ -0,0 +1,36 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @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 {}

src/Exception/Runtime/System/InvariantException.php

@@ -0,0 +1,28 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @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 {}

src/Exception/Runtime/SystemException.php

@@ -0,0 +1,29 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @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 {}