Repository navigation
Introduce foundation architectural support - #14
Merged
Merged
Conversation
… introduce Core/Foundation concepts **Details:** - Updated all badge links, URLs, and branch references in `README.md` to align with the new `architecture/foundation-support` branch. - Introduced detailed descriptions of Core/Foundation architectural layers, including dependency direction and separation of development responsibilities (Core → Foundation → Runtime). - Added milestones and pull request metadata to improve visibility of ongoing development efforts. - Expanded documentation to clarify goals for the Core layer: define stable architectural contracts while delegating developer-facing APIs to the Foundation layer. - Removed outdated or redundant sections for improved clarity and relevance. This update improves the consistency, readability, and alignment of the README with the FireHub project's evolving architecture and development practices.
dieselxxx
added
the
type: Architecture
Closed
2 tasks done
Closed
2 tasks done
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
dieselxxx
changed the title
architecture/foundation-support branch and…**Details:** - Introduced an abstract `Str` class in `Core-Standard/src/Type/Str.php` to define the foundational string-based Value Object type within the FireHub ecosystem. - Implements immutable string value semantics while serving as the base for domain-specific string extensions in higher-level layers (e.g., Foundation). - Provides a clear contract for string handling with its abstract `value(): string` method. - Aligns with the Core layer's goal of ensuring stable architectural contracts and PHP compatibility (`>=8.2`). This addition enhances the modularity and type safety of Core string operations, ensuring future extensibility and clear separation of responsibilities.
…h encoding support **Details:** - Added `Str::encoding()` and `Str::withEncoding()` methods in `Core-Standard/src/Type/Str.php` to provide string encoding introspection and mutation via an `Encoding` value object. Improves versatility for handling internationalization and character encoding scenarios. - Updated `ValueObject::equals()` in `Core-Standard/src/Type/ValueObject.php` to utilize `comparisonValue()` for equality checks, ensuring consistency in comparison logic across all Value Object subclasses. - Introduced protected `comparisonValue()` method in `ValueObject` to centralize comparison logic by delegating to the underlying value representation. - Adjusted `@uses` annotations in `ValueObject` doc comments for better clarity and alignment with new comparison logic. These updates enhance both the flexibility of the `Str` class for encoding management and the reliability of `ValueObject` comparison semantics, contributing to a more robust Core layer architecture.
**Details:** - Extended `Str` base Value Object to implement PHP's native `Stringable` interface, ensuring compatibility with type hints requiring `Stringable` in PHP `>=8.0`. - Introduced the `__toString()` method in `Str` to provide a native string representation of its value. This method utilizes `value()` for consistent output. - Updated class imports and doc comments to reflect the addition of the `Stringable` dependency and enhanced functionality. These changes enhance the interoperability of the `Str` class with both internal and external PHP components, improving compatibility and usability within the FireHub ecosystem.
…d `Char` type **Details:** - Extracted encoding-aware functionality from `Str` into a new `StringValue` abstract class in `Core-Standard/src/Type/StringValue.php`, preserving the immutable string value semantics. - Updated `Str` in `Core-Standard/src/Type/Str.php` to extend `StringValue`, simplifying its structure for domain-specific usage and aligning with Core's modular architecture. - Added `Char` abstract class in `Core-Standard/src/Type/Char.php` to define the base for character-based Value Objects. Ensures support for handling single characters with encoding awareness. - Updated class hierarchy to establish clear separation of concerns between general `StringValue` contracts and domain-specific `Str` and `Char` implementations. These changes enhance the modularity and extensibility of the Core layer, simplifying future extensions and reinforcing separation of architectural responsibilities.
…ar` objects **Details:** - Introduced an abstract `toChars(): array` method in the `Str` class within `Core-Standard/src/Type/Str.php`. - Provides a mechanism to split the immutable string value into a list of `Char<non-empty-string>` objects. - Enhances the extensibility of the `Str` class for character-level operations, aligning with the FireHub ecosystem's focus on modularity and type safety. This update lays the groundwork for fine-grained string manipulations, improving support for encoding-aware scenarios and future extensions.
**Details:** - Introduced an abstract `Boolean` class in `Core-Standard/src/Type/Boolean.php` to define the foundational boolean-based Value Object type within the FireHub ecosystem. - Implements immutable boolean value semantics while serving as the base for domain-specific boolean extensions in higher-level layers (e.g., Foundation). - Provides a clear contract for boolean handling with its abstract `value(): bool` method. - Aligns with the Core layer's focus on defining stable architectural contracts and PHP type safety (`>=8.2`). This addition strengthens the modularity, type safety, and extensibility of the Core layer, ensuring clarity and consistency for boolean-related operations within the FireHub project.
**Details:** - Deleted the `Decimal` abstract class in `Core-Standard/src/Type/Number/Decimal.php`, initially designed as an immutable floating-point value object. - The removal reflects a decision to streamline numeric type abstractions, reducing redundancy while aligning Core's scope with clearer architectural priorities. - Cleans up unused functionality and simplifies the Core layer's numeric type hierarchy. This change eliminates unnecessary complexity, ensuring a leaner and more focused Core architecture within the FireHub ecosystem.
**Details:** - Introduced abstract `isTrue(): bool` and `isFalse(): bool` methods in the `Boolean` class within `Core-Standard/src/Type/Boolean.php`. - Provides explicit contracts for checking boolean value states, improving clarity and semantic expressiveness in boolean handling. - Reinforces the immutability and type safety principles of the `Boolean` Value Object, aligning with the FireHub Core's design philosophy. This update enhances the usability and readability of the `Boolean` base class while paving the way for consistent boolean state-checking operations.
**Details:** - Introduced an abstract `codepoint(): int` method in the `Char` class within `Core-Standard/src/Type/Char.php`. - Defines a contract for retrieving the Unicode code point of a character, returning a non-negative integer. - Enhances the extensibility of the `Char` class for character-level operations, aligning with the modular and type-safe design principles of the FireHub Core. This addition improves support for fine-grained character processing while maintaining the immutability and clarity of the `Char` Value Object.
…ar` contract **Details:** - Added a new `Codepoint` class (`Core-Standard/src/Type/Char/Codepoint.php`) to represent immutable Unicode code points, incorporating validation for valid scalar values within the range of U+0000 to U+10FFFF (excluding surrogates). - Created an `InvalidCodepointException` class for handling invalid Unicode code point scenarios. - Updated the `Char` class (`Core-Standard/src/Type/Char.php`) to return a `Codepoint` object through its `codepoint()` method, enhancing the type safety and extensibility of the `Char` Value Object. - Removed unnecessary `final` keyword from the `Code` class definition to ensure alignment with extensibility policies. These changes provide robust Unicode handling within the Core layer while reinforcing the immutability and clarity principles of value object design in the FireHub ecosystem.
**Details:** - Added `isPositive(): bool`, `isNegative(): bool`, and `isZero(): bool` methods to the `Number` base class in `Core-Standard/src/Type/Number.php` for checking numeric states. - Introduced abstract methods `isFinite(): bool`, `isInfinite(): bool`, and `isNaN(): bool` to the `Real` class in `Core-Standard/src/Type/Number/Real.php`. - Enhances the extensibility and semantic clarity of numeric value objects, ensuring robust type-safe contracts for numeric state evaluations in the FireHub Core. These enhancements align with the FireHub ecosystem's focus on immutability, clarity,
…able interface Introduced `InvalidIntervalTimespanException` class to handle cases of invalid interval timespans. Updated the `Interval` abstract class to implement the `Enumerable` interface and refined its type template for improved type safety and extensibility."
…bilities **Details:** - Introduced the `Concatenable` interface in `Core-Standard/src/Boundary/Capability/Transformation/Concatenable.php`: - Defines the `concat(iterable $values): static` method for creating a new instance containing concatenated values while preserving iteration order. - Enhances the ecosystem with support for non-mutative concatenation of data structures. - Added the `Mergeable` interface in `Core-Standard/src/Boundary/Capability/Transformation/Mergeable.php`: - Defines the `merge(iterable $values): static` method for producing a new instance containing merged key-value associations, replacing conflicting keys with values from the provided source. - Promotes flexibility and
**Details:** - Introduced the `KeyMappable` interface in `Core-Standard/src/Boundary/Capability/Transformation/KeyMappable.php`: - Defines the method `mapKeys(callable $callback): static` for transforming keys of a data structure while preserving associated values. - Supports handling of key collisions when transforming multiple keys into a single key. - Enhances the FireHub Core ecosystem with flexible, reusable design for key mapping transformations, promoting non-mutative operations and adherence to modern PHP standards.
…apabilities **Details:** - Introduced the `IndexReplacement` interface in `Core-Standard/src/Boundary/Capability/Mutation/IndexReplacement.php`: - Defines the `replace(int $index, mixed $value): MutationOutcome` method for replacing values at specific integer indices without altering the data structure. - Ensures compliance with non-creation and non-removal constraints by preserving the structure and reporting `NOT_FOUND` for invalid indices. - Added the `KeyReplacement` interface in `Core-Standard/src/Boundary/Capability/Mutation/KeyReplacement.php`: - Implements the `replace(mixed $key, mixed $value): MutationOutcome` method for updating values associated with a key while maintaining the keyed structure. - Guards against key creation or removal and returns `NOT_FOUND` for nonexistent keys. - Enhances the FireHub Core ecosystem by introducing standardized mutation interfaces for index-based and key-based replacement, adhering to modern PHP design principles and ensuring extensibility.
**Details:** - Introduced the `RandomSelectable` interface in `Core-Standard/src/Boundary/Capability/Query/RandomSelectable.php`: - Defines the `random(): Maybe<TValue>` method to select a single random value without modifying the data structure. - Adds the `sample(int $size): static` method to select a random sample of values, ensuring values are selected without replacement. - Updated PHPDoc for precision in method descriptions. - Refined documentation in the `KeyMappable` interface, revising language for clarity and conciseness. - Enhances the FireHub Core ecosystem with standardized random selection capabilities and improved documentation for key transformation operations.
**Details:** - Updated the PHPDoc of the `random` method in the `RandomSelectable` interface to include `mixed` in the return type: `Maybe<TValue|mixed>`. - Enhances flexibility by allowing the method to accommodate a broader range of value types, improving compatibility across use cases. - Aligns with FireHub Core's commitment to robust and reusable interface design.
**Details:** - Introduced the `Entry` class in `Core-Standard/src/Type/DataStructure/Map/Entry.php`: - Represents immutable key-value associations as standalone value objects. - Includes a strongly typed `value()` method returning an array with `key` and `value`. - Enhances the FireHub Core ecosystem with a dedicated, reusable abstraction for key-value pairs, promoting immutability and robust design practices.
…ure classification **Details:** - Introduced the `Hierarchical` interface in `Core-Standard/src/Boundary/Type/DataStructure/Classification/Hierarchical.php`: - Defines a classification for data structures organized hierarchically through parent-child relationships. - Focuses on organizational topology without imposing constraints on representation, traversal, or storage. - Added the `Tree` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Tree.php`: - Implements `Hierarchical` and extends the `Collection` interface. - Defines the structure of a tree as a hierarchical, acyclic collection, organizing elements with a single root, parent-child relationships, and leaf nodes for elements without children. - Does not prescribe branching factors, traversal strategies, balancing, or mutation behaviors. - Enhances the FireHub Core ecosystem with flexible, reusable abstractions for hierarchical data structures, promoting extensibility and robust design practices.
**Details:** - Introduced hierarchical interface capabilities in the `Core-Standard` module. - Added the following interfaces for flexible and reusable data structure design: - `AncestorIteration` and `DescendantIteration` for traversing hierarchical structures. - `RootAccess` and `ChildAccess` for accessing key structural elements. - `Depth` and
**Details:** - Cleaned up formatting in the `use` statement block by removing an extra trailing comma. - Maintains codebase consistency and improves readability without functional changes.
…nforce type safety **Details:** - Updated the `descendants` and `ancestors` method signatures to accept a `Node` type instead of `mixed`. - Added `use FireHub\Core\Boundary\Type\DataStructure\Collection\Tree\Node` statements to both interfaces for proper type reference. - Improves consistency and ensures stricter type checking in hierarchical traversal capabilities."
**Details:** - Updated `Tree.php` to include `Depth` and `Height` capabilities for measuring tree structure properties. - Enhanced the `Tree` interface by appending `Depth` and `Height` to its list of implemented capabilities. - Improves the flexibility of hierarchical data structures by enabling depth and height measurement features."
…ation` **Details:** - Introduced the `SiblingIteration` interface in `Core-Standard/src/Boundary/Capability/SiblingIteration.php`: - Defines the `siblings(Node $node): iterable` method for iterating over sibling nodes within a hierarchical structure. - Excludes the specified node itself and ensures root nodes are excluded as they have no siblings. - Enhances hierarchical traversal capabilities by introducing sibling-specific iteration. - Updated PHPDoc in `DescendantIteration`: - Refined multi-line format of the `@return` annotation for readability and consistency. - Improved documentation clarity for descendant iteration in pre-order depth-first traversal. - Elevates the FireHub Core ecosystem’s support for hierarchical structures with an expanded and well-documented API.
**Details:** - Extended the `Tree` interface to include the `SiblingIteration` capability for iterating over sibling nodes in hierarchical structures. - Updated PHPDoc annotations to reflect the addition of `SiblingIteration`. - Enhances hierarchical data traversal by supporting sibling-level iteration, improving flexibility in tree-based operations.
**Details:** - Deleted the following interfaces and abstractions related to hierarchical data structures: - `Tree`, `Node`, `AncestorIteration`, `DescendantIteration`, `SiblingIteration` - `RootAccess`, `ChildAccess` - `Depth`, `Height` - Removed corresponding PHPDoc annotations and type references across the deleted files. - This change simplifies the FireHub Core ecosystem by eliminating unused or redundant hierarchical capabilities from the codebase.
**Details:** - Introduced the `Searchable` interface in `Core-Standard/src/Boundary/Capability/Query/Searchable.php`: - Defines the `search(mixed $value): mixed` method for locating values within a data structure. - Returns a search result if a match exists or `null` otherwise. - Promotes flexibility by not enforcing specific search, comparison, or result representation logic. - Includes support for customizable value (`TValue`) and result (`TResult`) types. - Enhances the FireHub Core ecosystem with a reusable abstraction for value search capabilities.
**Details:** - Added the `use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear` statement to `Stream.php`. - Prepares the `Stream` data structure to utilize the `Linear` classification for future enhancements or functionality.
**Details:** - Moved `use FireHub\Core\Boundary\Type\DataStructure\Classification\Linear` to follow alphabetical order within import statements. - Improves code readability and maintains consistency in import organization across the codebase.
…ate references**
- **Changes**:
- Renamed `InvalidUtf8Exception` to `InvalidEncodingException` in the `Foundation\Str\Exception` namespace:
- The new class now represents errors related to invalid string encodings more broadly, not limited to UTF-8.
- Refactored references in the `Utf8` class:
- Updated exceptions thrown when invalid string encoding or content is detected.
- **Rationale**:
- Generalizes exception handling to support broader encoding-related errors beyond UTF-8.
- Aligns naming conventions with increased flexibility for encoding-related validations.
- Enhances clarity and future maintainability by deprecating an overly specific exception.
- **Details**:
- Introduced the `IndexInsertion` interface in `Core-Standard/src/Boundary/Capability/Mutation/IndexInsertion.php`:
- Defines the `insertAt(int $index, mixed $value): MutationOutcome` method for inserting values at a specific index within an ordered collection.
- Supports prepending, appending, or inserting at valid indices while maintaining order and shifting elements.
- Returns a `MutationOutcome` to indicate whether the insertion was successful (`CREATED`) or failed due to an invalid index (`NOT_FOUND`).
- Incorporates comprehensive PHPDoc annotations outlining usage, behavior, and constraints.
- **Rationale**:
- Adds a reusable abstraction for index-based insertion to the FireHub Core ecosystem.
- Enables standardized, clear, and extensible handling of ordered collection modifications.
- Improves maintainability and future scaling with a modular design pattern.
- **Details**:
- Introduced the `Insertion` interface in `Core-Standard/src/Boundary/Capability/Mutation/Insertion.php`:
- Defines the `insert(mixed ...$values): void` method for inserting one or more values into a data structure.
- Leaves the positioning of inserted values up to the organizational rules of the implementing structure.
- Includes comprehensive PHPDoc annotations outlining usage, behavior, and constraints.
- Provides a flexible abstraction to handle generic data structure insertions while adhering to their internal rules.
- **Rationale**:
- Enhances the FireHub Core ecosystem with a reusable interface for general data insertion operations.
- Promotes modularity and extensibility for future-proof data structure handling.
- Lays a strong foundation for standardized mutation capabilities across various structures.
**Details**: - Introduced the `Heap` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Heap.php`: - Defines a heap data structure, focusing on maintaining priority relationships between elements. - Supports extensibility for specialized heap implementations by abstracting branching factors, comparison strategies, and ordering semantics. - Implements key characteristics of hierarchical and collection-based structures with front-access capabilities. - Introduced the `PriorityQueue` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/PriorityQueue.php`: - Defines a priority queue, where retrieval order is determined by element priority rather than insertion order. - Abstracts priority assignment, comparison, and ordering without requiring specific internal representations. - Implements key characteristics of linear and collection-based structures with front-access capabilities. **Rationale**: - Expands the FireHub Core ecosystem with abstractions for two critical data structures to support priority-based organization and access. - Improves modularity, enabling developers to build reusable and extensible heap and priority queue implementations in conformance with shared boundaries. - Establishes a strong groundwork for future extensions, operational constraints, and specialized prioritization rules.
**Details**: - Introduced the `Entry` class in `Core-Standard/src/Type/DataStructure/PriorityQueue/Entry.php`: - Represents an immutable priority-value association for use in priority queues. - Implements a strongly typed value object to maintain a priority and its associated value as a single unit. - Includes methods to retrieve the priority and value pair in array format. - Enhances the modularity and clarity of the `PriorityQueue` abstraction by providing a dedicated implementation for priority-value entries.
**Details**: - Updated branch references in README badges from `architecture/foundation-support` to `develop`: - Includes badges for PHPStan, PHPUnit, Codecov, and GitHub activity. - Adjusted commit comparison links to reflect `master` vs. `develop` instead of `develop` vs. `architecture/foundation-support`. - Reorganized branch documentation: - Clarified the purpose and stability guarantees of the `develop` branch. - Removed outdated milestones, pull request details, and related branch information. - Condensed architectural notes and shifted focus to `develop` as the main integration branch. - Improved clarity and alignment between README content and current branch structure.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🧱 System Design / Architecture Pull Request
Related Issue
Closes Introduce runtime foundation architectural support #12
Description
Define the architectural support required for the FireHub Foundation layer by introducing Core-level contracts for high-level abstractions.
Establish the system boundary between Core, Runtime, and Foundation:
This architecture is required to prevent Core components from depending directly on Foundation implementations while still allowing Core Value Objects, contracts, and framework components to reference fundamental high-level concepts.
The decision ensures that FireHub maintains a clean dependency direction:
Application
↓
Foundation
↓
Core Contracts
↑
Runtime
Affected Components
Core
Runtime
Foundation
Adapter
Capability
Architectural Rule
Core contracts MUST define only the minimum required behavior of an abstraction.
High-level APIs, fluent methods, transformations, and developer conveniences MUST remain in Foundation.
This separation allows FireHub to evolve Core, Runtime, and Foundation independently while preserving a stable architectural foundation.
Architecture Overview
System Design
Design Decisions
System Boundaries
Included
Excluded
Implementation
Core Changes
Contracts
Dependencies
Validation
Architecture Compliance
Build & Stability
Impact Analysis
Core Impact
Runtime Impact
Future Extensions
Risks / Constraints
Risk Level
Potential Risks
Documentation
Checklist
Notes
Technical Notes
Future Work
Reviewer Guidance