The class `Facile\PhpCodec\Decoders` provides factory methods for built-in decoders and combinators.

### How to use decoders

```php
use Facile\PhpCodec\Decoders;
use Facile\PhpCodec\Decoder;
use Facile\PhpCodec\Validation\Validation;
use Facile\PhpCodec\Validation\ValidationFailures;
use Facile\PhpCodec\Validation\ValidationSuccess;

/** @var Decoder $decoder */
$decoder = Decoders::intFromString();

/** @var Validation $v1 */
$v1 = $decoder->decode('123');
// Since '123' is a numeric string which represents an integer,
// then we can expect the decoding to be successful.
// Hence, $v1 will be an instance of ValidationSuccess

if($v1 instanceof ValidationSuccess) {
var_dump($v1->getValue());
}

/** @var Validation $v2 */
$v2 = $decoder->decode('hello');
// Similarly, since 'hello' is not a numeric string, we expect
// the decoding fail. $v2 will be an instance of ValidationError

if($v2 instanceof ValidationFailures) {
var_dump($v2->getErrors());
}
```

### Dealing with the validation result

We can use `Validation::fold` to destruct the validation result while providing
a valid result in any case.

```php
use Facile\PhpCodec\Decoders;
use Facile\PhpCodec\Decoder;
use Facile\PhpCodec\Validation\Validation;

/** @var Decoder $decoder */
$decoder = Decoders::intFromString();

Validation::fold(
function (\Facile\PhpCodec\Validation\ValidationFailures $failures): int {
// I may not care about the error.
// Here I want to give a default value when the deconding fails.
return 0;
},
function (\Facile\PhpCodec\Validation\ValidationSuccess $success): int {
return $success->getValue();
},
$decoder->decode($input)
);
```

You can use the path reporter to build well-formatted error messages for failures.

```php
use Facile\PhpCodec\Decoders;

$decoder = Decoders::intFromString();
$v = $decoder->decode('hello');
$msgs = \Facile\PhpCodec\Reporters::path()->report($v);

var_dump($msgs);
/* This will print
array(1) {
[0] =>
string(49) "Invalid value "hello" supplied to : IntFromString"
}
*/
```

## Examples

Take a look to the [examples](https://github.com/facile-it/php-codec/tree/master/tests/examples) folder.

# Reporters

Reporters do create reports from `Validation` objects.
Generally speaking, reporters are objects that implement the `Reporter` interface, given `T` the type of the report that the generate.

One interesting group of reporters is the validation error reporters group.
They implements `Reporter>`.
Thus, given a `Validation` object, they generate a list of error messages for each validation error.

PHP-Codec comes with two error reporters:

- PathReporter, which is a pretty straightforward porting of io-ts' [PathReporter](https://github.com/gcanti/io-ts/blob/master/index.md#error-reporters).
- SimplePathReporter, which is a simplified (read: shorter messages) version of the PathReporter.

```php
$d = Decoders::arrayProps([
'a' => Decoders::arrayProps([
'a1' => Decoders::int(),
'a2' => Decoders::string(),
]),
'b' => Decoders::arrayProps(['b1' => Decoders::bool()])
]);
$v = $d->decode(['a'=> ['a1' => 'str', 'a2' => 1], 'b' => 2]);

$x = \Facile\PhpCodec\Reporters::path()->report($v);
// $x will be
// ['Invalid value "str" supplied to : {a: {a1: int, a2: string}, b: {b1: bool}}/a: {a1: int, a2: string}/a1: int',
// 'Invalid value 1 supplied to : {a: {a1: int, a2: string}, b: {b1: bool}}/a: {a1: int, a2: string}/a2: string',
// 'Invalid value undefined supplied to : {a: {a1: int, a2: string}, b: {b1: bool}}/b: {b1: bool}/b1: bool']