Monads for PHP

A collection of useful monads for PHP 8.3+. Inspired by Rust's powerful type system and functional programming patterns.

Features

• 🦀 Rust-inspired API - Familiar methods for those coming from Rust
• 🔒 Type-safe - Full PHPStan level 9 support with generics
• 🧪 Well-tested - Comprehensive test suite
• 📦 Zero dependencies - Lightweight and focused
• 🎯 Four core monads:
  • Option<T> - Represent optional values without null
  • Result<T, E> - Handle errors without exceptions
  • Lazy<T> - Defer computation until needed
  • Writer<W, T> - Carry a value alongside an accumulated log

Installation

You can install the package via Composer:

composer require gosuperscript/monads

Requirements

• PHP 8.3 or higher

Usage

Option Monad

The Option type represents an optional value: every Option is either Some and contains a value, or None, and does not. This is a safer alternative to using null.

usefunctionSuperscript\Monads\Option\{Some, None};
// Create an Option$some = Some(42);
$none = None();
// Check if value exists$some->isSome(); // true$none->isNone(); // true// Transform the value$doubled = Some(21)->map(fn($x) => $x * 2); // Some(42)$empty = None()->map(fn($x) => $x * 2); // None// Provide default valuesSome(42)->unwrapOr(0); // 42None()->unwrapOr(0); // 0// Chain operationsSome(10)
->filter(fn($x) => $x > 5)
->map(fn($x) => $x * 2)
->unwrapOr(0); // 20// Convert to ResultSome(42)->okOr("error"); // Ok(42)None()->okOr("error"); // Err("error")

Key Option Methods

• isSome() / isNone() - Check if the option contains a value
• isSomeAnd(callable $predicate) - Check if Some and matches predicate
• map(callable $f) - Transform the contained value
• filter(callable $f) - Filter based on a predicate
• and(Option $other) / or(Option $other) - Combine options
• andThen(callable $f) - Chain operations (flatMap)
• unwrap() - Get the value (throws if None)
• unwrapOr($default) - Get the value or a default
• unwrapOrElse(callable $f) - Get the value or compute a default
• expect(string|Throwable $message) - Unwrap with custom error message

Result Monad

Result<T, E> is the type used for returning and propagating errors. It is either Ok(T), representing success and containing a value, or Err(E), representing error and containing an error value.

usefunctionSuperscript\Monads\Result\{Ok, Err, attempt};
// Create Results$ok = Ok(42);
$err = Err("something went wrong");
// Check the result$ok->isOk(); // true$err->isErr(); // true// Transform success values$doubled = Ok(21)->map(fn($x) => $x * 2); // Ok(42)$stillErr = Err("error")->map(fn($x) => $x * 2); // Err("error")// Transform error values$recovered = Err("error")->mapErr(fn($e) => "recovered"); // Err("recovered")// Handle both cases$result = Ok(10)->match(
err: fn($e) => "Error: $e",
ok: fn($x) => "Success: $x"
); // "Success: 10"// Chain operationsOk(10)
->map(fn($x) => $x * 2)
->andThen(fn($x) => $x > 15 ? Ok($x) : Err("too small"))
->unwrapOr(0); // 20// Convert to OptionOk(42)->ok(); // Some(42)Err("e")->ok(); // None()// Safely execute code that might throw$result = attempt(fn() => json_decode($json, flags: JSON_THROW_ON_ERROR));
// Returns: Result<mixed, Throwable>

Key Result Methods

• isOk() / isErr() - Check if the result is success or error
• map(callable $f) - Transform the success value
• mapErr(callable $f) - Transform the error value
• mapOr($default, callable $f) - Transform or provide default
• mapOrElse(callable $default, callable $f) - Transform or compute default
• match(callable $err, callable $ok) - Handle both cases
• and(Result $other) / or(Result $other) - Combine results
• andThen(callable $f) - Chain operations (flatMap)
• unwrap() - Get the success value (throws if Err)
• unwrapErr() - Get the error value (throws if Ok)
• unwrapOr($default) - Get the value or a default
• unwrapOrElse(callable $f) - Get the value or compute a default
• expect(string|Throwable $message) - Unwrap with custom error message

Lazy Monad

The Lazy type allows you to defer the execution of a computation until its result is actually needed.

useSuperscript\Monads\Lazy\Lazy;
// Create a lazy computation$lazy = Lazy::of(fn() => expensiveComputation());
// The computation hasn't run yet...// Evaluate when needed (memoized)$result = $lazy->evaluate(); // Runs the computation$cached = $lazy->evaluate(); // Returns cached result// Practical example: lazy database query$users = Lazy::of(fn() => DB::query("SELECT * FROM users"));
if ($needUsers) {
$data = $users->evaluate(); // Query runs only if needed
}

Writer Monad

The Writer monad lets you carry a value alongside an accumulated log through a chain of computations. This is useful for logging, auditing, or building up auxiliary data without side effects.

useSuperscript\Monads\Writer\Writer;
usefunctionSuperscript\Monads\Writer\Writer;
// Create a Writer with an array-based log$writer = Writer(42, ['initial value']);
// Access value and log$writer->value(); // 42$writer->log(); // ['initial value']$writer->run(); // [42, ['initial value']]// Transform the value (log unchanged)Writer(21)->map(fn($x) => $x * 2); // Writer(42, [])// Chain computations that produce their own logsWriter(10, ['start'])
->andThen(fn($x) => Writer($x * 2, ['doubled']))
->andThen(fn($x) => Writer($x + 1, ['incremented']));
// value: 21, log: ['start', 'doubled', 'incremented']// Append to the log without changing the valueWriter(42)->tell(['something happened']);
// value: 42, log: ['something happened']// Use a custom log type with Writer::of()$writer = Writer::of('hello', '', fn(string$a, string$b): string => $a . $b)
->tell(' world')
->map(fn($v) => strtoupper($v));
// value: 'HELLO', log: ' world'

Key Writer Methods

• value() - Get the contained value
• log() - Get the accumulated log
• run() - Get both as a [$value, $log] tuple
• map(callable $f) - Transform the value, leaving the log unchanged
• andThen(callable $f) - Chain a computation that returns a Writer, combining logs (flatMap)
• tell($entry) - Append to the log without changing the value
• mapLog(callable $f) - Transform the log
• inspect(callable $f) - Execute a side effect with the value
• listen(callable $f) - Access both value and log to produce a new value
• reset($log) - Reset the log to a given value

Collection Operations

Both Option and Result support collecting arrays of values:

usefunctionSuperscript\Monads\Option\{Some, None};
usefunctionSuperscript\Monads\Result\{Ok, Err};
// Collect Options - returns first None or Some(array)
Option::collect([Some(1), Some(2), Some(3)]); // Some([1, 2, 3])
Option::collect([Some(1), None(), Some(3)]); // None()// Collect Results - returns first Err or Ok(array)
Result::collect([Ok(1), Ok(2), Ok(3)]); // Ok([1, 2, 3])
Result::collect([Ok(1), Err("e"), Ok(3)]); // Err("e")

Practical Examples

Safe Array Access

useSuperscript\Monads\Option\Option;
functiongetUser(int$id): Option {
$user = DB::find('users', $id);
return Option::from($user); // Returns None if null
}
$username = getUser(123)
->map(fn($user) => $user->name)
->unwrapOr('Guest');

Error Handling Without Exceptions

usefunctionSuperscript\Monads\Result\{Ok, Err, attempt};
functiondivide(int$a, int$b): Result {
return$b === 0 ? Err("Division by zero")
: Ok($a / $b);
}
$result = divide(10, 2)
->map(fn($x) => $x * 2)
->unwrapOr(0); // 10$error = divide(10, 0)
->map(fn($x) => $x * 2)
->unwrapOr(0); // 0

Computation with Logging

usefunctionSuperscript\Monads\Writer\Writer;
functionaddTax(float$price): Writer {
$taxed = $price * 1.2;
returnWriter($taxed, [sprintf('Tax: %.2f -> %.2f', $price, $taxed)]);
}
functionapplyDiscount(float$price): Writer {
$discounted = $price * 0.9;
returnWriter($discounted, [sprintf('Discount: %.2f -> %.2f', $price, $discounted)]);
}
$result = Writer(100.0, ['Starting price: 100.00'])
->andThen(fn($p) => addTax($p))
->andThen(fn($p) => applyDiscount($p));
$result->value(); // 108.0$result->log(); // ['Starting price: 100.00', 'Tax: 100.00 -> 120.00', 'Discount: 120.00 -> 108.00']

Pipeline Processing

usefunctionSuperscript\Monads\Result\{Ok, Err};
functionprocessData(array$data): Result {
returnOk($data)
->andThen(fn($d) => validateData($d))
->andThen(fn($d) => transformData($d))
->andThen(fn($d) => saveData($d));
}
$result = processData($input)->match(
err: fn($e) => response()->json(['error' => $e], 400),
ok: fn($d) => response()->json(['data' => $d], 200)
);

Testing

The package uses Pest for testing:

# Run tests
vendor/bin/pest
# Run type checking
vendor/bin/phpstan
# Run code style fixer
vendor/bin/pint

PHPStan Integration

This library provides full PHPStan support with generic types. The testing utilities include:

useSuperscript\Monads\Result\Testing\ComparesResults;
useSuperscript\Monads\Option\Testing\ComparesOptions;
class MyTest extends TestCase {
use ComparesResults;
use ComparesOptions;
publicfunctiontest_example() {
// Custom assertions$this->assertOk(Ok(42));
$this->assertErr(Err("error"));
$this->assertSome(Some(42));
$this->assertNone(None());
// PHPUnit constraints$this->assertThat(Ok(42), $this->isOk());
$this->assertThat(Err("e"), $this->isErr());
}
}

Why Monads?

Monads help you write more predictable and maintainable code by:

1. Making errors explicit - No hidden nulls or uncaught exceptions
2. Enabling composition - Chain operations cleanly with map and andThen
3. Improving type safety - Let PHPStan catch errors at analysis time
4. Reducing boilerplate - Less null checking and try-catch blocks

Inspiration

This library is heavily inspired by Rust's Option and Result types, bringing similar patterns to PHP.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

The MIT License (MIT). Please see License File for more information.