Download the PHP package omnitech-solutions/flowlight without Composer

Flowlight — LightService‑style Guide

Table of Contents

• Why Flowlight?
• Features
• Installation
• Project Structure
• Core Concepts
  • Context
  • Action
  • Organizer
• Failure & Control Flow
  • Outcomes
  • withErrors (merge only)
  • withErrorsThrowAndReturn (merge + stop)
  • throwAndReturn (message/code + stop)
  • Internal control‑flow exception: JumpWhenFailed
  • WithErrorHandler (unexpected throws → context failure)
• Usage
  • Quick Start (Organizer)
  • Validator Action pattern
  • Service code with WithErrorHandler
  • Reading results
• Testing Guidelines
• Planned / Not Implemented
• Minimal API Reference

Why Flowlight?

Business flows grow complex quickly: validation, mapping, persistence, notifications, branching. Flowlight keeps each step small and composable, carrying state via a single Context so the code reads like a story:

Features

• Composable pipelines — Actions and Organizers chain clearly.
• Validation as data — accumulate errors; stop intentionally.
• Unified exception capture — normalize unexpected throws into the Context.
• Lightweight — PHP ≥ 8.2, minimal deps.

Not Implemented (TBD): lifecycle hooks (before/after/around), skip‑remaining, expects/promises, structured logging.

Installation

Project Structure

Core Concepts

Context

Carries inputs, params, errors, resources, and diagnostics.

• Errors are grouped by key (e.g., email) with a base bucket for global messages.
• Diagnostics live under internalOnly (e.g., message, error_code, errorInfo).
• Public callers consume success() / failure() and errorsArray().

Action

Extend Flowlight\Action and implement perform(Context $ctx): void.

Organizer

Declares a sequence of steps; each step receives the same Context.

• Define steps by overriding protected static function steps(): array.
• Call via Organizer::call(array $input = [], array $overrides = [], ?callable $transformContext = null): Context.

Failure & Control Flow

Outcomes

Use success() / failure() to decide how to render results. Public code should not depend on internal flags.

withErrors (merge only)

Accumulates errors without stopping the chain.

withErrorsThrowAndReturn (merge + stop)

Accumulates errors, sets an optional message/code, then stops immediately using internal control flow.

Result (illustrative) once the organizer returns:

• errorsArray() ⇒ ['email' => ['is invalid'], 'base' => ['Validation failed']]
• internalOnly() ⇒ ['message' => 'Validation failed', 'error_code' => 1001]

throwAndReturn (message/code + stop)

Stops immediately with a message/code, without attaching field errors.

Internal control‑flow exception: JumpWhenFailed

Internal exception used to unwind quickly after a throw‑and‑return path. The organizer boundary catches it and normalizes the Context.

WithErrorHandler (unexpected throws → context failure)

Wrap risky code; unexpected exceptions are recorded into the Context with a human message and the pipeline is stopped. Optional rethrow propagates after recording.

Usage

Quick Start (Organizer)

Validator Action pattern

Accumulate rule errors, then stop once you decide it’s terminal.

Service code with WithErrorHandler

See the trait example above. Keep validation failures (expected) separate from true exceptions (unexpected).

Reading results

Consume success() / failure() and errorsArray(); avoid internal flags.

Testing Guidelines

• Action tests — create Context via Context::makeWithDefaults, execute, assert params/resources/errors.
• ValidatorAction tests — feed invalid input, assert errors shape and that the organizer stops on throw‑and‑return.
• Organizer tests — assert short‑circuiting and happy‑path composition.
• WithErrorHandler tests — cover callable + Throwable‑proxy paths, and rethrow.

Planned / Not Implemented

• Lifecycle hooks (before/after/around)
• Skip remaining (skipRemaining() parity)
• Expects & Promises (compile/runtime guards)
• Structured logging around organizer/action boundaries

Minimal API Reference

Context

• withErrors(array|Traversable $errs): self — merge errors (no stop).
• withErrorsThrowAndReturn(array|Traversable $errs, ?string $message = null, array|int $optionsOrErrorCode = []): self — merge + stop.
• throwAndReturn(?string $message = null, array|int $optionsOrErrorCode = []): self — stop with message/code only.
• errorsArray(): array — user‑facing errors (incl. base).
• internalOnly(): ArrayAccess|array — diagnostics (message, error_code, errorInfo).
• success(): bool / failure(): bool

Organizer

• protected static function steps(): array
• public static function call(array $input = [], array $overrides = [], ?callable $transformContext = null): Context

Traits\WithErrorHandler

• withErrorHandler(Context $ctx, callable|Throwable $blockOrThrowable, bool $rethrow = false): void

Exceptions

• JumpWhenFailed — internal control‑flow exception.
• Exceptions\ContextFailedError — exception carrying a Context.