chore(docs): update docs with recent changes (#291)

Author: joelwurtz

docs/_nav.md

@@ -5,6 +5,7 @@
     - [Configuration](getting-started/configuration.md)
     - [Cache](getting-started/cache.md)
 - [Mapping](mapping/index.md)
+    - [Mapper attribute](mapping/mapper-attribute.md)
     - [MapTo and MapFrom attributes](mapping/attributes.md)
     - [Symfony Serializer](mapping/serializer.md)
     - [Mapping Collections](mapping/map-collection.md)
@@ -14,6 +15,7 @@
     - [Transformer](mapping/transformer.md)
     - [Provider](mapping/provider.md)
     - [Mapping inheritance](mapping/inheritance.md)
+    - [Identifier: mapping existing objects](mapping/identifier.md)
     - [DateTime format](mapping/date-time.md)
 - [Symfony Bundle](bundle/index.md)
     - [Installation](bundle/installation.md)

docs/bundle/configuration.md

@@ -79,6 +79,10 @@ indicate if we use the attribute of the symfony/serializer during the mapping, t
 `#[MaxDepth]`, `#[Ignore]` and `#[DiscriminatorMap]` attributes;
 * `api_platform` (default: `false`): A boolean which indicate if we use services from the api-platform/core package and
 inject extra data (json ld) in the mappers when we map a Resource class to or from an array.
+* `doctrine` (default: `false`): A boolean which indicate if we want to use service from doctrine to extract more 
+    information about the classes, and use doctrine to fetch existing objects. It will use by default the `doctrine.orm.entity_manager`
+    service if present, will then try to use the `doctrine_mongodb.odm.document_manager` service, or throw an exception if none of them
+    are present. You can specify your own manager by overriding the `automapper.doctrine.object_manager` service.
 * `name_converter` (default: `null`): A service id which implement the `AdvancedNameConverterInterface` or 
   `NameConverterInterface` (starting from 7.2) from the symfony/serializer, this name converter will be used when 
    mapping from an array to an object and vice versa;

docs/getting-started/configuration.md

@@ -16,6 +16,10 @@ $configuration = new Configuration(
     autoRegister: true,
     mapPrivateProperties: true,
     allowReadonlyTargetToPopulate: false,
+    strictTypes: false,
+    reloadStrategy: \AutoMapper\Loader\FileReloadStrategy::ON_CHANGE,
+    allowExtraProperties: false,
+    extractTypesFromGetter: false,
 );
 $autoMapper = AutoMapper::create(configuration: $configuration);
 ```
@@ -58,7 +62,32 @@ Setting this to false will make the `AutoMapper` throw an exception if the mappe
 This can be useful if you want to pre generate all the mappers and have tests to ensure that all the mappers are
 generated.
 
+* `mapPrivateProperties` (default: `true`)
+
+When set to true, the generated mappers will map private and protected properties.
+
+* `strictTypes` (default: `false`)
+
+When set to true, the generated mappers will add `declare(strict_types=1);` at the top of the generated files.
+
+* `reloadStrategy` (default: `FileReloadStrategy::ON_CHANGE`)
+
+Allow specifying which strategy to use to reload the generated mappers. It can be one of the following:
+
+  * `FileReloadStrategy::NEVER`: never reload the mapper, even if the source code changes. This is useful in production
+    environments where you are sure that the source code will not change and avoid useless checks.
+  * `FileReloadStrategy::ON_CHANGE`: reload the mapper only if the source code changes. This is a good compromise between
+    performance and development convenience.
+  * `FileReloadStrategy::ALWAYS`: reload the mapper each time it is needed. This is useful when debugging automapper itself, but
+     it is not recommended for most cases as it will slow down the performance.
+
 * `allowExtraProperties` (default: `false`)
 
 Settings this to true will allow the mapper to map extra properties from the source object to the target object when
 the source or the target implements the `ArrayAccess` interface.
+
+* `extractTypesFromGetter` (default: `false`)
+
+When set to true, the generated mappers will used the return type of the getters to determine the type of the property
+even when writing to the property. This can be useful with covariance when the getter return a more specific type than the
+setter.

docs/mapping/identifier.md

@@ -0,0 +1,54 @@
+# Identifier : Mapping existing objects
+
+With AutoMapper you can can map data to an existing object. 
+
+```php
+// We fetch existing object from database
+$user = $this->entityManager->find(User::class, $id);
+
+// We map data to existing object
+$mapper->map($requestValue, $user);
+```
+
+This works fine for most cases, but you may have nested objects in your source and destination objects.
+
+As an example, let's say your `User` object has multiple `Address` object.
+
+```php
+class User 
+{
+    public string $name;
+    /** @var Address[] */
+    public array $address;
+}
+
+class Address 
+{
+    public string $id;
+    public string $street;
+    public string $city;
+}
+```
+
+When mapping data to an existing `User` object, you don't want to instantiate new `Address` objects as it may
+create duplicates in your database or even worse fail with an exception because it's already existing.
+
+For that purpose, AutoMapper support the concept of Identifier which allow to reuse existing objects in a collection base
+on their identifiers.
+
+When AutoMapper is configured to be used with an ORM like Doctrine, it will automatically use the metadata to find the identifier of your objects.
+
+In other cases, you can manually tell AutoMapper which property to use as identifier.
+
+```php
+class Address 
+{
+    #[MapFrom(identifier: true)]
+    public string $id;
+}
+```
+
+When mapping a collection of `Address` objects, AutoMapper will now look for existing objects in the destination collection and use
+them if identifiers match.
+
+Otherwise, it will create a new object and add it to the collection.

docs/mapping/index.md

@@ -3,12 +3,15 @@
 Despite doing its best to map objects automatically, AutoMapper provides a lot of ways to customize the mapping between
 a `source` and a `target`.
 
+- [Mapper attribute](mapper-attribute.md)
 - [MapTo and MapFrom attributes](attributes.md)
 - [Symfony Serializer attributes](serializer.md)
+- [Mapping a collection](map-collection.md)
 - [Ignoring properties](ignoring-properties.md)
 - [Conditional mapping](conditional-mapping.md)
 - [Groups](groups.md)
 - [Transformer](transformer.md)
 - [Provider](provider.md)
 - [Mapping inheritance](inheritance.md)
+- [Identifier: mapping existing objects](identifier.md)
 - [DateTime format](date-time.md)

docs/mapping/mapper-attribute.md

@@ -20,17 +20,21 @@ You can also limit the scope of the `#[Mapper]` attribute to a specific source o
 #[Mapper(source: EntityDto::class, constructorStrategy: ConstructorStrategy::NEVER)]
 ```
 
-## DateTime format
-
-You can override DateTime format for a whole class by using `#[Mapper]` attribute:
+The `source` or `target` parameters can also be an array of classes, to override the mapping for multiple sources or targets
+with a single attribute.
 
 ```php
-#[Mapper(dateTimeFormat: \DateTimeInterface::ATOM)]
+#[Mapper(source: [EntityDto::class, AnotherEntityDto::class], constructorStrategy: ConstructorStrategy::NEVER)]
 ```
 
-This way, all your class properties that are DateTime will be transformed to string with the corresponding format.
-For more details about how each DateTime format configuration works together please read the dedicated page:
-[DateTime format](./date-time.md).
+## Configuration
+
+The `#[Mapper]` attribute supports most of the configuration parameters specified in the [global configuration](../getting-started/configuration.md).
+It will override the global configuration for the specified mapping.
+
+## Register
+
+This attribute may also be used when registering mappers manually when using the Symfony bundle.
 
 ## Priority
 

docs/mapping/provider.md

@@ -74,3 +74,39 @@ class MyProvider implements ProviderInterface
     }
 }
 ```
+
+## Third party providers
+
+We also provide some third party providers that allow you to use popular libraries to instantiate the `target` object : 
+
+### Doctrine 
+
+Automatically fetch the target from the database if it's an entity.
+
+This provider is automatically registered when : 
+
+ * an `Doctrine\Persistence\ObjectManager` is given when creating the `AutoMapper` object or is configured in the Symfony Bundle.
+ * The `target` class is managed by this `ObjectManager`.
+
+### Api Platform
+
+Use the Api Platform Provider to fetch the target object. It also converts IRIs to objects.
+
+This provider is automatically registered when : 
+
+ * The Api Platform library is installed and `api_platform` is enabled in the Symfony Bundle Configuration.
+ * The `target` class is a resource managed by Api Platform.
+
+### Disable auto registration
+
+If you want to disable the automatic registration of the Doctrine and Api Platform providers on a specific Mapping,
+you can use the `#[MapProvider]` attribute with `false`.
+
+```php
+use AutoMapper\Attribute\MapProvider;
+
+#[MapProvider(provider: false)]
+class Entity
+{
+}
+```

docs/mapping/serializer.md

@@ -68,6 +68,18 @@ use Symfony\Component\Serializer\NameConverter\CamelCaseToSnakeCaseNameConverter
 $autoMapper = AutoMapper::create(nameConverter: new CamelCaseToSnakeCaseNameConverter());
 ```
 
+It also supports the `Symfony\Component\Serializer\Attribute\SerializedName` attribute.
+
+```php
+use Symfony\Component\Serializer\Attribute\SerializedName;
+
+class Source
+{
+    #[SerializedName('nested')]
+    public $nestedProperty;
+}
+```
+
 [More information on the Name converters](https://symfony.com/doc/current/components/serializer.html#converting-property-names-when-serializing-and-deserializing)
 
 ### Normalizer Bridge