README

Minimal, type-safe Result type for explicit success/failure handling in PHP (PHP 8.2+).

Composer:

composer require maxiviper117/result-flow

Documentation map

Why Result Flow

Explicit branches: success and failure are handled intentionally.
Metadata propagation: context survives across every chain step.
Predictable semantics: fail-fast and collect-all tools are explicit and separate.
Type-aware design: PHPStan-friendly templates across public methods.

Quick example

use Maxiviper117\ResultFlow\Result;

$result = Result::ok(['order_id' => 123, 'total' => 42], ['request_id' => 'r-1'])
    ->ensure(fn (array $order) => $order['total'] > 0, 'Order total must be positive')
    ->then(fn (array $order) => Result::ok([
        'saved' => true,
        'id' => $order['order_id'],
    ]));

$output = $result->match(
    onSuccess: fn (array $v) => ['ok' => true, 'data' => $v],
    onFailure: fn ($e) => ['ok' => false, 'error' => (string) $e],
);

Deferred operations

use Maxiviper117\ResultFlow\Result;

$result = Result::defer(fn () => loadUserById($id))
    ->then(fn (array $user) => Result::ok(normalizeUser($user)));

Retry deferred operations

use Maxiviper117\ResultFlow\Result;

$result = Result::retryDefer(
    3,
    fn () => callExternalApi($payload),
    delay: 100,
    exponential: true,
);

Resource-safe operations

use Maxiviper117\ResultFlow\Result;

$result = Result::bracket(
    acquire: fn () => fopen($path, 'r'),
    use: fn ($handle) => fread($handle, 100),
    release: fn ($handle) => fclose($handle),
);

Batch workflows

Result::mapItems($items, $fn) for per-item Result status.
Result::mapAll($items, $fn) for fail-fast aggregate processing.
Result::mapCollectErrors($items, $fn) for collect-all error reporting.

All batch callbacks use: fn ($item, $key) => Result|value.

Laravel Boost

This package ships Laravel Boost source assets so AI agents in downstream consumer apps can generate ResultFlow-aware code.

Package-shipped guideline source

Source file in this package: resources/boost/guidelines/core.blade.php
In a Laravel app that uses Boost, run:

php artisan boost:install

Boost applies package-shipped guidance within the app AI context.

Package-shipped central skill source

Source file in this package:
- resources/boost/skills/result-flow/SKILL.md
The central skill loads only needed concept references from:
- resources/boost/skills/result-flow/references/*.md

App-level overrides

App teams can define or override guidelines locally:

.ai/guidelines/...

To override a built-in guideline, use the same relative path in .ai/guidelines, for example:

.ai/guidelines/inertia-react/2/forms.blade.php

Contributing

Tests: composer test
Static analysis: composer analyse
Rector check: composer rector-dry
Rector apply: composer rector
Format: composer format

See CONTRIBUTING.md.

License

MIT - see LICENSE.md.

maxiviper117 / result-flow

Maintainers

Package info

Fund package maintenance!

Statistics

Security