Introduce foundation architectural support

README.md

@@ -22,24 +22,24 @@
   /></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)
+[![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)
 
 <p>
-  <a href="https://github.com/The-FireHub-Project/Core-Standard/commits/develop/">
+  <a href="https://github.com/The-FireHub-Project/Core-Standard/commits/architecture/foundation-support/">
     <img
-      src="https://img.shields.io/github/last-commit/The-FireHub-Project/Core-Standard/develop?style=flat&logo=github&logoColor=959da5&label=last%20commit%20(branch)&labelColor=31373e"
+      src="https://img.shields.io/github/last-commit/The-FireHub-Project/Core-Standard/architecture/foundation-support?style=flat&logo=github&logoColor=959da5&label=last%20commit%20(branch)&labelColor=31373e"
       alt="GitHub last commit (branch)"
   /></a>
-  <a href="https://github.com/The-FireHub-Project/Core-Standard/commits/develop/">
+  <a href="https://github.com/The-FireHub-Project/Core-Standard/commits/architecture/foundation-support/">
     <img
-      src="https://img.shields.io/github/commit-activity/m/The-FireHub-Project/Core-Standard/develop?style=flat&logo=github&logoColor=959da5&label=commit%20activity%20(branch)&labelColor=31373e"
+      src="https://img.shields.io/github/commit-activity/m/The-FireHub-Project/Core-Standard/architecture/foundation-support?style=flat&logo=github&logoColor=959da5&label=commit%20activity%20(branch)&labelColor=31373e"
       alt="GitHub activity (branch)"
   /></a>
-  <a href="https://github.com/The-FireHub-Project/Core-Standard/compare/master...develop/">
+  <a href="https://github.com/The-FireHub-Project/Core-Standard/compare/develop...architecture/foundation-support/">
     <img
-      src="https://img.shields.io/github/commits-difference/The-FireHub-Project/Core-Standard?base=master&head=develop&style=flat&logo=github&logoColor=959da5&label=ahead%20master&labelColor=31373e"
+      src="https://img.shields.io/github/commits-difference/The-FireHub-Project/Core-Standard?base=develop&head=architecture/foundation-support&style=flat&logo=github&logoColor=959da5&label=ahead%20develop&labelColor=31373e"
       alt="GitHub commit difference between two branches"
   /></a>
 </p>
@@ -49,47 +49,98 @@ Standard provides the base classes, kernel, domain layer, and minimal runtime ut
 
 ---
 
-## <img src="https://raw.githubusercontent.com/The-FireHub-Project/the-firehub-project.github.io/master/resources/graphics/icons/firehub.svg" width="15" alt="FireHub Icon"> Development Branch
+## <img src="https://raw.githubusercontent.com/The-FireHub-Project/the-firehub-project.github.io/master/resources/graphics/icons/firehub.svg" width="15" alt="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
+
+<p>
+  <a href="https://github.com/The-FireHub-Project/Core-Standard/pull/14/">
+    <img
+      src="https://img.shields.io/github/pulls/detail/title/The-FireHub-Project/Core-Standard/14?style=flat&logo=github&logoColor=959da5&label=title&labelColor=31373e"
+      alt="GitHub pull request title"
+  /></a>
+  <a href="https://github.com/The-FireHub-Project/Core-Standard/pull/14/">
+    <img
+      src="https://img.shields.io/github/pulls/detail/author/The-FireHub-Project/Core-Standard/14?style=flat&logo=github&logoColor=959da5&labelColor=31373e"
+      alt="GitHub pull request author"
+  /></a>
+  <a href="https://github.com/The-FireHub-Project/Core-Standard/pull/14/">
+    <img
+      src="https://img.shields.io/github/pulls/detail/age/The-FireHub-Project/Core-Standard/14?style=flat&logo=github&logoColor=959da5&labelColor=31373e"
+      alt="GitHub pull request created"
+  /></a>
+  <a href="https://github.com/The-FireHub-Project/Core-Standard/pull/14/">
+    <img
+      src="https://img.shields.io/github/pulls/detail/comments/The-FireHub-Project/Core-Standard/14?style=flat&logo=github&logoColor=959da5&labelColor=31373e"
+      alt="GitHub pull request comments"
+  /></a>
+</p>
+
+### Milestone
+
+<p>
+  <a href="https://github.com/The-FireHub-Project/Core-Standard/milestone/1/">
+    <img
+      src="https://img.shields.io/github/milestones/progress-percent/The-FireHub-Project/Core-Standard/1?style=flat&logo=github&logoColor=959da5&labelColor=31373e"
+      alt="GitHub milestone details"
+  /></a>
+</p>
+
 ## <img src="https://raw.githubusercontent.com/The-FireHub-Project/the-firehub-project.github.io/master/resources/graphics/icons/firehub.svg" width="15" alt="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.
+
+## <img src="https://raw.githubusercontent.com/The-FireHub-Project/the-firehub-project.github.io/master/resources/graphics/icons/firehub.svg" width="15" alt="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
+## <img src="https://raw.githubusercontent.com/The-FireHub-Project/the-firehub-project.github.io/master/resources/graphics/icons/firehub.svg" width="15" alt="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.
 
-## <img src="https://raw.githubusercontent.com/The-FireHub-Project/the-firehub-project.github.io/master/resources/graphics/icons/firehub.svg" width="15" alt="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.
 
 ## <img src="https://raw.githubusercontent.com/The-FireHub-Project/the-firehub-project.github.io/master/resources/graphics/icons/firehub.svg" width="15" alt="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).

src/Type/Boolean.php

@@ -0,0 +1,41 @@
+<?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\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<TValue>
+ */
+abstract readonly class Boolean extends ValueObject {
+
+    /**
+     * @inheritDoc
+     *
+     * @since 1.0.0
+     */
+    abstract public function value ():bool;
+
+}

src/Type/Char.php

@@ -0,0 +1,32 @@
+<?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\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<TValue>
+ */
+abstract readonly class Char extends StringValue {}

src/Type/Str.php

@@ -0,0 +1,42 @@
+<?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\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<TValue>
+ */
+abstract readonly class Str extends StringValue {
+
+    /**
+     * ### Converts the string to the list of Chars
+     * @since 1.0.0
+     *
+     * @return list<\FireHub\Core\Type\Char<non-empty-string>>
+     */
+    abstract public function toChars ():array;
+
+}

src/Type/StringValue.php

@@ -0,0 +1,80 @@
+<?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\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<TValue>
+ */
+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<p>
+     * The encoding to set.
+     * </p>
+     *
+     * @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();
+
+    }
+
+}