Download the PHP package gosuperscript/monads without Composer

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:

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.

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.

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.

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.

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:

Practical Examples

Safe Array Access

Error Handling Without Exceptions

Computation with Logging

Pipeline Processing

Testing

The package uses Pest for testing:

PHPStan Integration

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

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.