prewk/result

Result object for PHP inspired by Rust

4.0.0 2024-05-10 18:17 UTC

Requires

• php: >=8.1.0
• prewk/option: >= 1.3.0

Requires (Dev)

• ergebnis/composer-normalize: 2.42.0
• infection/infection: 0.27.11
• phpunit/phpunit: 10.5.15
• psalm/plugin-phpunit: 0.19.0
• symplify/easy-coding-standard: 12.1.14
• vimeo/psalm: 5.24.0

(MIT or Apache-2.0)

• Oskar Thornblad

README

A PHP implementation of Rust's Result type with roughly the same API.

Version information

Version 4.x.x requires PHP 8.1.0+. Make sure you match the versions for this and the Option library if you use both.

Installation

composer require prewk/result

Overview

use Prewk\Result;
use Prewk\Result\{Ok, Err};

function someApiCall(): Result {
    // ...
    if ($apiCallSuccesful) {
        return new Ok($results);
    } else {
        return new Err($error);
    }
}

function anotherApiCall(): Result {
    // ...
    if ($apiCallSuccesful) {
        return new Ok($results);
    } else {
        return new Err($error);
    }
}

// Fallback to value
$value = someApiCall()->unwrapOr(null);

// Fallback to result and throw an exception if both fail
$value = someApiCall()->orElse(function($err) {
	return anotherApiCall();
})->unwrap();

// Throw custom exception on error
$value = someApiCall()->expect(new Exception("Oh noes!"));

Helpers

Optional global helper functions exist to simplify result object construction:

ok(); // new Prewk\Result\Ok(null);
ok($val); // new Prewk\Result\Ok($val);
err($e); // new Prewk\Result\Err($e);

Add the following to your composer.json:

{
  "autoload": {
    "files": ["vendor/prewk/result/helpers.php"]
  }
}

API deviations from Rust

Exceptions

If an Err containing an Exception is unwrapped, that Exception will be thrown. Otherwise a generic ResultException will be thrown.

Gotchas

Note that or and and will be evaluated immediately:

// This will call all three api calls regardless of successes/errors
$this
	->apiCall()
	->or(anotherApiCall())
	->and(thirdApiCall());

See andThen and orElse for lazy evaluation.

License

MIT & Apache 2.0