Skip to content

Commit

Permalink
chore(doc): update doc with new configuration / bundle namespace
Browse files Browse the repository at this point in the history
  • Loading branch information
joelwurtz committed Mar 17, 2024
1 parent 5ff5ab9 commit cfc3e33
Show file tree
Hide file tree
Showing 3 changed files with 30 additions and 45 deletions.
64 changes: 19 additions & 45 deletions docs/symfony.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,72 +6,46 @@ To make Symfony's users life easier, we made a bundle that will make all Depende

### Installation 📦

```shell
composer require jolicode/automapper-bundle
```
The bundle is already shipped with the main package, so you don't have to install it manually.

### Configuration 🔧

To use it, you just have to add the main bundle class to your `config/bundles.php` file.
To use it, you have to add the main bundle class to your `config/bundles.php` file.
```php
return [
// ...
AutoMapper\Bundle\AutoMapperBundle::class => ['all' => true],
AutoMapper\Symfony\Bundle\AutoMapperBundle::class => ['all' => true],
];
```

Then configure the bundle to your needs, for example:
```yaml
automapper:
autoregister: true
normalizer: true
serializer: false
mappings:
- source: AutoMapper\Bundle\Tests\Fixtures\User
target: AutoMapper\Bundle\Tests\Fixtures\UserDTO
pass: DummyApp\UserConfigurationPass
allow_readonly_target_to_populate: false
```
Possible properties:
- `normalizer` (default: `false`): A boolean which indicate if we inject the AutoMapperNormalizer;
- `cache_dir` (default: `%kernel.cache_dir%/automapper`): This setting allows you to customize the output directory
#### Reference
* `normalizer` (default: `false`): A boolean which indicate if we inject the AutoMapperNormalizer;
* `serializer` (default: `true` if the symfony/serializer is available, false otherwise): A boolean which indicate
if we use the attribute of the symfony/serializer during the mapping, this only apply to the `#[Groups]`, `#[MaxDepth]`,
`#[Ignore]` and `#[DiscriminatorMap]` attributes;
* `name_converter` (default: `null`): A service id which implement the `AdvancedNameConverterInterface` from the symfony/serializer,
this name converter will be used when mapping from an array to an object and vice versa;
* `cache_dir` (default: `%kernel.cache_dir%/automapper`): This setting allows you to customize the output directory
for generated mappers;
- `mappings`: This option allows you to customize Mapper metadata, you have to specify `source` & `target` data types
and related configuration using `pass` field. This configuration should implements `AutoMapper\Bundle\Configuration\MapperConfigurationInterface`.
- `allow_readonly_target_to_populate` (default: `false`): Will throw an exception if you use a readonly class as target
* `mappings`: This option allows you to set a list of Mapper which will be generated during the cache warmup, you have
to specify `source` & `target` data types.
* `allow_readonly_target_to_populate` (default: `false`): Will throw an exception if you use a readonly class as target
to populate if set to `false`.

### MapperConfigurationInterface

You can add some metadata to customize a transformation. Here is an example:

```php
class UserMapperConfiguration implements MapperConfigurationInterface
{
public function getSource(): string
{
return User::class;
}
public function getTarget(): string
{
return UserDTO::class;
}
public function process(MapperGeneratorMetadataInterface $metadata): void
{
$metadata->forMember('yearOfBirth', function (User $user) {
return ((int) date('Y')) - ((int) $user->age);
return ((int) date('Y')) - ((int) $user->age);
});
}
}
```

Here you have to inherit the `MapperConfigurationInterface` interface, that ways it will autoconfigure your
transformation for a given source & target. And in the `process` method you will add or overwrite fields to map.
The fields you give onto the `forMember` method are target fields and the callback will always give you the source
object.

### Normalizer Bridge 🌁

A Normalizer Bridge is available, aiming to be 100% feature compatible with the ObjectNormalizer of the
``symfony/serializer`` component. The goal of this bridge **is not to replace the ObjectNormalizer** but rather
providing a very fast alternative.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
use Symfony\Component\DependencyInjection\Reference;
use Symfony\Component\HttpKernel\DependencyInjection\Extension;
use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
use Symfony\Component\Serializer\SerializerInterface;
use Symfony\Component\Uid\AbstractUid;

class AutoMapperExtension extends Extension
Expand Down Expand Up @@ -55,6 +56,14 @@ public function load(array $configs, ContainerBuilder $container): void
->addTag('automapper.transformer_factory', ['priority' => '-1004']);
}

if ($config['serializer']) {
if (!interface_exists(SerializerInterface::class)) {
throw new \LogicException('The "symfony/serializer" component is required to use the "serializer" feature.');
}

$loader->load('event_serializer.php');
}

if ($config['normalizer']) {
if (!interface_exists(NormalizerInterface::class)) {
throw new \LogicException('The "symfony/serializer" component is required to use the "normalizer" feature.');
Expand Down
2 changes: 2 additions & 0 deletions src/Symfony/Bundle/DependencyInjection/Configuration.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
use Symfony\Component\Config\Definition\Builder\TreeBuilder;
use Symfony\Component\Config\Definition\ConfigurationInterface;
use Symfony\Component\Serializer\SerializerInterface;

readonly class Configuration implements ConfigurationInterface
{
Expand All @@ -20,6 +21,7 @@ public function getConfigTreeBuilder(): TreeBuilder
$rootNode
->children()
->booleanNode('normalizer')->defaultFalse()->end()
->booleanNode('serializer')->defaultValue(interface_exists(SerializerInterface::class))->end()
->scalarNode('name_converter')->defaultNull()->end()
->scalarNode('cache_dir')->defaultValue('%kernel.cache_dir%/automapper')->end()
->scalarNode('date_time_format')->defaultValue(\DateTimeInterface::RFC3339)->end()
Expand Down

0 comments on commit cfc3e33

Please sign in to comment.