automapper: A PHP repository from acelot

ℹ️ You are on a branch with the second version of the acelot/automapper. If you want a previous version, then proceed to 1.x branch.

AutoMapper is a powerful declarative data mapper for PHP 8. AutoMapper can map data from any source data (usually array/object) to the existing array/object or marshal a new ones.

💿 Install

composer require acelot/automapper:^2.0

🗿 Usage

How to marshal new array from the another?

use Acelot\AutoMapper\Context;
use Acelot\AutoMapper\AutoMapper as a;

$source = [
    'id' => '99',
    'name' => [
        'lastname' => 'Doe',
        'firstname' => 'John',
    ],
    'skills' => 'Php, CSS,JS,html, MySql,  brainfuck,'
];

$result = a::marshalArray(
    new Context(),
    $source,
    a::toKey('id', a::pipe(
        a::get('[id]'),
        a::toInt()
    )),
    a::toKey('fullname', a::pipe(
        a::get('[name]'),
        a::call(fn($v) => $v['firstname'] . ' ' . $v['lastname'])
    )),
    a::toKey('skills', a::pipe(
        a::get('[skills]'),
        a::explodeString(','),
        a::mapIterable(a::pipe(
            a::trimString(),
            a::ifEmpty(a::ignore()),
            a::call('strtolower')
        )),
        a::toArray(),
        a::sortArray()
    ))
);

// Output of `var_export($result)`
array(
  'id' => 99,
  'fullname' => 'John Doe',
  'skills' => [
    0 => 'brainfuck',
    1 => 'css',
    2 => 'html',
    3 => 'js',
    4 => 'mysql',
    5 => 'php',
  ],
)

How to map data from source to the existing array?

Show the code

use Acelot\AutoMapper\Context;
use Acelot\AutoMapper\AutoMapper as a;

$source = [
    'title' => '  Product title  ',
    'desc' => [
        'Product short description',
        'Product regular description',
        'Product descriptive description',
    ]
];

$target = [
    'id' => 5,
    'title' => 'Current title',
];

$result = a::map(
    new Context(),
    $source,
    $target,
    a::toKey('title', a::pipe(
        a::get('[title]'),
        a::trimString()
    )),
    a::toKey('description', a::get('[desc][#last]')),
);

// Output of `var_export($result)`
array (
  'id' => 5,
  'title' => 'Product title',
  'description' => 'Product descriptive description',
)

📌 Examples

All examples can be found in tests/Functional directory.

🗄️ Reference

No need to use concrete classes, it's better to use the AutoMapper API static functions. It is very convenient to import the AutoMapper as a short alias, for example use Acelot\AutoMapper\AutoMapper as a.

Main functions

The main functions of AutoMapper.

Function	Description
`map`	Maps data from the source to the target. Target is passing by reference.
`marshalArray`	Maps data from the source to the keys of the new array.
`marshalObject`	Maps data from the source to the properties of the new `stdClass`.

Field definitions

Definitions that helps you to shape the target structure.

Function	Description
`toKey`	Sets/creates the value by key with given name in the target array.
`toProp`	Sets/creates the value by property with given name in the target object.
`toMethod`	Calls a method with given name with value as an argument in the target object.
`toSelf`	Assigns a value to the target.

Processors

Core value processors. The purpose of processors is to retrieve the value or mutate the incoming value and pass it to the next one.

Function	Description
`assertType`	Asserts the type of value. Throws `UnexpectedValueException` if assert is failed.
`call`	Process the value by user defined function.
`callCtx`	Same as `call` but context will be passed as a first argument.
`condition`	Condition processor. If the user-defined function returns `true`, then the value will be passed to the first processor, otherwise to the second.
`conditionCtx`	Same as `condition` but context will be passed to the user-defined function.
`find`	Finds the element in iterable by the given predicate function.
`findCtx`	Same as `find` but context will be passed to the predicate function.
`get`	Most useful processor. Fetches the value from the source by given path.
`getFromCtx`	Fetches the value from the context.
`ignore`	Always returns the `IgnoreValue`. This value will be ignored by field definition, `mapArray` and `mapIterator`
`mapIterable`	Iterates over elements of an iterable and applies the given sub-processor. ℹ️ Produces values by `yield` operator, so in order to retrieve them you should to iterate the result or call `toArray` helper.
`marshalNestedArray`	The same function as `mapArray` only in the form of a processor. Accepts the value from the previous processor as a source.
`marshalNestedObject`	Same as `marshalNestedArray` only produces object.
`notFound`	Always returns the `NotFoundValue`.
`pass`	This processor do nothing and just returns the value untouched.
`pipe`	Conveyor processor. Accepts multiple sub-processors and pass the value to the first sub-processor, then pass the result of the first to the second, then to the third and so on.
`value`	Just returns the given value.

Helpers

Helpers are the processors that built on top of the another processors. Some helpers are just a shorthands to the core processors with specific arguments, some of them are combination of the multiple processors.

Function	Description
`joinArray`	Joins the incoming array using the given separator. Throws `UnexpectedValueException` if incoming value is not an array.
`sortArray`	Sorts the incoming array using built-in `sort` function. Throws `UnexpectedValueException` if incoming value is not an array.
`uniqueArray`	Returns only unique elements of the incoming array. Throws `UnexpectedValueException` if incoming value is not an array.
`ifNotFound`	Checks if the incoming value is `NotFoundValue` and passes the value to other processors depending on the result.
`ifEmpty`	Same as `ifNotFound` but checks if the value is `empty`.
`ifNull`	Same as `ifNotFound` but checks if the value `is_null`.
`IfEqual`	Checks if the incoming value is equal to the given value.
`ifNotEqual`	Checks if the incoming value is not equal to the given value.
`explodeString`	Splits the incoming string into parts using built-in `explode` function. Throws `UnexpectedValueException` if incoming value is not a string.
`trimString`	Trims the incoming string using built-in `trim` function. Throws `UnexpectedValueException` if incoming value is not a string.
`toBool`	Converts the incoming value to boolean type.
`toFloat`	Converts the incoming value to float type. Throws `UnexpectedValueException` if incoming value is not a scalar.
`toInt`	Converts the incoming value to integer type. Throws `UnexpectedValueException` if incoming value is not a scalar.
`toString`	Converts the incoming value to string type. Throws `UnexpectedValueException` if incoming value is not a scalar or an object that not implements `__toString`.
`toArray`	Converts the incoming value to array. Usually used with `mapIterable` processor.

🧩 Integrations

Name	Description
`RespectValidation`	Provides validation processor via `respect/validation` library.

🤨 FAQ

What is Context?

The Context is a special DTO class for storing any kind of data: configs, DB connections, fixtures, etc. This DTO is passed to the mapper, and you can use your data inside the processors. Processors capable of working with the context end with Ctx suffix, callCtx for example.

How to use `get` processor?

You can obtain any key/prop/method from the source using the get processor which accepts a special path string. The processor parses the given path and divides it into parts, then pulls out the data following the parts of the path.

Available path parts:

Part	Description
`@`	"Self Pointer" – returns the source itself
`[0]`	Returns an array value by index
`[key]`	Returns an array value by key
`[some key]`	Returns an array value by key with spaces
`[#first]`	Returns an array first value
`[#last]`	Returns an array last value
`->property`	Returns an object value by property
`->{some property}`	Returns an object value by property name with spaces
`->someMethod()`	Calls an object method and returns the value

You can combine the parts to obtain the deep values:

[array_key][array key with spaces][#first][#last]->property->{property with spaces}->someMethod()

If any part of the path is not found, then the processor will return NotFoundValue value. This value throws an NotFoundException but you can recover it using ifNotFound helper.

acelot/automapper