ℹ️ 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.

🖋️ License

Licensed under MIT. Copyright (c) 2017-present, Valeriy Protopopov