Download the PHP package bosunski/results without Composer

Results

Results is a PHP simple (dependency-free) library that provides a set of helper functions and classes for handling optional values and results of operations. It is inspired by the Option and Result types in Rust. The implementation itself is based on the TypeScript implementation called ts-results.

Installation

You can install the library through Composer:

Usage

Demo

You can try the package in this Playground

Option

The Option type represents an optional value: every Option is either Some and contains a value, or None, and does not.

Result

The Result type is a type that represents either success (Ok) or failure (Err).

Helper Functions

The library provides a set of helper functions for creating Option and Result instances:

• Some(mixed $value): Some
• None(): None
• Option(mixed $value): Option
• Ok(mixed $value): Ok
• Err(Throwable $e): Err
• Result(mixed $value): Ok|Err
• wrap(callable $fn): Result

Examples

Optional values and results in PHP can be represented using the Option and Result types provided by the Results library. Here are some examples:

In the above examples:

• Option('value') creates an Option that contains a value (referred to as Some).
• Option(null) creates an Option that does not contain a value (referred to as None).
• Result('value') creates a Result that represents a successful operation (Ok).
• Result(new Exception('error')) creates a Result that represents a failed operation (Err).

Let's dive into more complex examples of using the Option and Result types in PHP.

Consider a scenario where we have a function that may or may not return a value. We can use the Option type to handle this uncertainty.

Now, let's consider a scenario where we have a function that can either succeed or fail. We can use the Result type to handle this.

In these examples, the Option and Result types provide a way to handle optional values and the results of operations in a safe and expressive manner.

The wrap Function

The wrap function is a utility function provided by the library. It is designed to handle operations that can throw an error. The wrap function executes a callable and returns its result wrapped in a Result object. If the callable function throws an exception, the wrap function catches it and returns an Err object containing the exception.

[!IMPORTANT] The wrap function will only catch instances of Throwable. If your function raises something like a fatal error it will not be caught by wrap.

Here's an example of how you might use the wrap function:

In this example, mightThrowException is a function that might throw an exception. We pass this function to wrap, which executes it, catch any error and wraps the result in a Result object. We then check if the result is an instance of Ok or Err and handle it accordingly.

The wrap function provides a safe and expressive way to handle operations that can throw errors, allowing you to focus on your application logic rather than error handling when you don't need to.

Contributing

Setting up the project

You can install development dependencies by running:

Running tests

License

This project is licensed under the MIT License.