feature symfony#51741 [ObjectMapper] Object to Object mapper component (soyuka)

This PR was squashed before being merged into the 7.3 branch.

Discussion
----------

[ObjectMapper] Object to Object mapper component

| Q             | A
| ------------- | ---
| Branch?       | 7.3
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| License       | MIT
| Doc PR        | TBD this description will be used as docs

## Why ?

In the train back from [API Platform Con](https://api-platform.com/con/2023/) and after watching `@weaverryan` conference about API Platform's feature that helps [separating Doctrine Entities from POPOs](https://symfonycasts.com/screencast/api-platform-extending/state-options), we had the feeling that such a component is definitely missing from the Symfony ecosystem. Current implementations (automapper-plus, janephp/automapper) are good but feel to complicated when you want something accessible (DX and complexity). Here we're not trying to have exceptional performance, we just want an accessible API with few mandatory features. Basically those are:

- map properties from a class/object to another class/object (`Map(target: A::class)`)
- configure the property name each property is mapped to (`Map(target: 'prop')`)
- change the value during transformation (`Map(transform: 'ucfirst')`)
- control whether the value should be mapped or not (`Map(if: 'boolval')`)
- reuse objects if possible (works better with doctrine UOW)

Other implementation details:
- if a property exists in B, it'll "automatically" be mapped (doesn't handle type errors, should we ?)
- if a property doesn't exists in B it'll "automatically" **not** be mapped

The rest is not "auto".

## Mapper Component

The Mapper component allows you to map an object to another object,
facilitating the mapping using attributes.

### Usage

```php
use Symfony\Component\ObjectMapper\ObjectMapper;
use Symfony\Component\ObjectMapper\Attributes\Map;

// This maps class `A` to class `B`.
#[Map(B::class)]
class A
{
    // This maps A::foo to B::bar.
    #[Map(target: 'bar')]
    public string $foo;

    // This calls ucfirst on A::transform
    #[Map(transform: 'ucfirst')]
    public string $name;

    // This doesn't map A::bar if it's value is falsy.
    #[Map(if: 'boolval')]
    public bool $bar = false;
}

$mapper = new ObjectMapper();
$mapper->map(new A);
```
The `Map` attribute has the following signature:

```php
#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
final class Map
{
    /**
     *
     * `@param` null|string|class-string                                  $source     The property or the class to map to
     * `@param` null|string|class-string                                  $target     The property or the class to map from
     * `@param` string|callable(mixed $value, object $object): bool       $if         A Symfony service name or a callable that instructs whether to map
     * `@param` CallableType|CallableType[]                               $transform  A Symfony service name or a callable that transform the value during mapping
     */
    public function __construct(
        public readonly ?string $source = null,
        public readonly ?string $target = null,
        public readonly mixed $if = null,
        public readonly mixed $transform = null
    ){
    }
}
```

`if` and `transform` are callable or Symfony services, not that we need to introduce an interface for services to implement, this will follow if we want to introduce the component inside the Framework Bundle.

The mapper also takes a `$source` argument if one needs to update an object instead of creating a new one:

```php
$b = new B;
$mapper = new ObjectMapper();
$mapper->map(new A, $b);
```

## TODO

- [x] AutoMapper or Automapper or something else? `Mapper` component with an `AutoMapper` implementation.
- [x] max depth? Supports recursivity, `maxDepth` is for serializers.

Commits
-------

3f99b03 [ObjectMapper] Object to Object mapper component

Author: fabpot

composer.json

@@ -91,6 +91,7 @@
         "symfony/mime": "self.version",
         "symfony/monolog-bridge": "self.version",
         "symfony/notifier": "self.version",
+        "symfony/object-mapper": "self.version",
         "symfony/options-resolver": "self.version",
         "symfony/password-hasher": "self.version",
         "symfony/process": "self.version",

src/Symfony/Component/ObjectMapper/.gitattributes

@@ -0,0 +1,3 @@
+/Tests export-ignore
+/phpunit.xml.dist export-ignore
+/.git* export-ignore

src/Symfony/Component/ObjectMapper/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+name: Check subtree split
+
+on:
+  pull_request_target:
+
+jobs:
+  close-pull-request:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Close pull request
+      uses: actions/github-script@v6
+      with:
+        script: |
+          if (context.repo.owner === "symfony") {
+            github.rest.issues.createComment({
+              owner: "symfony",
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: `
+          Thanks for your Pull Request! We love contributions.
+
+          However, you should instead open your PR on the main repository:
+          https://github.com/symfony/symfony
+
+          This repository is what we call a "subtree split": a read-only subset of that main repository.
+          We're looking forward to your PR there!
+          `
+            });
+
+            github.rest.pulls.update({
+              owner: "symfony",
+              repo: context.repo.repo,
+              pull_number: context.issue.number,
+              state: "closed"
+            });
+          }

src/Symfony/Component/ObjectMapper/.github/workflows/check-subtree-split.yml

@@ -0,0 +1,3 @@
+vendor/
+composer.lock
+phpunit.xml

src/Symfony/Component/ObjectMapper/.github/workflows/close-pull-request.yml

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\ObjectMapper\Attribute;
+
+/**
+ * Configures a class or a property to map to.
+ *
+ * @experimental
+ *
+ * @author Antoine Bluchet <[email protected]>
+ */
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_PROPERTY | \Attribute::IS_REPEATABLE)]
+readonly class Map
+{
+    /**
+     * @param string|class-string|null                                                                              $source    The property or the class to map from
+     * @param string|class-string|null                                                                              $target    The property or the class to map to
+     * @param string|bool|callable(mixed, object): bool|null                                         $if        A boolean, a service id or a callable that instructs whether to map
+     * @param (string|callable(mixed, object): mixed)|(string|callable(mixed, object): mixed)[]|null $transform A service id or a callable that transforms the value during mapping
+     */
+    public function __construct(
+        public ?string $target = null,
+        public ?string $source = null,
+        public mixed $if = null,
+        public mixed $transform = null,
+    ) {
+    }
+}

src/Symfony/Component/ObjectMapper/.gitignore

@@ -0,0 +1,7 @@
+CHANGELOG
+=========
+
+7.3
+---
+
+ * Add the component as experimental

src/Symfony/Component/ObjectMapper/Attribute/Map.php

@@ -0,0 +1,30 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\ObjectMapper;
+
+/**
+ * Service used by "Map::if".
+ *
+ * @template T of object
+ *
+ * @experimental
+ *
+ * {@see Symfony\Component\ObjectMapper\Attribute\Map}
+ */
+interface ConditionCallableInterface
+{
+    /**
+     * @param mixed $value  The value being mapped
+     * @param T     $object The object we're working on
+     */
+    public function __invoke(mixed $value, object $object): bool;
+}

src/Symfony/Component/ObjectMapper/CHANGELOG.md

@@ -0,0 +1,21 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\ObjectMapper\Exception;
+
+/**
+ * @experimental
+ *
+ * @author Antoine Bluchet <[email protected]>
+ */
+interface ExceptionInterface extends \Throwable
+{
+}