Hi @1ed

I think you raise a fair point here.

IMO the cleanest way to handle this would be to split the Instantiator and to introduce something like an Hydrator. The current Instantiator is actually doing both of these tasks

Agreed this is a fair point and splitting the class.

Some thoughts:

1. BC?
2. Probably a Factory::hydrateWith() could be added?
3. Currently, when the instantiator creates the object with the constructor, the attributes are used up (so they aren't used on setters). How could we handle this?

1- About BC all following options will apply to hydrator and not on instantiator anymore: allowExtraAttributes, extraAttributes, alwaysForceProperties, forceProperties, so we need the instantiator to pass these options to the hydrator, in order that this kind of code to continue to work:

    public function initialize(): self
    {
        return $this->instantiateWith(
            (new Instantiator())->alwaysForceProperties()
        );
    }

and we need to deprecated all setters for these options in the instantiator.

Also I may be wrong, but I think there is no valid use case to use Instantioator::forceGet() and Instantioator::forceSet() in userland and they should have been marked internal? so we should deprecate them as well.

2- agreed, and the hydrator should have all the setters for the options mentioned above.

3- IMO this should be handled the same way than now, given Instantiator::instantiate() is "instantiation phase" and the rest of Instantiator::__invoke() is the "hydration phase", then:
- no options passed: the instantiator creates the object via its constructor - hydrator fills in other properties which are not in the constructor
- withoutConstructor is passed: the instantiator creates an "empty shell" object - hydrator fills everything
- forceProperties / alwaysForceProperties / extraAttributes / allowExtraAttributes does not affect instantiation phase

Thinking Factory::hydrateWith() should work like this:

// customize the hydrator
public function initialize(): self
{
    return $this->hydrateWith(function(Hydrator $hydrator) {
        // $hydrator is the "default" hydrator service configured by bundle config
        // this allows us to inject property_accessor and property_info into it
        return $hydrator
            ->alwaysForceProperties()
            ->allowExtraAttributes()
        ; // clones the hydrator
    });

    // alternative to above
    return $this->hydrateWith(Hydrator::FORCE_PROPERTIES | Hydrator::ALLOW_EXTRA);

    // complete control
    return $this->hydrateWith(function(MyObject $object, array $remainingAttributes) {
        $object->someRichMethod($remainingAttributes['foo'], $remainingAttributes['bar']);

        return $object;
    });
}

And Factory::instantiateWith() could work something like:

public function initialize(): self
{
    return $this->instantiateWith(Instantiator::WITHOUT_CONSTRUCTOR);

    // or use a factory method
    return $this->instantiateWith([MyObject::class, 'factoryMethod']);

    // complete control:
    return $this->instantiateWith(function(array &$attributes) {
        $object = new MyObject($attributes['foo'], $attribtues['bar']);

        // required if not using a custom hydrator
        unset($attributes['foo'], $attributes['bar']);

        return $object;
    });
}

I think that's really the only custom config you'd need to make for the instantiator, or am I missing something?

In the bundle config, we'd only need boolean for the default instantiation mode: with constructor (default) or without.

I like the bitwise configurations :)

for the instantiator:

• I also think this is the only config remaining in the instantiator
• it would be nice to not require a manual unset() in userland when using a custom instantiator, but I presently don't see how it could be done

for the hydrator: don't we also need forceProperties and extraAttributes?

it would be nice to not require a manual unset() in userland when using a custom instantiator, but I presently don't see how it could be done

Agreed, don't see a way around it currently either. If customizing both, you could do everything in the instantiator and somehow disable the hydrator.

for the hydrator: don't we also need forceProperties and extraAttributes?

Yep, these just couldn't be configured via bits