PHPackages                             orivex-x/php-composables - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. orivex-x/php-composables

ActiveLibrary[Framework](/categories/framework)

orivex-x/php-composables
========================

A modular, reactive, versioned PHP workflow framework

1.0.0(6mo ago)00MITPHPPHP >=8.2CI passing

Since Nov 17Pushed 6mo agoCompare

[ Source](https://github.com/Orivex-x/php-composables)[ Packagist](https://packagist.org/packages/orivex-x/php-composables)[ RSS](/packages/orivex-x-php-composables/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (3)Versions (2)Used By (0)

PHP Composables
===============

[](#php-composables)

[![PHP](https://camo.githubusercontent.com/fff68409e83d3ed7aa0b378c76366d72fa0fb1f875467162ce208929b7e753a7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e32253230253743253230382e33253230253743253230382e342d626c75652e737667)](#)[![CI](https://github.com/orivex-x/php-composables/actions/workflows/ci.yml/badge.svg)](https://github.com/orivex-x/php-composables/actions/workflows/ci.yml)[![Coverage](https://camo.githubusercontent.com/1bfaa8ba7b3a8e03ece5b582a536b90cf31918a75e4df0e8de256afd2670adb3/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f6f72697665782d782f7068702d636f6d706f7361626c65732e737667)](https://codecov.io/gh/orivex-x/php-composables)[![Packagist Version](https://camo.githubusercontent.com/44b3978737951d8ed6886661a73671b4c743f8be31c553f2d0dbfafebe2baa7d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f72697665782d782f7068702d636f6d706f7361626c65732e737667)](https://packagist.org/packages/orivex-x/php-composables)[![License](https://camo.githubusercontent.com/e1b5f88d6f4d261b38c8ee2b14d539c0bc7326c3838e5ece1c62be06c6e1f5d8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6f72697665782d782f7068702d636f6d706f7361626c65732e737667)](LICENSE)[![Total Downloads](https://camo.githubusercontent.com/b9f913ff2aaebd39cfefff60cc7f6682de9e3b15e310c326a761655e6f9dcb01/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f72697665782d782f7068702d636f6d706f7361626c65732e737667)](https://packagist.org/packages/orivex-x/php-composables)

Overview
--------

[](#overview)

PHP Composables is a modular, reactive, and event-driven framework for PHP that allows developers to build dynamic workflows using composable modules. Each module can define:

- **Inputs & Outputs** - specify required data and its type.
- **Dependencies** - automatically resolved by pipelines.
- **Logic** - core callable that produces outputs from inputs.
- **Hooks** - functions triggered after outputs are produced.
- **Branches** - conditional downstream modules based on outputs.
- **Async Execution** - offload hooks and branches to an asynchronous queue.

Modules can be combined into **pipelines** that handle execution order, versioning, and dependency resolution. PHP Composables also includes an **event system** for monitoring module lifecycle and async operations.

Ideal for microservices, automation, data pipelines, and dynamic web applications.

Requirements
------------

[](#requirements)

- **PHP >= 8.2**
- **Composer 2.x**

Installation
------------

[](#installation)

Install via Composer:

```
composer require orivex-x/php-composables
```

Include Composer autoload in your project:

```
require_once './vendor/autoload.php';
```

Core Concepts
-------------

[](#core-concepts)

### Module

[](#module)

A **Module** is a self-contained unit of work.

**Key Features**:

- **Name & Version**: Each module has a semantic version.
- **Inputs & Outputs**: Enforce data types.
- **Dependencies**: Modules can require other modules.
- **Logic**: Callable function producing outputs.
- **Hooks**: Triggered after outputs are produced.
- **Branches**: Conditional downstream execution.
- **Async Execution**: Hooks and branches can run asynchronously.

### Example

[](#example)

```
use PhpComposables\Module;

$userModule = Module::create("User", "1.0.0")
    ->declareInput("name", "string")
    ->declareOutput("greeting", "string")
    ->setLogic(fn($inputs) => ["greeting" => "Hello, {$inputs['name']}!"])
    ->onOutput("greeting", fn($g) => print("[HOOK] Greeting: $g\n"))
    ->register();
```

ModulePipeline
--------------

[](#modulepipeline)

A **pipeline** composes multiple modules, resolving dependencies and handling execution order.

**Features**:

- Async execution of hooks and branches.
- Force specific module versions.
- Avoid repeated module execution.
- Executes branches conditionally based on outputs.

### Example

[](#example-1)

```
use PhpComposables\ModulePipeline;

$pipeline = ModulePipeline::compose([$userModule])
    ->setAsync() // Enable async hooks & branches
    ->setModuleVersion("User", "1.0.0");

$result = $pipeline->run(["name" =>" '"Alice']);
print_r($result);
```

ModuleRegistry
--------------

[](#moduleregistry)

Central registry for modules and their versions. Retrieve modules by name and optionally by version. If no version is specified, the latest semantic version is returned.

### Example

[](#example-2)

```
use PhpComposables\ModuleRegistry;

$latestUser = ModuleRegistry::get("User");
$authModule = ModuleRegistry::get("Auth", "1.2.0");
```

ModuleAsyncQueue
----------------

[](#moduleasyncqueue)

Handles asynchronous execution for hooks and branches.

**Features**:

- Enqueue tasks with optional schema validation.
- Run queued tasks in order.
- Async validation respects Module::$asyncValidationStrict.
- Emits events for enqueue, run, and errors.

**Important**: Module outputs must match the declared types. Hooks can use `print()` or side effects, but **do not return non-compliant types**.

### Async Hook & Branch Warnings

[](#async-hook--branch-warnings)

When using `Module::$asyncQueue = true`:

- Hooks and branch logic are executed **after the main module run**.
- By default, **validation errors in async hooks/branches will throw exceptions**.
- To make async hooks safer, you can disable strict validation:

```
Module::$asyncValidationStrict = false; // Async validation errors will only warn
```

- Always return type-compliant outputs from async hooks; returning invalid types may cause queue warnings or skipped execution.
- Avoid relying on async hook outputs in the main module run - they execute after the module completes.

### Example

[](#example-3)

```
use PhpComposables\ModuleAsyncQueue;

// Side effect safe callback
ModuleAsyncQueue::enqueue(
    fn($data) => print_r($data),
    ["foo" => "bar"],
    null,
    "hook"
);

// Execute queued tasks
ModuleAsyncQueue::run();
```

ModuleEventDispatcher
---------------------

[](#moduleeventdispatcher)

Dispatches events for module lifecycle and async queue activities.

**Supported Events**:

EventDescriptionmodule.run.startBefore a module executesmodule.run.endAfter a module completesqueue.enqueueWhen an async item is enqueuedqueue.runWhen an async item runs### Example

[](#example-4)

```
use PhpComposables\ModuleEventDispatcher;

ModuleEventDispatcher::listen(ModuleEventDispatcher::EVENT_MODULE_RUN_START, fn($payload) =>
    echo "Module started: {$payload['module']}\n"
);
```

Exception Handling
------------------

[](#exception-handling)

PHP Composables provides specialized exception classes:

- **ModuleException** - errors within a module (logic, hooks, branches)
- **ModuleSchemaException** - errors from the module schema.
- **ModulePipelineException** - errors during pipeline execution
- **ModuleRegistryException** - when retrieving modules fails
- **ModuleAsyncQueueException** - for async queue failures
- **ModuleEventDispatcherException** - for event listener errors

```
try {
    $pipeline->run(["name" => "Alice"]);
} catch (ModuleException $e) {
    echo "Module failed: {$e->getMessage()} in module {$e->getModuleName()}";
}
```

Best Practices
--------------

[](#best-practices)

- Version modules consistently.
- Use hooks for side effects (logging, emails, analytics), not main logic.
- Branch outputs carefully to avoid cycles.
- Async queues are recommended for non-critical tasks.
- Catch ModuleException or ModulePipelineException at the top level.
- **Always return type-compliant outputs** from modules to avoid async queue failures.

Advanced Features
-----------------

[](#advanced-features)

- **Dependency Resolution** - pipelines automatically order modules.
- **Conditional Branching** - modules trigger downstream modules based on outputs.
- **Async Hooks & Branches** - offload non-critical tasks.
- **Event System** - monitor execution and async operations.

Developer Quickstart
--------------------

[](#developer-quickstart)

```