|
1 | | -# php-result |
| 1 | +# PHP Result |
2 | 2 |
|
3 | | -Result type for PHP inspired by Rust's Result<T, E> type. |
| 3 | +[](https://packagist.org/packages/valbeat/result) |
| 4 | +[](https://packagist.org/packages/valbeat/result) |
| 5 | +[](https://packagist.org/packages/valbeat/result) |
| 6 | + |
| 7 | +A Result type implementation for PHP inspired by Rust's `Result<T, E>` type. |
| 8 | + |
| 9 | +This library provides a robust way to handle operations that might fail, without relying on exceptions. It encourages explicit error handling and makes it impossible to accidentally ignore errors. |
| 10 | + |
| 11 | +## Installation |
| 12 | + |
| 13 | +```bash |
| 14 | +composer require valbeat/result |
| 15 | +``` |
4 | 16 |
|
5 | 17 | ## Requirements |
6 | 18 |
|
7 | 19 | - PHP 8.4 or higher |
8 | 20 | - Composer |
9 | 21 |
|
10 | | -## Installation |
| 22 | +## Basic Usage |
| 23 | + |
| 24 | +```php |
| 25 | +use Valbeat\Result\Ok; |
| 26 | +use Valbeat\Result\Err; |
| 27 | +use Valbeat\Result\Result; |
| 28 | + |
| 29 | +// Creating Results |
| 30 | +$success = new Ok(42); |
| 31 | +$failure = new Err("Something went wrong"); |
| 32 | + |
| 33 | +// Pattern matching with match expression |
| 34 | +$message = $success->match( |
| 35 | + ok: fn($value) => "Success: $value", |
| 36 | + err: fn($error) => "Error: $error" |
| 37 | +); |
| 38 | +echo $message; // "Success: 42" |
| 39 | + |
| 40 | +// Checking if a Result is Ok or Err |
| 41 | +if ($success->isOk()) { |
| 42 | + echo "Operation succeeded!"; |
| 43 | +} |
| 44 | + |
| 45 | +if ($failure->isErr()) { |
| 46 | + echo "Operation failed!"; |
| 47 | +} |
| 48 | + |
| 49 | +// Unwrapping values (throws exception on error) |
| 50 | +$value = $success->unwrap(); // 42 |
| 51 | +// $failure->unwrap(); // throws LogicException |
| 52 | + |
| 53 | +// Safe unwrapping with default values |
| 54 | +$value = $failure->unwrapOr(0); // 0 |
| 55 | +$value = $failure->unwrapOrElse(fn($err) => strlen($err)); // 19 |
| 56 | +``` |
| 57 | + |
| 58 | +## Advanced Usage |
| 59 | + |
| 60 | +### Transforming Results |
| 61 | + |
| 62 | +```php |
| 63 | +// Map over success values |
| 64 | +$result = (new Ok(5)) |
| 65 | + ->map(fn($x) => $x * 2) |
| 66 | + ->map(fn($x) => $x + 1); |
| 67 | +echo $result->unwrap(); // 11 |
| 68 | + |
| 69 | +// Map over error values |
| 70 | +$result = (new Err("error")) |
| 71 | + ->mapErr(fn($e) => strtoupper($e)); |
| 72 | +echo $result->unwrapErr(); // "ERROR" |
| 73 | +``` |
| 74 | + |
| 75 | +### Chaining Operations |
| 76 | + |
| 77 | +```php |
| 78 | +// Chain operations that might fail |
| 79 | +$result = (new Ok(10)) |
| 80 | + ->andThen(fn($x) => $x > 5 ? new Ok($x * 2) : new Err("Too small")) |
| 81 | + ->andThen(fn($x) => new Ok($x + 5)); |
| 82 | +echo $result->unwrap(); // 25 |
| 83 | + |
| 84 | +// Short-circuit on first error |
| 85 | +$result = (new Ok(2)) |
| 86 | + ->andThen(fn($x) => $x > 5 ? new Ok($x * 2) : new Err("Too small")); |
| 87 | +echo $result->unwrapErr(); // "Too small" |
| 88 | +``` |
| 89 | + |
| 90 | +### Combining Results |
| 91 | + |
| 92 | +```php |
| 93 | +// Use first Ok value |
| 94 | +$result = (new Err("first error")) |
| 95 | + ->or(new Err("second error")) |
| 96 | + ->or(new Ok(42)); |
| 97 | +echo $result->unwrap(); // 42 |
| 98 | + |
| 99 | +// Use first Ok or call function |
| 100 | +$result = (new Err("error")) |
| 101 | + ->orElse(fn($e) => new Ok(strlen($e))); |
| 102 | +echo $result->unwrap(); // 5 |
| 103 | +``` |
| 104 | + |
| 105 | +### Side Effects |
| 106 | + |
| 107 | +```php |
| 108 | +// Inspect values without consuming the Result |
| 109 | +$result = (new Ok(42)) |
| 110 | + ->inspect(fn($x) => print("Value is: $x\n")) |
| 111 | + ->map(fn($x) => $x * 2); |
| 112 | + |
| 113 | +// Inspect errors |
| 114 | +$result = (new Err("oops")) |
| 115 | + ->inspectErr(fn($e) => error_log("Error occurred: $e")); |
| 116 | +``` |
| 117 | + |
| 118 | +## API Reference |
| 119 | + |
| 120 | +### Result Methods |
| 121 | + |
| 122 | +All Result types (both Ok and Err) implement these methods: |
| 123 | + |
| 124 | +#### Type Checking |
| 125 | +- `isOk(): bool` - Returns true if the Result is Ok |
| 126 | +- `isOkAnd(callable $fn): bool` - Returns true if the Result is Ok and the predicate returns true |
| 127 | +- `isErr(): bool` - Returns true if the Result is Err |
| 128 | +- `isErrAnd(callable $fn): bool` - Returns true if the Result is Err and the predicate returns true |
| 129 | + |
| 130 | +#### Value Extraction |
| 131 | +- `unwrap(): mixed` - Returns the success value or throws LogicException |
| 132 | +- `unwrapErr(): mixed` - Returns the error value or throws LogicException |
| 133 | +- `unwrapOr(mixed $default): mixed` - Returns the success value or a default |
| 134 | +- `unwrapOrElse(callable $fn): mixed` - Returns the success value or computes it from the error |
| 135 | + |
| 136 | +#### Transformation |
| 137 | +- `map(callable $fn): Result` - Maps a Result<T, E> to Result<U, E> by applying a function to the success value |
| 138 | +- `mapErr(callable $fn): Result` - Maps a Result<T, E> to Result<T, F> by applying a function to the error value |
| 139 | +- `mapOr(mixed $default, callable $fn): mixed` - Maps the success value or returns a default |
| 140 | +- `mapOrElse(callable $defaultFn, callable $fn): mixed` - Maps the success value or computes a default from the error |
| 141 | + |
| 142 | +#### Combination |
| 143 | +- `and(Result $res): Result` - Returns the second Result if the first is Ok, otherwise returns the first Err |
| 144 | +- `andThen(callable $fn): Result` - Chains another operation that returns a Result |
| 145 | +- `or(Result $res): Result` - Returns the first Ok or the second Result if the first is Err |
| 146 | +- `orElse(callable $fn): Result` - Returns the first Ok or calls a function with the error to produce a Result |
| 147 | + |
| 148 | +#### Side Effects |
| 149 | +- `inspect(callable $fn): Result` - Calls a function with the success value if Ok |
| 150 | +- `inspectErr(callable $fn): Result` - Calls a function with the error value if Err |
| 151 | + |
| 152 | +#### Pattern Matching |
| 153 | +- `match(callable $okFn, callable $errFn): mixed` - Pattern match on the Result |
11 | 154 |
|
| 155 | +## Comparison with Rust |
| 156 | + |
| 157 | +This implementation closely follows Rust's Result type design: |
| 158 | + |
| 159 | +| Rust | PHP Result | |
| 160 | +|------|------------| |
| 161 | +| `Result<T, E>` | `Result<T, E>` | |
| 162 | +| `Ok(T)` | `new Ok(T)` | |
| 163 | +| `Err(E)` | `new Err(E)` | |
| 164 | +| `is_ok()` | `isOk()` | |
| 165 | +| `is_err()` | `isErr()` | |
| 166 | +| `unwrap()` | `unwrap()` | |
| 167 | +| `unwrap_or()` | `unwrapOr()` | |
| 168 | +| `map()` | `map()` | |
| 169 | +| `and_then()` | `andThen()` | |
| 170 | +| `match` expression | `match()` method | |
| 171 | + |
| 172 | +## Development |
| 173 | + |
| 174 | +### Running Tests |
| 175 | +```bash |
| 176 | +composer test |
| 177 | +``` |
| 178 | + |
| 179 | +### Static Analysis |
12 | 180 | ```bash |
13 | | -composer install |
| 181 | +composer phpstan |
14 | 182 | ``` |
| 183 | + |
| 184 | +### Run All Checks |
| 185 | +```bash |
| 186 | +composer check |
| 187 | +``` |
| 188 | + |
| 189 | +## License |
| 190 | + |
| 191 | +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. |
| 192 | + |
| 193 | +## Contributing |
| 194 | + |
| 195 | +Contributions are welcome! Please feel free to submit a Pull Request. |
0 commit comments