AutoMapper

https://github.com/jolicode/automapper
Admin
AutoMapper is a blazing fast data mapper for PHP that eliminates tedious object-to-object mapping...
Tokens:100,178
Snippets:657
Trust Score:10
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install AutoMapper with Composer

Source: https://github.com/jolicode/automapper/blob/main/README.md

Install the AutoMapper library via Composer. This is the first step in the Quick Start guide.

```shell
composer require jolicode/automapper
```

--------------------------------

### Full YAML configuration example for automapper bundle

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/configuration.md

Example configuration file for the AutoMapper bundle, typically placed at config/packages/automapper.yaml. Shows all available options with their default or example values, including class_prefix, constructor_strategy, date_time_format, normalizer, loader, json_streamer, and mapping paths.

```yaml
automapper:
  class_prefix: "Symfony_Mapper_"
  constructor_strategy: 'auto'
  date_time_format: !php/const DateTimeInterface::RFC3339
  check_attributes: true
  check_groups: true
  auto_register: true
  map_private_properties: true
  allow_readonly_target_to_populate: false
  remove_default_properties: true
  normalizer:
    enabled: false
    only_registered_mapping: false
    priority: 1000
  loader:
    eval: false
    cache_dir: "%kernel.cache_dir%/automapper"
    reload_strategy: "always"
  json_streamer:
    enabled: false
    only_registered_mapping: false
  serializer_attributes: true
  api_platform: false
  object_mapper: false
  name_converter: null
  mapping:
    paths:
      - "%kernel.project_dir%/src/Entity"
    mappers:
      - source: AutoMapper\Bundle\Tests\Fixtures\User
        target: AutoMapper\Bundle\Tests\Fixtures\UserDTO
        reverse: false

```

--------------------------------

### Map data with AutoMapper

Source: https://github.com/jolicode/automapper/blob/main/README.md

Create an AutoMapper instance and map data to a target class. This is the second step in the Quick Start guide, after installation.

```php
$mapper = AutoMapper::create();
$target = $mapper->map($data, Target::class);
```

--------------------------------

### Example: Using source type in supports()

Source: https://github.com/jolicode/automapper/blob/main/docs/upgrading/upgrading-10.0.md

An example of using the new signature to check if the source type is nullable, returning false if it is.

```php
class MyTransformer implements PropertyTransformerSupportInterface
{
    public function supports(SourcePropertyMetadata $source, TargetPropertyMetadata $target, MapperMetadata $mapperMetadata): bool
    {
        if ($source->type->isNullable()) {
            return false;
        }
        
        // ...
    }
}
```

--------------------------------

### Install json_stream extension with pie

Source: https://github.com/jolicode/automapper/blob/main/bench/README.md

Install the json_stream PHP extension with pie to get the ~6.7x read-path speedup. The write path is unaffected because it does not decode.

```shell
pie install joelwurtz/json-stream
```

--------------------------------

### Install benchmark dependencies

Source: https://github.com/jolicode/automapper/blob/main/bench/README.md

Installs the benchmark dependencies. The package depends on the checked-out AutoMapper via a Composer path repository, so it always benchmarks your working copy.

```bash
cd bench
composer install
```

--------------------------------

### Priority example with two #[Mapper] attributes

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/mapper-attribute.md

Shows how priority determines which attribute is used when multiple are defined for the same mapping.

```php
#[Mapper(source: EntityDto::class, constructorStrategy: ConstructorStrategy::NEVER, priority: 2)]
class Entity
{
    public string $foo;
}

#[Mapper(constructorStrategy: ConstructorStrategy::ALWAYS, priority: 1)]
class EntityDto
{
    public string $foo;
}
```

--------------------------------

### Create AutoMapper with custom Configuration

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/configuration.md

Shows how to instantiate a Configuration object with all options and pass it to AutoMapper::create(). The example sets classPrefix to 'Mapper_', constructorStrategy to 'auto', and other options to customize mapper generation.

```php
use AutoMapper\Configuration;
use AutoMapper\AutoMapper;

$configuration = new Configuration(
    classPrefix: 'Mapper_'
    constructorStrategy: 'auto',
    dateTimeFormat: \DateTimeInterface::RFC3339,
    attributesChecking: true,
    groupsChecking: true,
    autoRegister: true,
    mapPrivateProperties: true,
    allowReadonlyTargetToPopulate: false,
    strictTypes: false,
    reloadStrategy: \AutoMapper\Loader\FileReloadStrategy::ON_CHANGE,
    allowExtraProperties: false,
    extractTypesFromGetter: false,
);
$autoMapper = AutoMapper::create(configuration: $configuration);
```

--------------------------------

### map.php example returning an iterator

Source: https://github.com/jolicode/automapper/blob/main/tests/AutoMapperTest/README.md

Example of a map.php file that returns an iterator to provide multiple test cases. It yields named cases 'ok' and 'ko' with different input data.

```php
<?php

// ....

return (function () {
    $autoMapper = AutoMapperBuilder::buildAutoMapper();

    $user = ['name' => 'foo', 'int' => ['foo' => 1]];
    yield 'ok' => $autoMapper->map($user, UserConstructorDTOWithRelation::class);

    $user = ['name' => 'foo', 'int' => ['foo' => 2]];
    yield 'ko' => $autoMapper->map($user, UserConstructorDTOWithRelation::class);
})();
```

--------------------------------

### map.php example for BuiltinClass

Source: https://github.com/jolicode/automapper/blob/main/tests/AutoMapperTest/README.md

Example of a map.php file that returns a mapped array. It defines a BuiltinClass with a DateInterval property and uses AutoMapperBuilder to map it to an array.

```php
<?php
// tests/AutoMapperTest/BuiltinClass/map.php

declare(strict_types=1);

namespace AutoMapper\Tests\AutoMapperTest\BuiltinClass;

use AutoMapper\Tests\AutoMapperBuilder;

class BuiltinClass
{
    public function __construct(
        public \DateInterval $dateInterval
    ) {
    }
}

return AutoMapperBuilder::buildAutoMapper()->map(new BuiltinClass(new \DateInterval('P1Y')), 'array');
```

--------------------------------

### User and Address classes with nested objects

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/identifier.md

Example classes showing a User with an array of Address objects, used to illustrate the need for identifier-based mapping.

```php
class User 
{
    public string $name;
    /** @var Address[] */
    public array $address;
}

class Address 
{
    public string $id;
    public string $street;
    public string $city;
}
```

--------------------------------

### MapTo on a class for virtual properties

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/attributes.md

Use #[MapTo] on a class to add virtual properties. Here, the class Entity gets a virtual property 'virtualProperty'.

```php
#[MapTo(property: 'virtualProperty')]
class Entity {}
```

--------------------------------

### Read a collection with MapperContext::STREAM option

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/json-streamer.md

PHP example showing how to pass the MapperContext::STREAM option to the reader to keep memory usage flat when reading a collection only once. The collection is buffered by default, but this option disables buffering.

```php
use AutoMapper\MapperContext;

$users = $streamReader->read($stream, Type::list(Type::object(User::class)), [
    MapperContext::STREAM => true,
]);
```

--------------------------------

### Write a collection with MapperContext::STREAM option

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/json-streamer.md

PHP example showing how to stream a collection to JSON chunk by chunk using the MapperContext::STREAM option. Iterating the returned value yields chunks without building the whole string, while casting to string gives the full payload.

```php
$result = $streamWriter->write($users, Type::list(Type::object(User::class)), [
    MapperContext::STREAM => true,
]);

foreach ($result as $chunk) {
    echo $chunk;
}
```

--------------------------------

### Use #[Mapper] attribute with multiple targets

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/cache-warmup.md

You can specify an array of sources and/or targets to generate multiple mappers at once. This example generates mappers from 'array' to 'Entity' and from 'array' to EntityDto.

```php
#[Mapper(source: 'array', target: ['array', EntityDto::class])]
class Entity
{
    public string $foo;
}
```

--------------------------------

### Read a lazy collection of objects

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/json-streamer.md

PHP example showing how to read a JSON array of objects as a lazy collection. Elements are decoded and mapped one at a time, so a large payload never has to be held in memory at once.

```php
$users = $streamReader->read($stream, Type::list(Type::object(User::class)));

foreach ($users as $user) {
    // $user is a fully mapped User
}
```

--------------------------------

### Use #[Mapper] attribute with source and target

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/cache-warmup.md

The #[Mapper] attribute requires a source and/or target argument to specify the mapping. This example generates a mapper from 'array' to 'Entity' and vice versa during cache warmup.

```php
#[Mapper(source: 'array', target: 'array')]
class Entity
{
    public string $foo;
}
```

--------------------------------

### Inject and use StreamReaderInterface and StreamWriterInterface

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/json-streamer.md

PHP example showing how to inject the standard Symfony JsonStreamer interfaces and use them to read JSON into objects and write objects to JSON. The AutoMapper decorates these services, so the same interfaces are used.

```php
use Symfony\Component\JsonStreamer\StreamReaderInterface;
use Symfony\Component\JsonStreamer\StreamWriterInterface;
use Symfony\Component\TypeInfo\Type;

final readonly class UserController
{
    public function __construct(
        private StreamReaderInterface $streamReader,
        private StreamWriterInterface $streamWriter,
    ) {
    }

    public function __invoke(mixed $stream): iterable
    {
        // JSON -> objects
        $user = $this->streamReader->read($stream, Type::object(User::class));

        // objects -> JSON, chunk by chunk
        return $this->streamWriter->write($user, Type::object(User::class));
    }
}
```

--------------------------------

### Run PHPBench benchmarks

Source: https://github.com/jolicode/automapper/blob/main/bench/README.md

Commands to run the benchmarks. The first runs everything with timing and peak memory. The second runs a single scenario. The third focuses on memory using a custom report defined in phpbench.json. The remaining commands run benchmarks by group, with aggregate reports for most groups and memory reports for collection, write-collection, and write-wide-object.

```bash
php vendor/bin/phpbench run --report=aggregate
```

```bash
php vendor/bin/phpbench run src/DeserializeBench.php --report=aggregate
```

```bash
php vendor/bin/phpbench run src/CollectionBench.php --report=memory
```

```bash
php vendor/bin/phpbench run --group=denormalize --report=aggregate
```

```bash
php vendor/bin/phpbench run --group=normalize --report=aggregate
```

```bash
php vendor/bin/phpbench run --group=deserialize --report=aggregate
```

```bash
php vendor/bin/phpbench run --group=serialize --report=aggregate
```

```bash
php vendor/bin/phpbench run --group=object-to-object --report=aggregate
```

```bash
php vendor/bin/phpbench run --group=collection --report=memory
```

```bash
php vendor/bin/phpbench run --group=write-collection --report=memory
```

```bash
php vendor/bin/phpbench run --group=write-wide-object --report=memory
```

--------------------------------

### Mapping data to an existing object

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/identifier.md

Shows how to fetch an existing object from the database and map data to it using the mapper.

```php
// We fetch existing object from database
$user = $this->entityManager->find(User::class, $id);

// We map data to existing object
$mapper->map($requestValue, $user);
```

--------------------------------

### MapFrom with array source configuration

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/attributes.md

Pass an array to the source argument to specify configuration for multiple sources. Here, 'foo' maps from 'bar' for both Entity and array.

```php
class EntityDto
{
    #[MapFrom(source: Entity::class, property: 'title')]
    #[MapFrom(source: 'array', property: 'name')]
    public string $name;
    
    #[MapFrom(source: [Entity::class, 'array'], property: 'bar')]
    public string $foo;
}
```

--------------------------------

### Override target property type with targetPropertyType in #[MapTo]

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/type.md

Use targetPropertyType to force the target type when mapping to an array. In this example, the 'number' property is converted to an 'int' instead of a 'string' when mapping to an array.

```php
class Entity
{
    #[MapTo(target: 'array', targetPropertyType: 'int')]
    public string $number;
}
```

--------------------------------

### Run verification script

Source: https://github.com/jolicode/automapper/blob/main/bench/README.md

Runs each benchmark group and prints an 'ok' / 'DIFF' report, exiting non-zero on any divergence.

```bash
php bin/verify.php
```

--------------------------------

### Implement ProviderInterface

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/provider.md

Create a custom provider class that implements ProviderInterface. The provide method receives the target type, source, and context, and must return an object or null.

```php
use AutoMapper\Provider\ProviderInterface;

class MyProvider implements ProviderInterface
{
    public function provide(string $targetType, mixed $source, array $context): object|null
    {
        return new $targetType();
    }
}
```

--------------------------------

### Quick usage: map an object to a target class

Source: https://github.com/jolicode/automapper/blob/main/docs/index.md

Shows the simplest way to use AutoMapper: create an instance and map a source object to a target class. The mapper generates a PHP class for the mapping and caches it for future use.

```php
use AutoMapper\AutoMapper;

$automapper = AutoMapper::create();

$source = new Source();
$target = $automapper->map($source, Target::class);
```

--------------------------------

### Mapping collections with mapCollection

Source: https://github.com/jolicode/automapper/blob/main/docs/index.md

Shows how to map a collection of objects using the mapCollection method, which returns a collection of mapped target objects.

```php
$sources = [$source1, $source2, $source3];
$targets = $automapper->mapCollection($sources, Target::class);
```

--------------------------------

### Configure mappings for cache warmup in automapper.yaml

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/cache-warmup.md

Specify the mappings to generate during cache:warmup. Each mapping defines a source and target class, with an optional reverse flag. Dependencies of specified mappings are also generated automatically.

```yaml
automapper:
  mapping:
    mappers:
      - source: App\Entity\User
        target: App\Api\DTO\User
    
      - source: App\Entity\User
        target: array
        reverse: true
```

--------------------------------

### Use new bundle namespace

Source: https://github.com/jolicode/automapper/blob/main/docs/upgrading/upgrading-9.0.md

Replace the old bundle namespace with the new one after removing the jolicode/automapper-bundle package.

```php
use AutoMapper\Symfony\Bundle\AutoMapperBundle;
```

--------------------------------

### Use #[MapProvider] attribute

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/provider.md

Apply the MapProvider attribute to the target class to specify which provider to use. The provider is referenced by class name.

```php
use AutoMapper\Attribute\MapProvider;

#[MapProvider(provider: MyProvider::class)]
class Entity
{
}
```

--------------------------------

### Register a mapping for a class to migrate

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/migrate.md

Configuration to register a class in the mappings section so the library's normalizer will handle it. This is the first step to migrate a class without custom normalizer logic.

```yaml
# config/packages/automapper.yaml
automapper:
    normalizer:
        enabled: true
        only_registered_mapping: true
    mappings:
        mappers:
            - { source: App\Entity\MyEntity, target: 'array' }

```

--------------------------------

### Before: PropertyTransformerSupportInterface supports() with TypesMatching

Source: https://github.com/jolicode/automapper/blob/main/docs/upgrading/upgrading-10.0.md

The old signature of the supports() method included a TypesMatching argument. This is the code before the upgrade to 10.0.

```php
class MyTransformer implements PropertyTransformerSupportInterface
{
    public function supports(TypesMatching $types, SourcePropertyMetadata $source, TargetPropertyMetadata $target, MapperMetadata $mapperMetadata): bool
    {
        // ...
    }
}
```

--------------------------------

### Map UserDto to User with nested properties

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/nested.md

Shows how to use the mapper to map a UserDto instance to a User class. The resulting User object will have an Address object with street and city set from the UserDto's streetAddress and cityAddress properties.

```php
$mapper->map(new UserDto(
    streetAddress: '123 Main St',
    cityAddress: 'Springfield',
    name: 'John Doe'
), User::class);
```

--------------------------------

### Static callback condition with MapTo

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/conditional-mapping.md

Uses a static callback method to define the condition. The callback can accept the `source` object and `context` array as arguments.

```php
class Source
{
    public bool $propertyIsValid = true;

    #[MapTo(if: [self::class, 'isPropertyValid'])]
    public $property;
    
    public static function isPropertyValid(Source $source, array $context): bool
    {
        return $source->propertyIsValid && ($context['custom_key'] ?? false) === true;
    }
}
```

--------------------------------

### Return EarlyReturn from provider

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/provider.md

To skip property mapping, return an EarlyReturn object wrapping the desired target object from the provide method.

```php
use AutoMapper\Provider\EarlyReturn;
use AutoMapper\Provider\ProviderInterface;

class MyProvider implements ProviderInterface
{
    public function provide(string $targetType, mixed $source, array $context): object|null
    {
        return new EarlyReturn(new $targetType());
    }
}
```

--------------------------------

### Map object to object with new target

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/source-and-target.md

Maps a User object to a new UserDTO instance using the map method.

```php
$source = new User();
$target = $autoMapper->map($source, UserDTO::class);
```

--------------------------------

### Define classes with nested property mapping using MapTo

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/nested.md

Defines UserDto, User, and Address classes. The UserDto uses #[MapTo(property: 'address.street')] and #[MapTo(property: 'address.city')] to map to nested properties. The User class must initialize the Address object in its constructor to avoid null reference errors.

```php
class UserDto
{
    #[MapTo(property: 'address.street')]
    public string $streetAddress;

    #[MapTo(property: 'address.city')]
    public string $cityAddress;
    
    public string $name;
}

class User
{
    public Address $address;
    public string $name;
    
    public function __construct()
    {
        $this->address = new Address();
    }
}

class Address
{
    public string $street;
    public string $city;
}
```

--------------------------------

### Use static callback as MapTo transformer

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/transformer.md

Use a static method callback as the transformer. The callback receives the source property value, the whole source object, and the context array.

```php
class Source
{
    #[MapTo(transformer: [self::class, 'transform'])]
    public string $property;

    public static function transform(string $value, Source $source, array $context): string
    {
        return strtoupper($value);
    }
}

```

--------------------------------

### Constructor arguments option for mapping

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/context.md

Use the `constructor_arguments` option to provide values for constructor parameters that are not available in the source object. The option is an array keyed by the target class, with parameter names as keys.

```php
class UserDto {
    public function __construct(private string $name, private \DateTime $createdAt) {}
}

$source = new User();
$source->name = 'Jane';

$target = $autoMapper->map($source, UserDTO::class, [
    'constructor_arguments' => [
        UserDTO::class => ['createdAt' => new \DateTime('2021-01-01')]
    ]
]);
```

--------------------------------

### Basic context usage

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/context.md

Pass a context array as the third argument to the `map` method to change mapping behavior.

```php
$source = new User();
$target = $autoMapper->map($source, UserDTO::class, ['key' => 'value']);
```

--------------------------------

### Clone object with map

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/source-and-target.md

Clones a User object by mapping to the same class. The result is a deep clone, so sub-objects are also cloned.

```php
$source = new User();
$target = $autoMapper->map($source, User::class);

assert($source !== $target);
```

--------------------------------

### MapFrom on a method

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/attributes.md

Use #[MapFrom] on a target method to map from a source property. Here, the 'setName' method receives the value from 'title'.

```php
class EntityDto
{
    private string $name;

    #[MapFrom(property: 'title')]
    public function setName($name): void
    {
        $this->name = $name;
    }
}
```

--------------------------------

### After: PropertyTransformerSupportInterface supports() without TypesMatching

Source: https://github.com/jolicode/automapper/blob/main/docs/upgrading/upgrading-10.0.md

The new signature of the supports() method removes the TypesMatching argument. Source and target types are now obtained from the metadata arguments.

```php
class MyTransformer implements PropertyTransformerSupportInterface
{
    public function supports(SourcePropertyMetadata $source, TargetPropertyMetadata $target, MapperMetadata $mapperMetadata): bool
    {
        // ...
    }
}
```

--------------------------------

### Using service() in MapTo transformer and if conditions

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/expression-language.md

Use the `service` function to call a service method in the `transformer` or `if` condition of `MapTo`. The service can be referenced by its alias or fully qualified class name.

```php
class Entity
{
    #[MapTo(transformer: "service('my_service').transform(source)")]
    public string $name;
    
    // Or without an alias
    #[MapTo(transformer: "service('App\\Service\\MyService').transform(source)")]
    public string $name;
    
    #[MapTo(if: "service('my_service').check()")]
    public int $age;
}
```

--------------------------------

### Skipping uninitialized values with skip_uninitialized_values

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/context.md

When enabled, uninitialized source properties are not mapped and the target keeps its existing value.

```php
class User
{
    public string $name;
}

$source = new User(); // do not initialize $name property
$target = new UserDTO();
$target->name = 'Jane';
$target = $autoMapper->map($source, $target, ['skip_uninitialized_values' => true]);

assert($target->name === 'Jane'); // true
```

--------------------------------

### Defining a service with AsAutoMapperExpressionService

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/expression-language.md

Mark a service with the `#[AsAutoMapperExpressionService]` attribute to make it available in the expression language. The `alias` parameter allows referencing the service by a short name.

```php
namespace App\Service;

use AutoMapper\Symfony\Attribute\AsAutoMapperExpressionService;

#[AsAutoMapperExpressionService(alias: 'my_service')
class MyService
{
    public function transform(Entity $entity): string
    {
        return 'transformed';
    }
    
    public function check(): bool
    {
        return false;
    }
}
```

--------------------------------

### Map object to existing object

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/source-and-target.md

Maps a User object to an existing UserDTO instance, updating the target with values from the source.

```php
$source = new User();
$target = new UserDTO();
$autoMapper->map($source, $target);
```

--------------------------------

### Enable json_stream extension in php.ini

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/json-streamer.md

INI configuration to enable the native json_stream extension in php.ini. The AutoMapper uses it automatically when loaded, falling back to the polyfill otherwise.

```ini
extension=json_stream
```

--------------------------------

### PHP function condition with MapTo

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/conditional-mapping.md

Uses a PHP function (e.g., `boolval`) as the condition. The function must return a boolean. If the function requires more arguments than `source` and `context`, an exception is thrown.

```php
class Source
{
    #[MapTo(if: 'boolval')]
    public string $property = '';
}
```

--------------------------------

### Array-like class with #[Mapper] attribute

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/mapper-attribute.md

Sets arrayLike to true to map the class as a keyed array shape instead of a typed object.

```php
#[Mapper(arrayLike: true)]
class Bag implements \ArrayAccess
{
    private array $values = [];

    // ...
}
```

--------------------------------

### Skipping null values with skip_null_values

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/context.md

When enabled, null source values are not mapped and the target keeps its existing value.

```php
$source = new User();
$source->name = null;
$target = new UserDTO();
$target->name = 'Jane';
$target = $autoMapper->map($source, $target, ['skip_null_values' => true]);

assert($target->name === 'Jane'); // true
```

--------------------------------

### Run debug:mapper command

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/debugging.md

Use the debug:mapper command to display mapping information for a specific mapper, e.g., from User to UserDTO. This helps understand how AutoMapper maps objects and why some properties are not mapped.

```bash
php bin/console debug:mapper User UserDTO
```

--------------------------------

### MapTo on a property

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/attributes.md

Use #[MapTo] on a source property to map it to a target property. Here, the 'title' property maps to 'name'.

```php
class Entity
{
    #[MapTo(property: 'name')]
    public string $title;
}
```

--------------------------------

### Implement PrioritizedPropertyTransformerInterface to set priority

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/transformer.md

Shows a transformer class implementing PrioritizedPropertyTransformerInterface with a getPriority method returning 10. When multiple transformers can be applied, the one with the highest priority is used.

```php
namespace App\Transformer;

class UrlTransformer implements PropertyTransformerSupportInterface, PrioritizedPropertyTransformerInterface
{
    // ...
    
    public function getPriority(): int
    {
        return 10;
    }
}
```

--------------------------------

### Dynamic callback condition with MapTo

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/conditional-mapping.md

References a method of the object declaring the attribute to define the condition. The callback can accept the `source` object and `context` array as arguments.

```php
class Source
{
    public bool $propertyIsValid = true;

    #[MapTo(if: 'isPropertyValid')]
    public $property;
    
    public function isPropertyValid(): bool
    {
        return $this->propertyIsValid;
    }
}
```

--------------------------------

### Register reverse mapping for denormalization

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/migrate.md

Configuration to add the reverse option to a mapping, enabling the denormalizer for the registered class.

```yaml
# config/packages/automapper.yaml
automapper:
    normalizer:
        enabled: true
        only_registered_mapping: true
    mappings:
        mappers:
            - { source: App\Entity\MyEntity, target: 'array', reverse: true }

```

--------------------------------

### Marking an identifier with MapFrom attribute

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/identifier.md

Shows how to manually specify the identifier property using the MapFrom attribute with identifier: true.

```php
class Address 
{
    #[MapFrom(identifier: true)]
    public string $id;
}
```

--------------------------------

### Automatically apply custom transformer with PropertyTransformerSupportInterface

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/transformer.md

Automatically apply a custom transformer by implementing PropertyTransformerSupportInterface. When the source 'id' property is an int and the target property is named 'url', this transformer is used without specifying it in MapTo or MapFrom attributes.

```php
namespace App\Transformer;

use AutoMapper\Metadata\MapperMetadata;
use AutoMapper\Metadata\SourcePropertyMetadata;
use AutoMapper\Metadata\TargetPropertyMetadata;
use AutoMapper\Transformer\PropertyTransformer\PropertyTransformerSupportInterface;

class UrlTransformer implements PropertyTransformerSupportInterface
{
    public function __construct(private UrlGeneratorInterface $urlGenerator)
    {
    }
    
    public function supports(SourcePropertyMetadata $source, TargetPropertyMetadata $target, MapperMetadata $mapperMetadata): bool
    {
        return $source->type->isIdentifiedBy(TypeIdentifier::INT) && $source->property === 'id' && $target->property === 'url';
    }
    
    public function transform(mixed $value, object|array $source, array $context): mixed
    {
        return $this->urlGenerator->generate('my_route', ['id' => $value]);
    }
}

```

--------------------------------

### mapCollection() with context

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/map-collection.md

Passing a context array to mapCollection() to customize the mapping process. The context is applied to each individual object mapping operation.

```php
$context = ['groups' => ['read']];
$targets = $automapper->mapCollection($sources, Target::class, $context);
```

--------------------------------

### Specify multiple sources for #[Mapper] attribute

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/mapper-attribute.md

Uses an array of source classes to override mapping for multiple sources with a single attribute.

```php
#[Mapper(source: [EntityDto::class, AnotherEntityDto::class], constructorStrategy: ConstructorStrategy::NEVER)]
```

--------------------------------

### Handling circular references with a callback

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/context.md

Provide a callback to handle circular references; the callback receives the source and context and returns the value to use.

```php
$source = new User();
$source->friend = $source;
$target = $autoMapper->map($source, UserDTO::class, [
    'circular_reference_handler' => function ($source, $context) {
        return null;
    }
]);
```

--------------------------------

### Set DateTime format via property attribute

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/date-time.md

Sets a DateTime format on a #[MapTo] attribute (same for #[MapFrom]). This overrides any #[Mapper] attribute or bundle configuration.

```php
class Source
{
    #[MapTo(dateTimeFormat: \DateTimeInterface::ATOM)]
    public \DateTimeImmutable $dateTime;
}
```

--------------------------------

### Using env() in MapTo if condition

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/expression-language.md

Use the `env` function to access environment variables in the `if` condition of the `MapTo` attribute. The mapping is applied only when the environment variable `FEATURE_ENABLED` is truthy.

```php
class Entity
{
    #[MapTo(target: 'array', if: "env('FEATURE_ENABLED')")]
    public string $name;
}
```

--------------------------------

### Set DateTime format via mapper attribute

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/date-time.md

Sets a DateTime format on a #[Mapper] attribute. This overrides any bundle configuration.

```php
#[Mapper(dateTimeFormat: \DateTimeInterface::ATOM)]
class Source
{
    public \DateTimeImmutable $dateTime;
}
```

--------------------------------

### Register provider with AutoMapper::create

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/provider.md

Register the custom provider when creating the AutoMapper object by passing it in the providers array.

```php
use AutoMapper\AutoMapper;

$autoMapper = AutoMapper::create(providers: [new MyProvider()]);
```

--------------------------------

### mapCollection()

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/map-collection.md

Maps a collection of objects from a source type to a target class. Supports any iterable and accepts an optional context array that is applied to each individual mapping.

```APIDOC
## mapCollection()

### Description
Maps a collection of objects from a source type to a target class. Supports any iterable and accepts an optional context array that is applied to each individual mapping.

### Method
mapCollection

### Signature
```php
$automapper->mapCollection(iterable $sources, string $targetClass, array $context = []): array
```

### Parameters
- **$sources** (iterable) - Required - The collection of source objects to map.
- **$targetClass** (string) - Required - The fully qualified class name of the target type.
- **$context** (array) - Optional - An associative array of context options to customize the mapping. This context is applied to each individual object mapping operation.

### Return Value
- **array** - An array of mapped objects, each an instance of the target class.

### Example
```php
use AutoMapper\AutoMapper;

$automapper = AutoMapper::create();

$sources = [
    new Source('value1'),
    new Source('value2'),
    new Source('value3'),
];

$targets = $automapper->mapCollection($sources, Target::class);
```

### Context Example
```php
$context = ['groups' => ['read']];
$targets = $automapper->mapCollection($sources, Target::class, $context);
```
```

--------------------------------

### Multiple MapFrom attributes with source

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/attributes.md

Use multiple #[MapFrom] attributes on the same property to handle different sources. Here, 'name' maps from 'title' for Entity and from 'name' for array.

```php
class EntityDto
{
    #[MapFrom(source: Entity::class, property: 'title')]
    #[MapFrom(source: 'array', property: 'name')]
    public string $name;
}
```

--------------------------------

### map method with context

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/context.md

The map method accepts a context array as the third argument to customize mapping behavior.

```APIDOC
## map(source, target, context)

### Description
Maps a source object to a target object or class, with optional context options to control the mapping process.

### Method
map

### Parameters
- **source** (object) - Required - The source object to map from.
- **target** (string|object) - Required - The target class name or object to map to.
- **context** (array) - Optional - An associative array of options to customize mapping behavior.

### Context Options
- **groups** (array) - Optional - Define a subset of properties to map. Only properties flagged with the given groups on both source and target will be mapped.
- **allowed_attributes** (array) - Optional - Define a subset of properties to map. Only properties listed will be mapped. Can be nested to allow specific attributes of nested objects.
- **ignored_attributes** (array) - Optional - Define properties to exclude from mapping.
- **circular_reference_limit** (int) - Optional - Set to 0 to break circular references and throw a CircularReferenceException.
- **circular_reference_handler** (callable) - Optional - A callback to handle circular references. Receives the source object and context.
- **skip_null_values** (bool) - Optional - If true, null values in the source will not overwrite existing target values.
- **skip_uninitialized_values** (bool) - Optional - If true, uninitialized properties in the source will not overwrite existing target values.
- **date_time_format** (string) - Optional - The format to use when mapping DateTimeInterface objects to strings. Defaults to DateTimeInterface::RFC3339.

### Example
```php
$source = new User();
$target = $autoMapper->map($source, UserDTO::class, ['key' => 'value']);
```
```

--------------------------------

### Configure cache directory in AutoMapper::create()

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/cache.md

Use the `cacheDirectory` option to store generated Mappers in a specified directory, allowing reuse across requests and CLI commands. The Mapper will be regenerated if the source or target class changes. Note that some changes, such as altering a dependency, may not be detected and may require manual cache clearing.

```php
use AutoMapper\AutoMapper;

$autoMapper = AutoMapper::create(cacheDirectory: '/path/to/cache');
```

--------------------------------

### Map to accessor parameter with MapToContext attribute

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/context.md

Use the `map_to_accessor_parameter` option to pass parameters to a method that fetches a property value. The method parameter must be linked to the context using the `MapToContext` attribute.

```php
class User {
    public function __construct(private string $name) {}
    
    public function getName(#[MapToContext('suffix')] string $suffix): string {
        return $this->name . $suffix;
    }
}

$source = new User(name: 'Jane');
$target = $autoMapper->map($source, UserDTO::class, [
    'map_to_accessor_parameter' => ['suffix' => ' Doe']
]);
```

--------------------------------

### Denormalize array to object

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/source-and-target.md

Converts an array to a User object using the map method.

```php
$source = ['id' => 1];
$target = $autoMapper->map($source, User::class);
```

--------------------------------

### Use #[DiscriminatorMap] attribute for polymorphic mapping

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/serializer.md

Define a discriminator map to handle polymorphic mapping, using a type property to map to concrete classes.

```php
use Symfony\Component\Serializer\Annotation\DiscriminatorMap;

#[DiscriminatorMap(typeProperty: 'type', mapping: [
    'dog' => Dog::class,
    'cat' => Cat::class,
])]
abstract class Pet
{
    public $name;
}
```

--------------------------------

### mapCollection() with iterable

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/map-collection.md

Shows that mapCollection() accepts any iterable and returns an array of the target class objects.

```php
$targetsArray = $automapper->mapCollection($sourcesArray, Target::class);
```

--------------------------------

### Use #[Ignore] with #[MapTo] ignore: false

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/ignoring-properties.md

Combines the Symfony Serializer's `#[Ignore]` attribute with `#[MapTo]` having `ignore: false` to map the property to `SourceDTO` while ignoring it during serialization.

```php
use Symfony\Component\Serializer\Attribute\Ignore;

class Source
{
    #[Ignore]
    #[MapTo(target: SourceDTO::class, ignore: false)]
    public $ignoredProperty;
}
```

--------------------------------

### Disable auto-registration with #[MapProvider(provider: false)]

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/provider.md

Set the provider to false in the MapProvider attribute to disable automatic registration of Doctrine and Api Platform providers for a specific mapping.

```php
use AutoMapper\Attribute\MapProvider;

#[MapProvider(provider: false)]
class Entity
{
}
```

--------------------------------

### Check if json_stream extension is loaded

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/json-streamer.md

Shell command to verify whether the native json_stream extension is loaded. Returns true if loaded, false otherwise.

```shell
php -r "var_dump(extension_loaded('json_stream'));"
```

--------------------------------

### Implement PropertyTransformerComputeInterface to compute extra data

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/transformer.md

Shows a transformer class implementing PropertyTransformerComputeInterface. The compute method returns extra data that is passed as a static value to the transform method. Note: the compute method is only called when the transformer is guessed via the supports method, not when specified manually in #[MapTo] or #[MapFrom].

```php
namespace App\Transformer;

use AutoMapper\Metadata\MapperMetadata;
use AutoMapper\Metadata\SourcePropertyMetadata;
use AutoMapper\Metadata\TargetPropertyMetadata;
use AutoMapper\Transformer\PropertyTransformer\PropertyTransformerSupportInterface;

class UrlTransformer implements PropertyTransformerComputeInterface
{
    public function __construct()
    {
    }
    
    public function supports(SourcePropertyMetadata $source, TargetPropertyMetadata $target, MapperMetadata $mapperMetadata): bool
    {
        return $source->type->isIdentifiedBy(TypeIdentifier::INT) && $source->property === 'id' && $target->property === 'url';
    }

    public function compute(SourcePropertyMetadata $source, TargetPropertyMetadata $target, MapperMetadata $mapperMetadata): mixed
    {
        // Compute extra data here
        return 'some computed data';
    }
    
    public function transform(mixed $value, object|array $source, array $context, mixed $computed = null): mixed
    {
        return $computed . $value;
    }
}
```

--------------------------------

### Use AutoMapperNormalizer with Symfony Serializer

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/serializer.md

Create a Serializer instance with the AutoMapperNormalizer to leverage AutoMapper's performance while staying close to ObjectNormalizer behavior.

```php
use AutoMapper\Normalizer\AutoMapperNormalizer;
use Symfony\Component\Serializer\Serializer;

$autoMapper = AutoMapper::create();
$serializer = new Serializer([new AutoMapperNormalizer($autoMapper)]);
```

--------------------------------

### Specify source for #[Mapper] attribute

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/mapper-attribute.md

Limits the attribute to a specific source class.

```php
#[Mapper(source: EntityDto::class, constructorStrategy: ConstructorStrategy::NEVER)]
```

--------------------------------

### Basic mapCollection() usage

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/map-collection.md

Basic usage of mapCollection() to map an array of Source objects to Target instances. The method returns an array where each element is mapped to a new instance of the target class.

```php
use AutoMapper\AutoMapper;

$automapper = AutoMapper::create();

$sources = [
    new Source('value1'),
    new Source('value2'),
    new Source('value3'),
];

$targets = $automapper->mapCollection($sources, Target::class);
```

--------------------------------

### Enable only_registered_mapping and define a mapping

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/json-streamer.md

YAML configuration to opt in explicitly for AutoMapper handling only registered types. The mapping with 'reverse: true' enables both reading (json to User) and writing (User to json).

```yaml
automapper:
  json_streamer:
    enabled: true
    only_registered_mapping: true
  mapping:
    mappers:
      # reading: json -> User, writing: User -> json
      - { source: 'App\Entity\User', target: 'json', reverse: true }
```

--------------------------------

### Normalize object to stdClass

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/source-and-target.md

Converts a User object to a stdClass instance using the map method with \stdClass::class as target.

```php
$source = new User();
$target = $autoMapper->map($source, \stdClass::class);
```

--------------------------------

### Register AutoMapperBundle in config/bundles.php

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/installation.md

Adds the AutoMapperBundle to the Symfony application's bundle list, enabling the bundle for all environments.

```php
return [
    // ...
    AutoMapper\Symfony\Bundle\AutoMapperBundle::class => ['all' => true],
];
```

--------------------------------

### Create and register custom PropertyTransformerInterface

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/transformer.md

Create a custom transformer by implementing PropertyTransformerInterface RD. The first block shows the transformer class. The second block registers it with the AutoMapper instance. The third block uses it in the MapTo attribute. Custom transformers are experimental and may change. When using the Symfony Bundle, register with the 'automapper.property_transformer' tag or rely on autoconfiguration; the transformer argument then uses the service id.

```php
namespace App\Transformer;

use AutoMapper\Transformer\PropertyTransformer\PropertyTransformerInterface;

class UrlTransformer implements PropertyTransformerInterface
{
    public function __construct(private UrlGeneratorInterface $urlGenerator)
    {
    }
    
    public function transform(mixed $value, object|array $source, array $context): mixed
    {
        return $this->urlGenerator->generate('my_route', ['id' => $value]);
    }
}

```

```php
use AutoMapper\AutoMapper;

$autoMapper = AutoMapper::create(propertyTransformers: [new UrlTransformer($urlGenerator)]);

```

```php
use App\Transformer\UrlTransformer;

class Source
{
    #[MapTo(property: 'url', transformer: UrlTransformer::class)]
    public int $id;
}

```

--------------------------------

### Normalize object to array

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/source-and-target.md

Converts a User object to an array with scalar values using the map method with 'array' as target.

```php
$source = new User();
$target = $autoMapper->map($source, 'array');
```

--------------------------------

### Enable JSON streamer integration in framework and automapper config

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/json-streamer.md

YAML configuration to enable both the Symfony JsonStreamer component and the AutoMapper integration. The AutoMapper services decorate the Symfony ones, so unhandled types fall back to the Symfony implementation.

```yaml
# config/packages/framework.yaml
framework:
  json_streamer:
    enabled: true

# config/packages/automapper.yaml
automapper:
  json_streamer:
    enabled: true
```

--------------------------------

### Using groups to filter mapped properties

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/context.md

Only properties flagged with the specified group(s) will be mapped. Groups are checked on both source and target objects.

```php
$source = new User();
$target = $autoMapper->map($source, UserDTO::class, ['groups' => ['read']]);
```

--------------------------------

### Basic #[Mapper] attribute with constructorStrategy

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/mapper-attribute.md

Configures the mapper to never use the constructor for the Entity class.

```php
#[Mapper(constructorStrategy: ConstructorStrategy::NEVER)]
class Entity
{
    public string $foo;
}
```

--------------------------------

### Configure inheritance mapping with Discriminator

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/inheritance.md

Use this attribute to map inherited source classes to their corresponding target DTOs. The mapping keys are target classes and values are source classes. AutoMapper determines the correct class to instantiate based on the instance of the property.

```php
#[Mapper(discriminator: new Discriminator(
    mapping: [
        DogDto::class => Dog::class,
        CatDto::class => Cat::class,
    ]
))]
abstract class Pet
{
    /** @var string */
    public $name;

    /** @var PetOwner */
    public $owner;
}
```

--------------------------------

### Define groups with MapTo attribute

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/groups.md

Use the `#[MapTo]` attribute with a `groups` argument to specify that the property is mapped only when the context contains at least one of the listed groups.

```php
class Source
{
    #[MapTo(target: 'array', groups: ['group1', 'group2'])]
    public $groupedProperty;
}
```

--------------------------------

### Ignore property with #[MapTo] attribute

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/ignoring-properties.md

Sets the `ignore` argument to `true` to skip mapping the property to the `SourceDTO` class, and to `false` for mapping to an array.

```php
class Source
{
    #[MapTo(target: SourceDTO::class, ignore: true)]
    #[MapTo(target: 'array', ignore: false)]
    public $ignoredProperty;
}
```

--------------------------------

### Use #[Groups] attribute to define mapping groups

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/serializer.md

Define groups on a property to control which properties are mapped. When both target and source objects have groups, the property is mapped only if the context contains at least one group from both objects.

```php
use Symfony\Component\Serializer\Attribute\Groups;

class Source
{
    #[Groups(['group1', 'group2'])]
    public $groupedProperty;
}
```

--------------------------------

### Enable serializer attributes in automapper.yaml

Source: https://github.com/jolicode/automapper/blob/main/docs/bundle/migrate.md

Configuration to enable the serializer_attributes option so that serializer attributes on entities are used by the library.

```yaml
# config/packages/automapper.yaml
automapper:
    normalizer:
        enabled: true
        only_registered_mapping: true
    serializer: true
    mappings:
        mappers:
            - { source: App\Entity\MyEntity, target: 'array' }

```

--------------------------------

### Expression Language condition with MapTo

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/conditional-mapping.md

Uses Symfony Expression Language to define a condition. The `source` object and `context` array are available. In standalone mode, no additional functions are provided.

```php
class Source
{
    public bool $propertyIsValid = true;

    #[MapTo(if: 'source.propertyIsValid and (context["custom_key"] ?? false) == true')]
    public $property;
}
```

--------------------------------

### Set DateTime format via AutoMapper context

Source: https://github.com/jolicode/automapper/blob/main/docs/mapping/date-time.md

Forces a DateTime format everywhere by passing MapperContext::DATETIME_FORMAT to the map method. This overrides any attribute or bundle configuration.

```php
use AutoMapper\MapperContext;

$source = new Source();
$target = $autoMapper->map($source, 'array', [MapperContext::DATETIME_FORMAT => \DateTimeInterface::ATOM]);
```

--------------------------------

### Using ignored_attributes to exclude properties

Source: https://github.com/jolicode/automapper/blob/main/docs/getting-started/context.md

All properties except the specified ones will be mapped.

```php
$source = new User();
$target = $autoMapper->map($source, UserDTO::class, [
    'ignored_attributes' => ['id']
]);
```
Tokens:
Raw