Table of Contents

Installation

$ composer require"mark-gerarts/auto-mapper-plus"

Why?

Example usage

<?phpclass Employee{private$id;private$firstName;private$lastName;private$birthYear;publicfunction__construct($id,$firstName,$lastName,$birthYear)    {$this->id =$id;$this->firstName =$firstName;$this->lastName =$lastName;$this->birthYear =$birthYear;    }publicfunctiongetId()    {return$this->id;    }// And so on...}class EmployeeDto{// While the properties are public for this example, we can map to private// or protected properties just the same.public$firstName;public$lastName;public$age;}

<?phpuseAutoMapperPlus\Configuration\AutoMapperConfig;useAutoMapperPlus\AutoMapper;$config =newAutoMapperConfig();// Simply registering the mapping is enough to convert properties with the same// name. Custom actions can be registered for each individual property.$config    ->registerMapping(Employee::class, EmployeeDto::class)    ->forMember('age',function (Employee$source) {returndate('Y') -$source->getBirthYear();    })    ->reverseMap();// Register the reverse mapping as well.$mapper =newAutoMapper($config);// With this configuration we can start converting our objects.$john =newEmployee(10,"John","Doe",1980);$dto =$mapper->map($john, EmployeeDto::class);echo$dto->firstName;// => "John"echo$dto->lastName;// => "Doe"echo$dto->age;// => 37

In depth

Instantiating the AutoMapper

<?phpuseAutoMapperPlus\Configuration\AutoMapperConfig;useAutoMapperPlus\AutoMapper;$config =newAutoMapperConfig();$config->registerMapping(Source::class, Destination::class);$mapper =newAutoMapper($config);

<?php$mapper = AutoMapper::initialize(function (AutoMapperConfig$config) {$config->registerMapping(Source::class, Destination::class);$config->registerMapping(AnotherSource::class, Destination::class);// ...});

Using the AutoMapper

<?php$john =newEmployee("John","Doe",1980);// Map the source object to a new instance of the destination class.$mapper->map($john, EmployeeDto::class);// Mapping to an existing object is possible as well.$mapper->mapToObject($john,newEmployeeDto());// Map a collection using mapMultiple$mapper->mapMultiple($employees, EmployeeDto::class);

Registering mappings

<?php$config->registerMapping(Employee::class, EmployeeDto::class);

Custom callbacks

<?php$config->registerMapping(Employee::class, EmployeeDto::class)    ->forMember('fullName',function (Employee$source) {return$source->getFirstName() .'' .$source->getLastName();    });

Operations

<?php$getName =function ($source,AutoMapperInterface$mapper) {return'John'; };$mapping->forMember('name',$getName);// The above is a shortcut for the following:$mapping->forMember('name', Operation::mapFrom($getName));// Which in turn is equivalent to:$mapping->forMember('name',newMapFrom($getName));// Other examples:// Ignore this property.$mapping->forMember('id', Operation::ignore());// Map this property to the given class.$mapping->forMember('employee', Operation::mapTo(EmployeeDto::class));// Explicitly state what the property name is of the source object.$mapping->forMember('name', Operation::fromProperty('unconventially_named_property'));// The `FromProperty` operation can be chained with `MapTo`, allowing a// differently named property to be mapped to a class.$mapping->forMember('address',    Operation::fromProperty('adres')->mapTo(Address::class));// SetTo sets the property to the given value.$mapping->forMember('type', Operation::setTo('employee'));// An extended example showing you can access the mapper in `MapFrom`.$getColorPalette =function(SimpleXMLElement$XMLElement,AutoMapperInterface$mapper) {/** @var SimpleXMLElement $palette */$palette =$XMLElement->xpath('/product/specification/palette/colour');return$mapper->mapMultiple($palette, Color::class);};$mapping->forMember('palette',$getColorPalette);

<?php// This assumes address is an object, or a collection of mappable// objects if the source is an array/iterable.$mapping->forMember('address', Operation::mapTo(Address::class));// This is equivalent to:$mapping->forMember('address', Operation::mapTo(Address::class,false));// If you want to be very specific about the source being a collection, you// can use `mapCollectionTo`. This is purely syntactic sugar; it is equivalent// to the declarations above as well.$mapping->forMember('addresses', Operation::mapCollectionTo(Address::class));// On the other hand, if the source is an array that represents an object, you// can use the following:$mapping->forMember('address', Operation::mapTo(Address::class,true));// Or nicer$mapping->forMember('address', Operation::mapArrayTo(Address::class));

Dealing with polymorphic properties

<?php// This iterates over every property of the source property// 'polymorphicChildren'. Each value will be mapped to the first existing// mapping from the value to one of the given classes.$config->createMapping(ChildA::class, ChildADto::class);$config->createMapping(ChildB::class, ChildBDto::class);$config->createMapping(Parent::class, ParentDto::class)    ->forMember('polymorphicChildren',        Operation::mapToAnyOf([ChildADto::class, ChildBDto::class]    ));

Dealing with nested mappings

<?php$config->registerMapping(Child::class, ChildDto::class);$config->registerMapping(Parent::class, ParentDto::class)    ->forMember('child', Operation::mapTo(ChildDto::class));

Handling object construction

<?php$config->registerMapping(Source::class, Destination::class)    ->beConstructedUsing(function (Source$source,AutoMapperInterface$mapper):Destination {returnnewDestination($source->getProperty());    });

<?php// Either set it in the options:$config->getOptions()->skipConstructor();$mapper =newAutoMapper($config);// Or set it on the mapping directly:$config->registerMapping(Source::class, Destination::class)->skipConstructor();

ReverseMap

<?php// reverseMap() returns the new mapping, allowing to continue configuring the// new mapping.$config->registerMapping(Employee::class, EmployeeDto::class)    ->reverseMap()    ->forMember('id', Operation::ignore());$config->hasMappingFor(Employee::class, EmployeeDto::class);// => True$config->hasMappingFor(EmployeeDto::class, Employee::class);// => True

<?php// Source class properties:         Destination class properties:// - 'some_property',               - 'some_property'// - 'some_alternative_property'    - 'some_other_property'// - 'the_last_property'            - 'the_last_property'//$config->registerMapping(Source::class, Destination::class)    ->forMember('some_property', Operation::ignore())    ->forMember('some_other_property', Operation::fromProperty('some_alternative_property'))    ->reverseMap();// When mapping from Source to Destination, the following will happen:// - some_property gets ignored// - some_other_property gets mapped by using the value form some_alternative_property// - the_last_property gets mapped because the names are equal.//// Now, when we go in the reverse direction things are different:// - some_property gets mapped, because Ignore is not reversible// - some_alternative_property gets mapped because FromProperty is reversible// - the_last_property gets mapped as well

Copying a mapping

<?php$detailMapping =$config->registerMapping(Employee::class, EmployeeDetailView::class)// Define operations and options ...    ->forMember('age',function () {return20;    });// You can copy a mapping by passing source and destination class. This will// search the config for the relevant mapping.$listMapping =$config->registerMapping(Employee::class, EmployeeListView::class)    ->copyFrom(Employee::class, EmployeeDetailView::class)// Alternatively, copy a mapping by passing it directly.// ->copyFromMapping($detailMapping)//// You can now go ahead and define new operations, or override existing// ones.    ->forMember('name', Operation::ignore())    ->skipConstructor();

Automatic creation of mappings

<?php$config->getOptions()->createUnregisteredMappings();

Resolving property names

Naming conventions

<?phpuseAutoMapperPlus\NameConverter\NamingConvention\CamelCaseNamingConvention;useAutoMapperPlus\NameConverter\NamingConvention\SnakeCaseNamingConvention;$config->registerMapping(CamelCaseSource::class, SnakeCaseDestination::class)    ->withNamingConventions(newCamelCaseNamingConvention(),// The naming convention of the source class.newSnakeCaseNamingConvention()// The naming convention of the destination class.    );$source =newCamelCaseSource();$source->propertyName ='camel';$result =$mapper->map($source, SnakeCaseDestination::class);echo$result->property_name;// => "camel"

Explicitly state source property

<?php$config->registerMapping(Source::class, Destination::class)    ->forMember('id', Operation::fromProperty('identifier'));

Resolving names with a callback

<?phpclass Uppercase{public$IMAPROPERTY;}class Lowercase{public$imaproperty;}$uppercaseResolver =newCallbackNameResolver(function ($targetProperty) {returnstrtolower($targetProperty);});$config->registerMapping(Uppercase::class; Lowercase::class)    ->withNameResolver($uppercaseResolver);$uc =newUppercase();$uc->IMAPROPERTY ='value';$lc =$mapper->map($uc, Lowercase::class);echo$lc->imaproperty;// => "value"

The Options object

<?php$config =newAutoMapperConfig();$config->getOptions()->setDefaultMappingOperation(Operation::ignore());$defaultMapping =$config->registerMapping(Source::class, Destination::class);$overriddenMapping =$config->registerMapping(AnotherSource::class, Destination::class)    ->withDefaultOperation(newDefaultMappingOperation());$defaultMapping->getOptions()->getDefaultMappingOperation();// => Ignore$overriddenMapping->getOptions()->getDefaultMappingOperation();// => DefaultMappingOperation

Setting the options

For the AutoMapperConfig

<?php$config =newAutoMapperConfig();$config->getOptions()->dontSkipConstructor();

<?php// This will set the options for this specific mapping.$config =newAutoMapperConfig(function (Options$options) {$options->dontSkipConstructor();$options->setDefaultMappingOperation(Operation::ignore());// ...});

For the Mappings

<?php$config->registerMapping(Source::class, Destination::class)    ->skipConstructor()    ->withDefaultOperation(Operation::ignore());

<?php$config->registerMapping(Source::class, Destination::class)    ->setDefaults(function (Options$options) {$options->dontSkipConstructor();// ...    });

Mapping with stdClass

<?php// Register the mapping.$config->registerMapping(\stdClass::class, Employee::class);$mapper =newAutoMapper($config);$employee =new \stdClass();$employee->firstName ='John';$employee->lastName ='Doe';$result =$mapper->map($employee, Employee::class);echo$result->firstName;// => "John"echo$result->lastName;// => "Doe"

<?php// Operations can still be registered.$config->registerMapping(Employee::class, \stdClass::class)    ->forMember('id', Operation::ignore());$mapper =newAutoMapper($config);$employee =newEmployee(5,'John','Doe',1978);$result =$mapper->map($employee, \stdClass::class);echo$result->firstName;// => "John"echo$result->lastName;// => "Doe"var_dump(isset($result->id));// => bool(false)

<?php$config->registerMapping(CamelCaseSource::class, \stdClass::class)    ->withNamingConventions(newCamelCaseNamingConvention(),newSnakeCaseNamingConvention()    )// Operations have to be defined using the target property name.    ->forMember('some_property',function () {return'new value'; });$mapper =newAutoMapper($config);$source =newCamelCaseSource();$source->someProperty ='original value';$source->anotherProperty ='Another value';$result =$mapper->map($employee, \stdClass::class);var_dump(isset($result->someProperty));// => bool(false)echo$result->some_property;// => "new value"echo$result->another_property;// => "Another value"

The concept of object crates

<?phpclass YourObjectCrate { }$config =newAutoMapperConfig();// (Or pass a callable to the constructor)$config->getOptions()->registerObjectCrate(YourObjectCrate::class);$config->registerMapping(Employee::class, YourObjectCrate::class);$mapper =newAutoMapper($config);$employee =newEmployee(5,'John','Doe',1978);$result =$mapper->map($employee, YourObjectCrate::class);echo$result->firstName;// => "John"echo$result->lastName;// => "Doe"echoget_class($result);// => "YourObjectCrate"

Mapping with arrays

<?php$config->registerMapping('array', Employee::class);// Alternatively, use the enum DataType::ARRAY// Adding operations works just as you would expect.$config->registerMapping(DataType::ARRAY, Employee::class)    ->forMember('id', Operation::ignore())    ->forMember('type', Operation::setTo('employee'))// Since arrays are oftentimes snake_case'd.    ->withNamingConventions(newSnakeCaseNamingConvention(),newCamelCaseNamingConvention()    );// It is now possible to map an array to an employee:$employee = ['id' =>5,'first_name' =>'John','last_name' =>'Doe'];$result =$mapper->map($employee, Employee::class);echo$result->firstName;// => "John"echo$result->id;// => nullecho$result->type;// => "employee"

Using a custom mapper

<?php// You can either extend the CustomMapper, or just implement the MapperInterface// directly.class EmployeeMapperextends CustomMapper{/**     * @param Employee $source     * @param EmployeeDto $destination     * @return EmployeeDto     */publicfunctionmapToObject($source,$destination)    {$destination->id =$source->getId();$destination->firstName =$source->getFirstName();$destination->lastName =$source->getLastName();$destination->age =date('Y') -$source->getBirthYear();return$destination;    }}$config->registerMapping(Employee::class, EmployeeDto::class)    ->useCustomMapper(newEmployeeMapper());$mapper =newAutoMapper($config);// The AutoMapper can now be used as usual, but your custom mapper class will be// called to do the actual mapping.$employee =newEmployee(10,'John','Doe',1980);$result =$mapper->map($employee, EmployeeDto::class);

Adding context

<?php// This example shows how for example the current locale can be passed to alter// the mapping behaviour.$config->registerMapping(Employee::class, EmployeeDto::class)    ->forMember('honorific',function ($source,AutoMapperInterface$mapper,array$context):string {$translationKey ="honorific.{$source->getGender()}";return$this->translator->trans($translationKey,$context['locale']);        }    );// Usage:$mapper->map($employee, EmployeeDto::class, ['locale' =>$request->getLocale()]);

Misc

Similar libraries

See also

A note on PHPStan

Method AutoMapperPlus\MapperInterface::map() invoked with 3 parameters, 2 required.

Roadmap