Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ghostwriter/result
Provides a Result type implementation for PHP
https://github.com/ghostwriter/result
ghostwriter php result result-type
Last synced: about 1 month ago
JSON representation
Provides a Result type implementation for PHP
- Host: GitHub
- URL: https://github.com/ghostwriter/result
- Owner: ghostwriter
- License: bsd-3-clause
- Created: 2021-11-23T01:29:41.000Z (almost 3 years ago)
- Default Branch: 1.3.x
- Last Pushed: 2024-08-31T19:14:54.000Z (3 months ago)
- Last Synced: 2024-10-03T10:56:55.252Z (about 2 months ago)
- Topics: ghostwriter, php, result, result-type
- Language: PHP
- Homepage: https://github.com/ghostwriter/result
- Size: 528 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Result
[](https://github.com/ghostwriter/result/actions/workflows/automation.yml)
[](https://www.php.net/supported-versions)
[](https://dashboard.stryker-mutator.io/reports/github.com/ghostwriter/result/main)
[](https://codecov.io/gh/ghostwriter/result)
[](https://shepherd.dev/github/ghostwriter/result)
[](https://packagist.org/packages/ghostwriter/result)
[](https://packagist.org/packages/ghostwriter/result)
Provides a **`Result`** type implementation for PHP using [`ghostwriter/option`](https://github.com/ghostwriter/option)
## Installation
You can install the package via composer:
``` bash
composer require ghostwriter/result
```
## Usage
```php
use Ghostwriter\Result\Error;
use Ghostwriter\Result\Success;
// --- Success ---
$success = Success::create('Hello world!');
$success->unwrap(); // 'Hello world!'
// --- Error ---
$error = Error::create(new ExampleException());
$error->unwrap(); // throws: ResultException
$error->unwrapOr('Fallback'); // 'Fallback'
$error->unwrapError(); // returns: instance of ExampleException
// --- Example ---
function divide(int $x, int $y): ResultInterface
{
if ($y === 0) {
return Error::create(new DivisionByZeroError);
}
return Success::create($x / $y);
}
divide(1, 0); // Error(DivisionByZeroError)
divide(1, 1); // Success(1)
```
## API
### `SuccessInterface`
``` php
/**
* @template TValue
*
* @implements ResultInterface
*/
interface SuccessInterface extends ResultInterface
{
/**
* Create a new success value.
*
* @template TSuccess
*
* @param TSuccess $value
*
* @return self
*/
public static function create(mixed $value): self;
}
```
### `ErrorInterface`
``` php
use Throwable;
/**
* @template TValue of Throwable
*
* @implements ResultInterface
*/
interface ErrorInterface extends ResultInterface
{
/**
* Create a new error value.
*
* @return self
*/
public static function create(Throwable $throwable): self;
}
```
### `ResultInterface`
``` php
use Ghostwriter\Option\OptionInterface;
use Throwable;
/**
* @template TValue
*/
interface ResultInterface
{
/**
* Returns $result if the result is Success, otherwise returns the Error value of self.
*
* @template TAndValue
* @param self $result
*
* @return self
*/
public function and(self $result): self;
/**
* Calls $function if the result is Success, otherwise returns the Error value of self.
*
* @template TNewValue
*
* @param callable(TValue):TNewValue $function
*
* @return self
*/
public function andThen(callable $function): self;
/**
* Converts from Result to Option.
*/
public function error(): OptionInterface;
/**
* Unwraps a result, yielding the content of a Success.
*
* @throws Throwable
*/
public function expect(Throwable $throwable): mixed;
/**
* Unwraps a result, yielding the content of an Error.
*
* @throws Throwable
*/
public function expectError(Throwable $throwable): Throwable;
/**
* Returns true if the result is Error.
*/
public function isError(): bool;
/**
* Returns true if the result is Success.
*/
public function isSuccess(): bool;
/**
* Maps a Result to Result by applying a function to a contained Success value, leaving an Error value
* untouched.
*
* @template TMap
*
* @param callable(TValue):TMap $function
*
* @return self
*/
public function map(callable $function): self;
/**
* Maps a Result to Result by applying a function to a contained Error value, leaving a Success value
* untouched.
*
* @template TMapError
*
* @param callable(TValue):TMapError $function
*
* @return self
*/
public function mapError(callable $function): self;
/**
* Returns $result if the result is Error, otherwise returns the Success value of self.
*/
public function or(self $result): self;
/**
* Calls $function if the result is Error, otherwise returns the Success value of self.
*
* @template TOrElse
*
* @param callable(TValue):TOrElse $function
*
* @return self
*/
public function orElse(callable $function): self;
/**
* Converts from Result to Option.
*
* @return OptionInterface
*/
public function success(): OptionInterface;
/**
* Unwraps a result, yielding the content of a Success.
*
* @return TValue
*/
public function unwrap(): mixed;
/**
* Unwraps a result, yielding the content of an Error.
*
* @return TValue
*/
public function unwrapError(): mixed;
/**
* Unwraps a result, yielding the content of a Success. Else, it returns $fallback.
*
* @template TUnwrapOr
*
* @param TUnwrapOr $fallback
*
* @return TUnwrapOr|TValue
*/
public function unwrapOr(mixed $fallback): mixed;
/**
* Unwraps a result, yielding the content of a Success. If the value is an Error then it calls $function with its
* value.
*
* @template TUnwrapOrElse
*
* @param callable(TValue):TUnwrapOrElse $function
*
* @return TUnwrapOrElse|TValue
*/
public function unwrapOrElse(callable $function): mixed;
}
```
## Testing
``` bash
composer test
```
## Changelog
Please see [CHANGELOG.md](./CHANGELOG.md) for more information what has changed recently.
## Security
If you discover any security related issues, please email `[email protected]` instead of using the issue tracker.
## Sponsors
[[`Become a GitHub Sponsor`](https://github.com/sponsors/ghostwriter)]
## Credits
- [Nathanael Esayeas](https://github.com/ghostwriter)
- [All Contributors](https://github.com/ghostwriter/result/contributors)
## License
The BSD-3-Clause. Please see [License File](./LICENSE) for more information.