Krak Marshal

A library for marshaling data with a functional design. This is useful for transforming/marshaling data for API output, un-marshaling and hydrating serialized data, or for any other types types of transforming., _(*1)

Usage

 (int) $user->like_count,
                'biography' => substr($user->biography, 0, 64),
                'created_at_ts' => $user->created_at->getTimestamp(),
            ];
        }
    ]);
});

$marshaled = $m($users);

/*
[
    [
        'id' => ...,
        'first_name' => ...,
        'last_name' => ...,
        'biography' => ...,
        'created_at_ts' => ...,
    ],
    ...
]
*/
```

## Accessors

For certain marshalers, you'll want to marshal an entity in the form of the array or object. For that, we have accessors. An accessor implements the `Krak\Marshal\Access` interface.

```php
 1];
$access->has($data, 'a'); // true
$access->has($data, 'b'); // false
$access->get($data, 'a'); // 1
$access->get($data, 'b', 0); // 0
```

## Hydrators

Hydrators are used to marshal array data into an object. Each hydrator is any callable with the following interface

```php
 1,
    'b' => 2,
]);

// $obj now is hydrated with those values
```

## API

### hydrate($class, $hydrator = null)

Creates a marshaler that will hydrate the data with the given `$class` parameter and forwards the `$class` and the `$data` from the marshaler to the `$hydrator`. If no hydrator is supplied, the default `hydrator()` will be used.

```php
 1]);
assert($obj instanceof MyClass);
```

### keyMap($map)

transforms the keys of the data into a new key

### rename(array $map)

renames key fields into a new name

### only(array $fields)

It only includes the given fields. Everything else is filtered out.

### except(array $fields)

It includes all except the given fields. Everything else is kept.

### filter(callable $filter)

Filters the collection via the filter func which has the signature `$filter($value, $key): bool`

### dates($format = 'r')

Formats all instances of `DateTimeInterface` with the given format specifier.

### objectVars()

Converts the properties of an object into an array. This is just an alias of `get_object_vars`.

### typeCast(array $fields, $type)

Type casts the given fields into a specific type.

### pipe($marshalers)

Creates a marshaler that pipes the result of one marshaler into the next marshaler

```php
 1, 'first_name' => 2]);
```

### merge($marshalers)

Creates a marshaler that will apply $marshalers onto a value and then merges all of the results with array_merge. This expects the $marshalers to return arrays.

### keys($fields, Access $acc = null)

Creates a marshaler that retuns the fields of the data

### map($marshaler)

Creates a marshaler which takes a collection and returns an array of each of the marshaled items

### collection($marshalers, Access $acc = null)

Creates a marshaler of a collection based off of the collection of marshalers passed in. Each $marshaler in `$key => $marshaler` will marshal each $value in `$key => $value` based on the `$key`.

### on($marshalers, Access $acc = null)

Similar to `collection`, it marshals the fields of the collection based off of the map of marshalers passed in. The only difference is that it updates the fields in the original collection and returns the entire modified collection.

### stringyKeys($cb)

Maps a key by allowing a stringy instance passed to callback for key manipulation

### underscoredKeys()

Converts the keys to underscore style keys using the `Stringy::underscored` function

### camelizeKeys()

Converts the keys to camelCase style keys using the `Stringy::camelize` function

### identity()

Creates a marshaler for the identity function

### mock($val)

Creates a marshaler that returns $val always. This is useful for testing

### notnull($marshaler)

Creates a marshaler that will not allow null values to be passed to the marshaler. if a null value is passed, it just returns null and doesn't call the marshaler

### hydrator()

Returns a statically cached instance of a default hydrator instance.

### classNameHydrator($hydrator)

Treats the `$class` parameter as a class name and will instantiate a class and delgate to the internal hydrator

### publicPropertyHydrator()

Assigns the properties from array into the `$class` object passed in via publicly accessible properties.

### fromXML()

Parses XML string into an array.

```php

<root a="1">
    <item>Value</item>
    <items>
        <item>1</item>
        <item>2</item>
    </items>
    <map id="1">
        <a>A</a>
        <b>B</b>
    </map>
    <node>
        <![CDATA[<cdata>]]>
    </node>
</root>
XML;
$unmarshal = Krak\Marshal\fromXML();
var_dump($unmarshal($xml));
/** Outputs:
array(5) {
  ["@a"]=>
  string(1) "1"
  ["item"]=>
  string(5) "Value"
  ["items"]=>
  array(1) {
    ["item"]=>
    array(2) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
    }
  }
  ["map"]=>
  array(3) {
    ["@id"]=>
    string(1) "1"
    ["a"]=>
    string(1) "A"
    ["b"]=>
    string(1) "B"
  }
  ["node"]=>
  string(7) "<cdata>"
}
*/