<commit_before>Php Try type
============

A Try type for PHP.

The Try type is useful when called code will either return a value (Success) or
throw an exception (Failure). Instead of relying on the `try {} catch {}`
mechanism to handle this cases, the fact that code might either throw or return
a value is now encoded in its return type.

The type shows it usefulness with it's ability to create a "pipeline"
operations, catching exceptions along the way.

> Note: this implementation of the Try type is called Attempt, because "try" is
> a reserved keyword in PHP.

## Installation

Run:

```
composer require phptry/phptry
```
or add it to your `composer.json` file.

## Usage

> Note: most of the example code below can be tried out with the
> `user-input.php` example from the `examples/` directory.

### Constructing an Attempt

Turn any callable in an `Attempt` using the `Attempt::call()` construct it.

```php
\PhpTry\Attempt::call('callableThatMightThrow', array('argument1', 'argument2'));
```

Or use `Success` and `Failure` directly in your API instead of throwing exceptions:

```php<commit_msg>Add a before/after example that will probably lead to more confusion ;)<commit_after>Php Try type
============

A Try type for PHP.

The Try type is useful when called code will either return a value (Success) or
throw an exception (Failure). Instead of relying on the `try {} catch {}`
mechanism to handle this cases, the fact that code might either throw or return
a value is now encoded in its return type.

The type shows it usefulness with it's ability to create a "pipeline"
operations, catching exceptions along the way.

> Note: this implementation of the Try type is called Attempt, because "try" is
> a reserved keyword in PHP.

## Before / after

Before, the `UserService` and `Serializer` code might throw exceptions, so we
have an explicit try/catch:

```php
try {
    $user = $userService->findBy($id);
    $responseBody = $this->serializeUser($user);

    return new Response($user);
} catch (Exception $ex) {
    return Response('error', 500);
}
```

After, the `UserService` and `Serializer` now return a response of type `Try`
meaning that the computation will either be a `Failure` or a `Success`. The
combinators on the `Try` type are used to chain the following code in the case
the previous operation was successful.

```php
return $userService->findBy($id)
    ->flatMap(function($user) { return $this->serializeUser($user); }) // walk the happy path!
    ->map(function($responseBody) { return new Response($responseBody); })
    ->recover(function($ex) { return new Response('error', 500); })
    ->get(); // returns the wrapped value
```

## Installation

Run:

```
composer require phptry/phptry
```
or add it to your `composer.json` file.

## Usage

> Note: most of the example code below can be tried out with the
> `user-input.php` example from the `examples/` directory.

### Constructing an Attempt

Turn any callable in an `Attempt` using the `Attempt::call()` construct it.

```php
\PhpTry\Attempt::call('callableThatMightThrow', array('argument1', 'argument2'));
```

Or use `Success` and `Failure` directly in your API instead of throwing exceptions:

```php
{'fraction_non_alphanumeric': 0.11173533083645443, 'fraction_numerical': 0.003121098626716604, 'mean_word_length': 4.506872852233677, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7401590', 'n_tokens_mistral': 924, 'n_tokens_neox': 881, 'n_words': 425}