New concept for the context

[jdreesen]

New context class

This PR introduces a new Neusta\ConverterBundle\Context and deprecates the existing Neusta\ConverterBundle\Converter\Context\GenericContext as well as the use of any other (user-defined) context classes.

The old GenericContext did not support typed values.

User-defined context classes would allow typed values but are problematic if there are multiple bundles involved because it would need multiple inheritance if each bundle wants to define its own (typed) properties in this class.

The new Context fixes this by forcing each context value to be a specific (user-defined) class with the necessary (typed) properties, e.g.:

final class MyContext
{
    public function __construct(
        public readonly string $value,
    ) {
    }
}

You create a context instance with your context value objects and pass it to the converter:

$ctx = Context::create(new MyContext('some value'));

$converter->convert($target, $source, $ctx);

Inside a populator, you can then access the context values like this:

public function populate(object $target, object $source, ?object $ctx = null): void 
{
    $value = null;

	if ($ctx?->has(MyContext::class)) {
        $value = $ctx->get(MyContext::class)->value;
	}
}

Note

The new Context is immutable, so it cannot change within one converter (between its populators).

It is, however, possible to create a derived context instance with the desired changes using with() and without().
This derived context can then be passed on to internal converters, for example.

Tip

If you need to set a context value in one populator and require it in a later one, you can still do so by defining a mutable context value class and adding it to the context before calling the converter.
However, this is at your own risk, and you must ensure that the populators run in the correct order!

ContextConfigurators

Apart from creating the context manually and passing it to the converter, you can also configure it via the new ContextConfigurators.

It is possible to configure global context (for all converters) or converter-specific context (via ContextConfigurators) via the bundle’s configuration.

To do so, first create a ContextConfigurator:

use Neusta\ConverterBundle\Context;
use Neusta\ConverterBundle\Context\ContextConfigurator;

final class MyContextConfigurator implements ContextConfigurator
{
    public function __construct(
        private readonly string $someValue,
    ) {}

    public function configureContext(Context $ctx): Context
    {
        return $ctx->with(
            new MyContext($this->someValue),
        );
    }
}

And register it as a service:

services:
  App\MyContextConfigurator:
    arguments: ['something']

Then configure it either for all converters:

neusta_converter:
 context_configurators:
   - App\MyContextConfigurator

or just a specific one:

neusta_converter:
 converter:
   my_converter:
     context_configurators:
       - App\MyContextConfigurator

Note

If you register global context configurators and converter-specific ones, both will be applied (first the global ones, then the converter-specific ones).

Of course, it is still possible to pass the context manually to Converter::convert() as well.
In this case both contexts will be merged, with the context passed to Converter::convert() taking precedence.