Download the PHP package stasa87/auto-mapper-plus without Composer

On this page you can find all versions of the php package stasa87/auto-mapper-plus. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of stasa87/auto-mapper-plus

Informations about the package auto-mapper-plus

AutoMapper+

An automapper for PHP inspired by .NET's automapper. Transfers data from one object to another, allowing custom mapping operations.

Build Status

Table of Contents

Installation

This library is available on packagist:

If you're using Symfony, check out the AutoMapper+ bundle.

Why?

When you need to transfer data from one object to another, you'll have to write a lot of boilerplate code. For example when using view models, CommandBus commands, working with API responses, etc.

Automapper+ helps you by automatically transferring properties from one object to another, including private ones. By default, properties with the same name will be transferred. This can be overridden as you like.

Example usage

Suppose you have a class Employee and an associated DTO.

The following snippet provides a quick overview on how the mapper can be configured and used:

In depth

Instantiating the AutoMapper

The AutoMapper has to be provided with an AutoMapperConfig, which holds the registered mappings. This can be done in 2 ways:

Passing it to the constructor:

Using the static constructor:

Using the AutoMapper

Once configured, using the AutoMapper is pretty straightforward:

Registering mappings

Mappings are defined using the AutoMapperConfig's registerMapping() method. Every mapping has to be explicitly defined before you can use it.

A mapping is defined by providing the source class and the destination class. The most basic definition would be as follows:

This will allow objects of the Employee class to be mapped to EmployeeDto instances. Since no extra configuration is provided, the mapping will only transfer properties with the same name.

Custom callbacks

With the forMember() method, you can specify what should happen for the given property of the destination class. When you pass a callback to this method, the return value will be used to set the property.

The callback receives the source object as argument.

Operations

Behind the scenes, the callback in the previous example is wrapped in a MapFrom operation. Operations represent the action that should be performed for the given property.

The following operations are provided:

Name Explanation
MapFrom Maps the property from the value returned from the provided callback.
Ignore Ignores the property.
MapTo Maps the property to another class. Allows for nested mappings. Supports both single values and collections.
FromProperty Use this to explicitly state the source property name.
DefaultMappingOperation Simply transfers the property, taking into account the provided naming conventions (if there are any).
MapFromWithMapper Similar to MapFrom.
Compared to mapFrom, the callback has access to a instance of AutoMapperInterface. Define the second callback argument of AutoMapperInterface type. Accessible by using
- Operation::mapFromWithMapper(function($source, AutoMapperInterface $mapper){ ... })
- new mapFromWithMapper(function($source, AutoMapperInterface $mapper){ ... })

You can use them with the same forMember() method. The Operation class can be used for clarity.

Example of using MapFromWithMapper:

You can create your own operations by implementing the MappingOperationInterface. Take a look at the provided implementations for some inspiration.

If you need to have the automapper available in your operation, you can implement the MapperAwareInterface, and use the MapperAwareTrait. The default MapTo and MapFromWithMapper operations use these.

Dealing with nested mappings

Nested mappings can be registered using the MapTo operation. Keep in mind that the mapping for the child class has to be registered as well.

MapTo supports both single entities and collections.

Handling object construction

You can specify how the new destination object will be constructed (this isn't relevant if you use mapToObject). You can do this by registering a factory callback. This callback will be passed the source object.

Another option is to skip the constructor all together. This can be set using the options.

ReverseMap

Since it is a common use case to map in both directions, the reverseMap() method has been provided. This creates a new mapping in the alternate direction.

reverseMap will keep the registered naming conventions into account, if there are any.

Note: reverseMap() simply creates a completely new mapping in the reverse direction, using the default options. However, every operation you defined with forMember that implements the Reversible interface, gets defined for the new mapping as well. Currently, only fromProperty supports being reversed.

To make things more clear, take a look at the following example:

Copying a mapping

When defining different view models, it can occur that you have lots of similar properties. For example, with a ListViewModel and a DetailViewModel. This means that the mapping configuration will be similar as well.

For this reason, it is possible to copy a mapping. In practice this means that all the options will be copied, and all the explicitly defined mapping operations.

After copying the mapping, you're free to override operations or options on the new mapping.

Resolving property names

Unless you define a specific way to fetch a value (e.g. mapFrom), the mapper has to have a way to know which source property to map from. By default, it will try to transfer data between properties of the same name. There are, however, a few ways to alter this behaviour.

If a source property is specifically defined (e.g. FromProperty), this will be used in all cases.

Naming conventions

You can specify the naming conventions followed by the source & destination classes. The mapper will take this into account when resolving names.

For example:

The following conventions are provided (more to come):

You can implement your own by using the NamingConventionInterface.

Explicitly state source property

As mentioned earlier, the operation FromProperty allows you to explicitly state what property of the source object should be used.

You should read the previous snippet as follows: "For the property named 'id' on the destination object, use the value of the 'identifier' property of the source object".

FromProperty is Reversible, meaning that when you apply reverseMap(), AutoMapper will know how to map between the two properties. For more info, read the section about reverseMap.

Resolving names with a callback

Should naming conventions and explicitly stating property names not be sufficient, you can resort to a CallbackNameResolver (or implement your own NameResolverInterface).

This CallbackNameResolver takes a callback as an argument, and will use this to transform property names.

The Options object

The Options object is a value object containing the possible options for both the AutoMapperConfig and the Mapping instances.

The Options you set for the AutoMapperConfig will act as the default options for every Mapping you register. These options can be overridden for every mapping.

For example:

The available options that can be set are:

Name Default value Comments
Source naming convention null The naming convention of the source class (e.g. CamelCaseNamingConversion). Also see naming conventions.
Destination naming convention null See above.
Skip constructor true whether or not the constructor should be skipped when instantiating a new class. Use $options->skipConstructor() and $options->dontSkipConstructor() to change.
Property accessor PropertyAccessor Use this to provide an alternative implementation of the property accessor.
Default mapping operation DefaultMappingOperation the default operation used when mapping a property. Also see mapping operations
Default name resolver NameResolver The default class to resolve property names
Custom Mapper null Grants the ability to use a custom mapper.
Object crates [\stdClass::class] See the dedicated section.

Setting the options

For the AutoMapperConfig

You can set the options for the AutoMapperConfig by retrieving the object:

Alternatively, you can set the options by providing a callback to the constructor. The callback will be passed an instance of the default Options:

For the Mappings

A mapping also has the getOptions method available. However, chainable helper methods exist for more convenient overriding of the options:

Setting options via a callable has been provided for mappings as well, using the setDefaults() method:

Mapping with stdClass

As a side note it is worth mentioning that it is possible to map from and to stdClass. Mapping from stdClass happens as you would expect, copying properties to the new object.

Mapping to \stdClass requires some explanation. All properties available on the provided source object are copied to the \stdClass as public properties. It's still possible to define operations for individual properties (for example, to ignore a property).

Naming conventions will be taken into account, so keep this in mind when defining operations. The property name has to match the naming convention of the target.

The concept of object crates

As suggested and explained in this issue, AutoMapper+ uses object crates to allow mapping to \stdClass. This means you can register your own classes as well to be an object crate. This makes the mapper handle it exactly as \stdClass, writing all source properties to public properties on the target.

Registering object crates can be done using the Options.

Using a custom mapper

This library attempts to make registering mappings painless, with as little configuration as possible. However, cases exist where a mapping requires a lot of custom code. This code would look a lot cleaner if put in its own class. Another reason to resort to a custom mapper would be performance.

It is therefore possible to specify a custom mapper class for a mapping. This mapper has to implement the MapperInterface. For your convenience, a CustomMapper class has been provided that implements this interface.

Misc

Similar libraries

When picking a library, it's important to see what options are available. No library is perfect, and they all have their pro's and con's.

A few other object mappers exist for PHP. They're listed here with a short description, and are definitely worth checking out!

Performance benchmarks (credit goes to idr0id):

Runtime: PHP 7.1.8-1
Host: Linux 4.13.0-1-amd64 #1 SMP Debian 4.13.4-2 (2017-10-15) x86_64
Collection size: 10000

package duration (MS) MEM (B)
native php 3 6291456
idr0id/papper 39 6291456
trismegiste/alkahest 116 16777216
nylle/php-automapper 188 16777216
mark-gerarts/auto-mapper-plus 291 16777216
bcc/auto-mapper-bundle 716 6291456

Up-to-date benchmarks can be found here.

See also

Roadmap

All versions of auto-mapper-plus with dependencies

PHP Build Version
Package Version
Requires lstrojny/functional-php Version ^1.4
php Version ^5.6 || ^7.2
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package stasa87/auto-mapper-plus contains the following files

Loading the files please wait ....