diff --git a/CHANGELOG.md b/CHANGELOG.md index 80941ea..69bd54e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +# [[v0.4.0](https://github.com/The-FireHub-Project/Foundation/compare/v0.3.0...v0.4.0)] – 2026-11-17 + +### Added +* Add Pipeline and Continuation classes for immutable processing chain by @dieselxxx + # [[v0.3.0](https://github.com/The-FireHub-Project/Foundation/compare/v0.2.1...v0.3.0)] – 2026-11-06 ### Added diff --git a/README.md b/README.md index c6f202e..104efca 100644 --- a/README.md +++ b/README.md @@ -12,84 +12,124 @@ /> version GitHub license -[![PHPStan](https://github.com/The-FireHub-Project/Foundation/actions/workflows/PHPStan.yml/badge.svg?branch=develop)](https://github.com/The-FireHub-Project/Foundation/actions/workflows/PHPStan.yml) -[![PHPUnit](https://github.com/The-FireHub-Project/Foundation/actions/workflows/PHPUnit.yml/badge.svg?branch=develop)](https://github.com/The-FireHub-Project/Foundation/actions/workflows/PHPUnit.yml) -[![Codecov](https://codecov.io/gh/The-FireHub-Project/Foundation/branch/develop/graph/badge.svg?token=XW2YEONF51)](https://app.codecov.io/gh/The-FireHub-Project/Foundation/tree/develop) -

- + + GitHub created at + GitHub last commit (branch) - + GitHub activity (branch) - + + GitHub contributors + + GitHub language count + + GitHub top language + GitHub commit difference between two branches + + GitHub code size

-The essential PHP core for building domain-driven, clean architecture applications. -Standard provides the base classes, kernel, domain layer, and minimal runtime utilities needed to start any FireHub project. +Provides the high-level foundation layer of the FireHub ecosystem. This repository contains developer-focused APIs and reusable building blocks that simplify common programming tasks while maintaining consistency, type safety, and architectural principles across FireHub applications. + +The Foundation layer is built on top of the Runtime layer and transforms low-level execution primitives into expressive object-oriented APIs. It provides commonly used components such as string manipulation, date and time handling, mathematical utilities, and other essential application-level abstractions. + +This repository represents the developer-facing layer between the FireHub Runtime and application code, enabling clean, readable, and maintainable PHP development. --- -## FireHub Icon Development Branch +## FireHub Icon Repository Purpose + +FireHub Foundation is the high-level developer API layer of the FireHub ecosystem. + +Built on top of FireHub Runtime, it provides expressive, object-oriented abstractions for common programming tasks. The purpose of this layer is to expose simple, consistent, and powerful APIs while hiding low-level implementation details. -⚠️ **This is the `develop` branch** +Foundation contains reusable building blocks such as: -- Unstable -- APIs may change without notice -- Not intended for production use +- String manipulation APIs +- Date and time handling +- Mathematical utilities +- Common application-level abstractions +- Developer-oriented helper objects -## FireHub Icon Branch Purpose +The Foundation layer follows the FireHub architectural principles by separating responsibilities between definition, execution, and usage: -The `develop` branch is the **primary integration branch** for all ongoing development. +## FireHub Icon Security -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 +For security reporting and guidelines, please refer to our [SECURITY.md](https://github.com/The-FireHub-Project/.github/blob/master/.github/SECURITY.md) file. -All **release branches** are created **from `develop`**. +## FireHub Icon Community -## Stability Guarantee +![GitHub watchers](https://img.shields.io/github/watchers/The-FireHub-Project/Foundation?style=social) +![GitHub Repo stars](https://img.shields.io/github/stars/The-FireHub-Project/Foundation?style=social) +![GitHub forks](https://img.shields.io/github/forks/The-FireHub-Project/Foundation?style=social) -❌ No backward compatibility guarantee -❌ APIs may change without notice -❌ Behavior may be incomplete or inconsistent -❌ Breaking changes are expected +- Be sure to review the [Code of Conduct](https://github.com/The-FireHub-Project/.github/blob/master/.github/CODE_OF_CONDUCT.md). +- Read a [Contributing](https://github.com/The-FireHub-Project/.github/blob/master/.github/CONTRIBUTING.md) file to see how you can contribute to this project. +- Read our [Security policy](https://github.com/The-FireHub-Project/.github/blob/master/.github/SECURITY.md) file to see how you can report a vulnerability. +- Review the project [Governance model](https://github.com/The-FireHub-Project/.github/blob/master/.github/GOVERNANCE.md), including roles, decision-making, RFC process, and releases. -This branch is intended **only for contributors and advanced testers**. +## FireHub Icon Support -## FireHub Icon Composer Usage (Not Recommended) +

+ + GitHub in-progress issues + + GitHub total issues + + GitHub opened pull requests +

-For internal testing only: +For help with FireHub products, please refer to the following resources: -```json -{ - "require": { - "the-firehub-project/foundation": "dev-develop" - } -} -``` -⚠️ Never use dev-develop in production. +- **General questions & discussions**: [GitHub Discussions](https://github.com/orgs/The-FireHub-Project/discussions) +- **Bug reports & issues**: [Support](https://github.com/The-FireHub-Project/Foundation/issues) +- **Documentation & guides**: [FireHub Docs](https://the-firehub-project.github.io) +- **Commercial support** (Pro/Enterprise): contact your account manager ## FireHub Icon Authors and Contributors diff --git a/src/Pipeline.php b/src/Pipeline.php new file mode 100644 index 0000000..e064306 --- /dev/null +++ b/src/Pipeline.php @@ -0,0 +1,108 @@ + + * @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 Foundation + */ + +namespace FireHub\Foundation; + +use FireHub\Core\Boundary\ { + Pipeline as PipelineBoundary, Pipeline\Stage +}; +use FireHub\Foundation\Pipeline\Continuation; +use FireHub\Runtime; +use Closure; + +/** + * ### Executes an immutable processing pipeline + * + * Composes an ordered sequence of processing stages around a terminal handler. + * + * Each stage receives an input value and a continuation representing the remaining execution chain. + * + * Stages may execute logic before or after delegation, transform the input passed downstream, modify the returned + * result, or terminate processing without invoking the continuation. + * + * The execution chain is composed once during construction and reused for later executions. + * + * Pipeline immutability does not guarantee that individual stages or their dependencies are stateless. + * @since 1.0.0 + * + * @template TInput + * @template TOutput + * + * @implements \FireHub\Core\Boundary\Pipeline + */ +final readonly class Pipeline implements PipelineBoundary { + + /** + * ### Composed pipeline handler + * @since 1.0.0 + * + * @var Closure(TInput):TOutput + */ + private Closure $handler; + + /** + * ### Constructor + * @since 1.0.0 + * + * @uses \FireHub\Core\Boundary\Pipeline\Stage::process() To execute a processing stage. + * @uses \FireHub\Runtime\Arr\Transform::reverse() To reverse the provided stages. + * + * @param Closure(TInput):TOutput $handler

+ * Terminal handler executed after all stages delegate. + *

+ * @param \FireHub\Core\Boundary\Pipeline\Stage ...$stages

+ * Processing stages in execution order. + *

+ * + * @return void + */ + public function __construct (Closure $handler, Stage ...$stages) { + + foreach (Runtime\Arr\Transform::reverse($stages) as $stage) { + + $next = new Continuation($handler); + + $handler = static fn(mixed $input):mixed => $stage->process( + $input, + $next + ); + + } + + $this->handler = $handler; + + } + + /** + * ### Executes the pipeline + * + * Passes the provided input to the precomposed execution chain. + * + * Processing stages execute in registration order, provided each preceding stage delegates to its continuation. + * + * If no processing stages were registered, the terminal handler executes directly. + * @since 1.0.0 + * + * @param TInput $input

+ * Input passed to the first processing stage. + *

+ * + * @return TOutput Result produced by the pipeline. + */ + public function handle (mixed $input):mixed { + + return ($this->handler)($input); + + } + +} \ No newline at end of file diff --git a/src/Pipeline/Continuation.php b/src/Pipeline/Continuation.php new file mode 100644 index 0000000..bc1a02f --- /dev/null +++ b/src/Pipeline/Continuation.php @@ -0,0 +1,71 @@ + + * @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 Foundation + */ + +namespace FireHub\Foundation\Pipeline; + +use FireHub\Core\Boundary\Pipeline\Next; +use Closure; + +/** + * ### Represents a pipeline execution continuation + * + * Encapsulates the next executable step within a processing pipeline. + * + * A continuation delegates the received input to its underlying handler and returns the resulting output. + * + * The handler may represent another processing stage or the terminal pipeline handler. + * + * Continuations are immutable and may be invoked multiple times. The execution behavior and state management of + * the underlying handler remain its own responsibility. + * @since 1.0.0 + * + * @template TInput + * @template TOutput + * + * @implements \FireHub\Core\Boundary\Pipeline\Next + */ +final readonly class Continuation implements Next { + + /** + * ### Constructor + * @since 1.0.0 + * + * @param Closure(TInput):TOutput $handler

+ * Handler responsible for executing the next pipeline step. + *

+ * + * @return void + */ + public function __construct ( + private Closure $handler + ) {} + + /** + * ### Executes the continuation + * + * Delegates the provided input to the underlying handler and returns its result. + * @since 1.0.0 + * + * @param TInput $input

+ * Input passed to the next pipeline step. + *

+ * + * @return TOutput Result produced by the handler. + */ + public function handle (mixed $input):mixed { + + return ($this->handler)($input); + + } + +} \ No newline at end of file diff --git a/src/Str/Base.php b/src/Str/Base.php index f13b31e..4d7235e 100644 --- a/src/Str/Base.php +++ b/src/Str/Base.php @@ -542,6 +542,7 @@ public function group (int $number_of_groups):array { */ public function explode (string $separator, int $limit = IntegerLimits::MAX):array { + /** @var list */ return Runtime\Str\SB\Delimiter::explode($this->value, $separator, $limit); } diff --git a/src/Str/Bytes.php b/src/Str/Bytes.php index fbbf5e9..b9c55a5 100644 --- a/src/Str/Bytes.php +++ b/src/Str/Bytes.php @@ -325,6 +325,7 @@ public function group (int $number_of_groups):array { */ public function explode (string $separator, int $limit = IntegerLimits::MAX):array { + /** @var list */ return Runtime\Str\SB\Delimiter::explode($this->value, $separator, $limit); } diff --git a/src/Str/Exception/InvalidAsciiException.php b/src/Str/Exception/InvalidAsciiException.php index b755f24..1cb7824 100644 --- a/src/Str/Exception/InvalidAsciiException.php +++ b/src/Str/Exception/InvalidAsciiException.php @@ -21,6 +21,11 @@ */ final class InvalidAsciiException extends DomainException { + /** + * @inheritdoc + * + * @since 1.0.0 + */ protected const string DEFAULT_MESSAGE = 'Invalid characters in ASCII string'; } \ No newline at end of file diff --git a/src/Str/Exception/InvalidEncodingException.php b/src/Str/Exception/InvalidEncodingException.php index 2848abc..c015874 100644 --- a/src/Str/Exception/InvalidEncodingException.php +++ b/src/Str/Exception/InvalidEncodingException.php @@ -21,6 +21,11 @@ */ final class InvalidEncodingException extends DomainException { + /** + * @inheritdoc + * + * @since 1.0.0 + */ protected const string DEFAULT_MESSAGE = 'Invalid string encoding'; } \ No newline at end of file diff --git a/src/Str/Exception/InvalidPatternException.php b/src/Str/Exception/InvalidPatternException.php index 2cf8a9b..e26e24a 100644 --- a/src/Str/Exception/InvalidPatternException.php +++ b/src/Str/Exception/InvalidPatternException.php @@ -21,6 +21,11 @@ */ final class InvalidPatternException extends RuntimeException { + /** + * @inheritdoc + * + * @since 1.0.0 + */ protected const string DEFAULT_MESSAGE = 'The pattern is not valid'; } \ No newline at end of file diff --git a/src/Str/Exception/PatternOccurrencesNumberException.php b/src/Str/Exception/PatternOccurrencesNumberException.php index 4a5a6ce..7f3ff33 100644 --- a/src/Str/Exception/PatternOccurrencesNumberException.php +++ b/src/Str/Exception/PatternOccurrencesNumberException.php @@ -21,6 +21,11 @@ */ final class PatternOccurrencesNumberException extends RuntimeException { + /** + * @inheritdoc + * + * @since 1.0.0 + */ protected const string DEFAULT_MESSAGE = 'The pattern occurrences number is not valid'; } \ No newline at end of file