php-result

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 12 Open GitHub ↗

A type-safe Result type for PHP 8.2+ with PHPStan support.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# php-result

[![Latest Version on Packagist](https://img.shields.io/packagist/v/jsoizo/php-result.svg)](https://packagist.org/packages/jsoizo/php-result)
[![CI](https://github.com/jsoizo/php-result/actions/workflows/ci.yml/badge.svg)](https://github.com/jsoizo/php-result/actions/workflows/ci.yml)
[![License](https://img.shields.io/packagist/l/jsoizo/php-result.svg)](https://packagist.org/packages/jsoizo/php-result)

A type-safe Result type for PHP 8.1+ with PHPStan support.

## Features

- Zero dependencies
- PHPStan level max support
- Rich composition functions (map, flatMap, mapError)
- Inspired by functional programming Result/Either types

## Installation

```bash
composer require jsoizo/php-result
```

## Requirements

The library runtime supports PHP 8.1+. The development and test tooling in this repository requires PHP 8.2+ because the locked Pest/PHPUnit toolchain requires PHP 8.2.

## Basic Usage

```php
use Jsoizo\Result\Result;

// Create Success/Failure
$success = Result::success(42);
$failure = Result::failure('error message');

// Transform values
$doubled = $success->map(fn($x) => $x * 2); // Success(84)

// Chain operations
$result = $success
    ->flatMap(fn($x) => $x > 0
        ? Result::success($x * 2)
        : Result::failure('must be positive'));

// Get value with default
$value = $failure->getOrElse(0); // 0

// Get value with lazy fallback computed from the error
$value = $failure->getOr(fn($error) => strlen($error)); // 13
// The callback is only invoked on Failure, so expensive defaults are never built on success.

// Catch exceptions
$result = Result::catch(fn() => riskyOperation());

// Catch only an expected exception class; anything else is rethrown
$result = Result::catch(
    fn() => json_decode($json, flags: JSON_THROW_ON_ERROR),
    JsonException::class
);
// Result<mixed, JsonException> - a TypeError would propagate instead of becoming a Failure

// Convert a nullable value into a Result
$result = Result::fromNullable($userRepo->find($id), fn() => 'user not found');
// null → Failure('user not found'), non-null → Success(User)
// Only null counts as absence: falsy values like '', 0, false become Success.

// Handle both cases with fold
$message = $result->fold(
    onFailure: fn($error) => "Error: {$error->getMessage()}",
    onSuccess: fn($value) => "Got: {$value}"
);

// Compose validations with flatMap
$result = validateEmail($input['email'])
    ->flatMap(fn($email) => validatePassword($input['password'])
    ->flatMap(fn($password) => createUser($email, $password)));
// If each step can fail differently, the error type is the union of all possible errors.

// Recover from failure with default value
$recovered = $failure->recover(fn($e) => 'default'); // Success('default')
// recover() always returns a successful Result, so the error type becomes never.

// Chain fallback operations
$result = fetchFromPrimaryDb()
    ->recoverWith(fn($e) => fetchFromSecondaryDb())
    ->recoverWith(fn($e) => Result::success('cached fallback'));

// Side effects for debugging/logging
$result = validateInput($data)
    ->tap(fn($v) => logger()->info("Valid: $v"))
    ->tapError(fn($e) => logger()->error("Invalid: $e"))
    ->flatMap(fn($v) => processData($v));

// Get value as nullable
$value = $result->getOrNull(); // T|null

// Get error as nullable
if (($error = $result->getErrorOrNull()) !== null) {
    logger()->error("Failed: $error");
}

// Flatten nested Results
$nested = Result::success(Result::success(42));
$flat = $nested->flatten(); // Success(42)
// Result<Result<int, string>, string> becomes Result<int, string>.

// Monad comprehension with binding (avoids nested flatMap)
$result = Result::binding(function () use ($orderId) {
    /** @var Order $order */
    $order = yield Result::catch(fn() => $orderRepo->find($orderId));
    /** @var list<Item> $items */
    $items = yield Result::catch(fn() => $order->loadItems());
    return $items;
});
// Returns Result<list<Item>, Throwable> - short-circuits on first failure
// Every yielded value must be a Result; invalid yields throw ResultException.

// Accumulate a list of Results into one, collecting all errors
$result = Result::accumulate([
    validateName($input['name']),
    validateAge($input['age']),
    validateEmail($input['email']),
]);
// All Success → Success([name, age, email])
// Any Failure → Failure(['Name required', 'Invalid email']) (non-empty-list of errors)

// Sequence a list of Results into one, stopping at the first error
$result = Result::sequence([
    loadConfig($path),
    connectDb($dsn),
    fetchUser($id),
]);
// All Success → Success([config, connection, user])
// Any Failure → Failure('config not found') (first error, unwrapped)

// Accumulate errors from multiple independent validations
$result = Result::accumulate3(
    validateName($input['name']),
    validateAge($input['age']),
    validateEmail($input['email']),
    fn(string $name, int $age, string $email) => new User($name, $age, $email)
);
// All Success → Success(User(...))
// Any Failure → Failure(['Name required', 'Invalid email']) (non-empty-list of errors)
```

Use `accumulate($results)` for a homogeneous list of same-typed Results; use `accumulate2()`–`accumulate9()` to combine differently-typed Results into one value via a transform function. Use `sequence($results)` when you want fail-fast semantics instead: validation → `accumulate` (report all errors), sequential composition → `sequence` (stop at the first failure, error type stays as-is).

## API

### Factory Methods

| Method | Description |
|--------|-------------|
| `Result::success($value)` | Create a Success |
| `Result::failure($error)` | Create a Failure |
| `Result::catch(callable $fn, string $exceptionClass = Throwable::class)` | Wrap exception-throwing code, optionally capturing only a given exception class |
| `Result::fromNullable($value, callable $onNull)` | Convert a nullable value into a Result |
| `Result::binding(callable $fn)` | Monad comprehension using generators |
| `Result::accumulate($results)` | Convert a list of Results into one Result, collecting all errors |
| `Result::sequence($results)` | Convert a list of Results into one Result, stopping at the first error |
| `Result::accumulate2($r1, ..., $transform)` | Combine 2 Results, collecting all errors |
| `Result::accumulate3($r1, ..., $transform)` | Combine 3 Results, collecting all errors |
| `Result::accumulate4($r1, ..., $transform)` | Combine 4 Results, collecting all errors |
| `Result::accumulate5($r1, ..., $transform)` | Combine 5 Results, collecting all errors |
| `Result::accumulate6($r1, ..., $transform)` | Combine 6 Results, collecting all errors |
| `Result::accumulate7($r1, ..., $transform)` | Combine 7 Results, collecting all errors |
| `Result::accumulate8($r1, ..., $transform)` | Combine 8 Results, collecting all errors |
| `Result::accumulate9($r1, ..., $transform)` | Combine 9 Results, collecting all errors |

### Instance Methods

| Method | Description |
|--------|-------------|
| `isSuccess()` | Returns true if Success |
| `isFailure()` | Returns true if Failure |
| `getOrElse($default)` | Get value or default |
| `getOr($fn)` | Get value or compute fallback lazily from error |
| `get()` | Get value or throw |
| `getErrorOrElse($default)` | Get error or default |
| `getErrorOr($fn)` | Get error or compute fallback lazily from value |
| `getError()` | Get error or throw ResultException |
| `map($fn)` | Transform success value |
| `mapError($fn)` | Transform error value |
| `flatMap($fn)` | Chain Result-returning operations |
| `fold($onFailure, $onSuccess)` | Handle both cases and return a value |
| `recover($fn)` | Recover from error with a value |
| `recoverWith($fn)` | Recover from error with a Result |
| `tap($fn)` | Execute side effect on success value, return same Result |
| `tapError($fn)` | Execute side effect on error value, return same Result |
| `getOrNull()` | Get success value or null |
| `getErrorOrNull()` | Get error value or null |
| `flatten()` | Flatten nested `Result<Result<T, E1>, E2>` into `Result<T, E1\|E2>` |

### Error Types in flatMap

`flatMap()` preserves both the original error type and the error type returned by the callback:

```php
/** @var Result<string, ValidationError> $result */
$saved = $result->flatMap(fn(string $value) => save($value));
// If save() returns Result<User, DbError>, $saved is Result<User, ValidationError|DbError>.
```

Long chains can naturally produce wide error unions. When that becomes awkward, normalize errors with `mapError()` to a domain-specific error type at a boundary.

### Recovering with Different Success Types

`recover()` and `recoverWith()` can return a different success type than the original `Result`:

```php
/** @var Result<int, string> $result */
$recovered = $result->recover(fn(string $error) => false);
// Result<int|bool, never>
```

After `recover()`, the Result can no longer be a Failure. `recoverWith()` keeps the callback's error type because the fallback operation may still fail.

### Flattening Nested Results

`flatten()` preserves nested generic types. If the success value is another `Result`, the inner success type is used and the outer and inner error types are combined:

```php
/** @var Result<Result<int, DbError>, ValidationError> $result */
$flat = $result->flatten();
// Result<int, ValidationError|DbError>
```

Calling `flatten()` on a non-nested Result keeps the original type.

## PHPStan Integration

### Sealed Class Support

Result is marked as a sealed class using `@phpstan-sealed`. This prevents creating custom subclasses of Result outside of Success and Failure.

```php
// PHPStan will report an error for unauthorized subclasses:
// "Type CustomResult is not allowed to be a subtype of Result"
class CustomResult extends Result { ... }
```

Requirements:
- PHPStan 2.1.18 or later
- No additional packages needed

See: [PHPStan Sealed Classes](https://phpstan.org/writing-php-code/phpdocs-basics#sealed-classes)

### Type Narrowing with isSuccess/isFailure

The `isSuccess()` and `isFailure()` methods support [PHPStan type narrowing](https://phpstan.org/writing-php-code/narrowing-types):

```php
/** @param Result<User, ValidationError> $result */
function handleResult(Result $result): void
{
    if ($result->isSuccess()) {
        // PHPStan knows $result is Success<User, ValidationError>
        $user = $result->get();
    } else {
        // PHPStan knows $result is Failure<User, ValidationError>
        $error = $result->getError();
    }
}

// Early return pattern
/** @param Result<int, string> $result */
function getValue(Result $result): int
{
    if ($result->isFailure()) {
        return -1;
    }
    // PHPStan knows $result is Success<int, string>
    return $result->get();
}
```

### Match Exhaustiveness Check

This library includes a custom PHPStan rule that ensures match expressions on Result types are exhaustive.

**Setup:**

The rule is automatically enabled when you use PHPStan with this library (via `composer.json` extra config). Alternatively, add to your `phpstan.neon`:

```neon
includes:
    - vendor/jsoizo/php-result/extension.neon
```

**What it checks:**

```php
// Error: Match expression on Result type is not exhaustive. Missing: Failure.
match (true) {
    $result instanceof Success => 'success',
};

// OK: All cases covered
match (true) {
    $result instanceof Success => 'success',
    $result instanceof Failure => 'failure',
};

// OK: default covers remaining cases
match (true) {
    $result instanceof Success => 'success',
    default => 'failure',
};
```

**Note: PHPStan's `match.unhandled` error**

Even when all cases are covered, PHPStan may report `Match expression does not handle remaining value: true`. This is because PHPStan doesn't use sealed class information for match exhaustiveness.

To suppress this error, use the `@phpstan-ignore` comment:

```php
/** @phpstan-ignore match.unhandled (Result is sealed: Success|Failure) */
return match (true) {
    $result instanceof Success => 'success',
    $result instanceof Failure => 'failure',
};
```

The custom rule in this library ensures exhaustiveness, so it's safe to ignore `match.unhandled` for Result types.

**Limitations:**

The custom rule tracks simple variables in `instanceof` match arms, such as `$result instanceof Success`. It intentionally does not check property fetches or method calls such as `$this->result instanceof Success` or `$this->getResult() instanceof Success`.

php-result

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README