[RFC] Lazy Objects

Hello Valentin,

Thanks for having a look.

Arnaud and I are pleased to share with you the RFC we've been shaping for

over a year to add native support for lazy objects to PHP.

Please find all the details here:
https://wiki.php.net/rfc/lazy-objects

We look forward to your thoughts and feedback.

Cheers,
Nicolas and Arnaud

Hi, Nicolas and Arnaud!

I like the idea, thank you for the RFC!

Here are some initial thoughts and questions:

1. It doesn't seem right that calling
   ReflectionLazyObject::makeLazyGhost has an implicit side effect on
   $instance and returns reflection. It does 2 things and thus breaks the
   SRP. Having smth like $lazyGhost = new ReflectionClass(MyClass)->newLazyGhost($initializer) and/or
   ReflectionLazyObject::makeLazy($object, $initializer): void seems better.

About "new ReflectionClass(MyClass)->newLazyGhost", we could add this but
it would provide a duplicate way to achieve what can be done with
"makeLazy($object)" variants. As you might have read in the RFC, being able
to make a pre-existing instance lazy is needed to cover all use cases.

Then about "ReflectionLazyObject::makeLazy($object, $initializer): void",
is the difference only to return void and not a ReflectionLazyObject
instance? Then this might provide an underperforming API: creating a lazy
object and immediately after setting some of its properties is an use case
that can happen on the hot path (of e.g. Doctrine entities creation steps).
Returning "void" would force an extra call to
ReflectionLazyObject::fromInstance() that the proposed API prevents.

2. If ReflectionLazyObject extends ReflectionObject, then how new ReflectionLazyObject($object) will work for non-lazy objects? Will it
   throw?

The constructor is private so this is not allowed (I should add this to the
RFC).

3. Is extending ReflectionObject really necessary? What about creating
   ReflectionLazyObject as a standalone class without abusing inheritance?
   Or simply adding methods to ReflectionObject / ReflectionClass?

I don't think extending ReflectionObject is necessary. I don't know if
doing so is "abusing" inheritance. It might make sense either way. For the
use cases I identified, it wouldn't harm to not extend anything. Does
anyone else see a reason to go in one or the other direction? To me it just
makes sense to have ReflectionLazyObject extend ReflectionObject.

About adding methods to ReflectionObject / ReflectionClass, you mention
SRP in your message; ReflectionClass/ReflectionObject is already crowded,
and this lazy object topic is better separated to me.

4. The RFC says that Virtual state-proxies are necessary because of

circular references. It's difficult to accept this reasoning, because using
circular references is a bad practice and the given example is something I
try to avoid by all means in my code.

Yet circular references happen all the time in any non-trivial app, so this
has to be supported.

Nicolas

Hi

Please find all the details here:
https://wiki.php.net/rfc/lazy-objects

We look forward to your thoughts and feedback.

I've gave the RFC three or four passes and I'm not quite sure if I
follow everything, here's a list of some questions / remarks that came
to mind, roughly ordered by the order of things appearing in the RFC.

• "been tested successfully on the Doctrine and on the Symfony projects"

Is there a PoC patch showcasing how the code would change / be
simplified for those pre-existing codebases?

• int $options = 0

Not a fan of flag parameters that take a bitset, those provide for a
terrible DX due to magic numbers. Perhaps make this a regular (named)
parameter, or an list of enum LazyObjectOptions { case
SkipInitOnSerialize; }?

• skipProperty()

Not a fan of the method name, because it doesn't really say what it
does, without consulting the docs. Perhaps skipInitializationFor() or
similar?

• setProperty()

Not a fan of the method name, because it is not a direct counterpart to
getProperty(). Unfortunately I don't have a better suggestion.

• The examples should be expanded and clarified, especially the one for
  makeLazyProxy():

My understanding is that the $object that is passed to the first
parameter of makeLazyProxy() is completely replaced. Is this
understanding correct? What does that mean for spl_object_hash(),
spl_object_id()? What does this mean for WeakMap and WeakReference? What
does this mean for objects that are only referenced from within $object?

Consider this example:

 class Foo {
   public function __destruct() { echo __METHOD__; }
 }

 class Bar {
   public string $s;
   public ?Foo $foo;

  public function __destruct() { echo __METHOD__; }
 }

 $bar = new Bar();
 $bar->foo = new Foo();

 ReflectionLazyObject::makeLazyProxy($bar, function (Bar $bar) {
   $result = new Bar();
   $result->foo = null;
   $result->s = 'init';
   return $result;
 });

 var_dump($bar->s);

My understanding is that this will dump string(4) "init". Will the
destructor of Foo be called? Will the destructor of Bar be called?

• What happens if I make an object lazy that already has all properties
  initialized? Will that be a noop? Will that throw? Will that create a
  lazy object that will never automatically be initialized?

• Cloning, unless __clone() is implemented and accesses a property.

The semantics of cloning a lazy object should be explicitly spelled out
in the RFC, ideally with an example of the various edge cases (should
any exist).

• Before calling the initializer, properties that were not initialized
  with ReflectionLazyObject::skipProperty(),
  ReflectionLazyObject::setProperty(),
  ReflectionLazyObject::setRawProperty() are initialized to their default
  value.

Should skipProperty() also skip the initialization to the default value?
My understanding is that it allows skipping the initialization on
access, but when initialization actually happens it should probably be
set to a well-defined value, no?

Am I also correct in my understanding that this should read "initialized
to their default value (if any)", meaning that properties without a
default value are left uninitialized?

• If an exception is thrown while calling the initializer, the object is
  reverted to its pre-initialization state and is still considered lazy.

Does this mean that the initializer will be called once again when
accessing another property? Will the "revert to its pre-initialization"
work properly when you have nested lazy objects? An example would
probably help.

• The initializer is called with the object as first parameter.

What is the behavior of accessing the object properties, while the
initializer is active? Based on the examples, I assume it will not be
recursively called, similarly to how the hooks work?

• The object is marked as non-lazy and the initializer is released.

What does it mean for the initializer to be released? Consider the
following example:

 ReflectionLazyObject::makeLazyGhost($o, $init = function ($o) use

(&$init) {
$o->init = $init;
});

• The return value of the initializer has to be an instance of a parent
  or a child class of the lazy-object and it must have the same properties.

Would returning a parent class not violate the LSP? Consider the
following example:

 class A { public string $s; }
 class B extends A { public function foo() { } }

 $o = new B();
 ReflectionLazyObject::makeLazyProxy($o, function (B $o) {
   return new A();
 });

 $o->foo(); // works
 $o->s = 'init';
 $o->foo(); // breaks

• The destructor of lazy non-initialized objects is not called.

That sounds unsafe. Consider the following example:

 class Mutex {
   public string $s;
   public function __construct() {
     // take lock
   }

   public function __destruct() {
     // release lock
   }
 }

 $m = new Mutex();
 ReflectionLazyObject::makeLazyGhost($m, function ($m) {
 });
 unset($m); // will not release the lock.

• Using the Manager::createManager() factory is not compatible with
  ghost objects because their initializer requires initializing the ghost
  object in place,

I don't understand that example, because it doesn't actually use lazy
objects and thus I don't understand if Manager, Dispatcher, or both are
intended to be lazily initialized. It would help to rewrite the example
to use makeLazyGhost() and indicate with a comment in which cases the
problem would arise.

• Backward Incompatible Changes

There a technicality: The ReflectionLazyObject class name will no
longer be available to userland.

Best regards
Tim Düsterhus

As someone who has had to maintain these proxies/ghosts before, this
looks quite useful and powerful. I feel it has rather wonky syntax,
but it is clearly better than the alternative of implementing it
yourself. I'm also a huge fan that the syntax allows for
usage/creation far and away from the definition/class itself.

Good luck, and I hope it passes.

Robert Landers
Software Engineer
Utrecht NL

Hi Tim,

That's a lot of interesting feedback. I will try to answer some of
your points, and Nicolas will follow with other points.

• int $options = 0

Not a fan of flag parameters that take a bitset, those provide for a
terrible DX due to magic numbers. Perhaps make this a regular (named)
parameter, or an list of enum LazyObjectOptions { case
SkipInitOnSerialize; }?

The primary reason for choosing to represent $options as a bitset is
that it's consistent with the rest of the Reflection API (e.g.
ReflectionClass::getProperties() uses a bitset for the $filter
parameter).

I don't get your point about magic numbers since we are using
constants to abstract them.

• skipProperty()

Not a fan of the method name, because it doesn't really say what it
does, without consulting the docs. Perhaps skipInitializationFor() or
similar?

We have opted for skipInitializerForProperty()

• setProperty()

Not a fan of the method name, because it is not a direct counterpart to
getProperty(). Unfortunately I don't have a better suggestion.

We have renamed setRawProperty() to setRawPropertyValue() in the RFC.
We are open to other suggestions.

We have also removed setProperty(), as we believe that there is no
use-case for it.

• The examples should be expanded and clarified, especially the one for
  makeLazyProxy():

Agreed. We will add examples and clarify some behaviors.

My understanding is that the $object that is passed to the first
parameter of makeLazyProxy() is completely replaced. Is this
understanding correct? What does that mean for spl_object_hash(),
spl_object_id()? What does this mean for WeakMap and WeakReference? What
does this mean for objects that are only referenced from within $object?

The object is updated in-place, and retains its identity. It is not
replaced. What makeLazyGhost() and makeLazyProxy() do is equivalent to
calling unset() on all properties, and setting a flag on the object
internally. Apart from setting the internal flag, this is achievable
in userland by iterating on all properties via the Reflection API, and
using unset() in the right scope with a Closure.

spl_object_id(), spl_object_hash(), SplObjectStorage, WeakMap,
WeakReference, strict equality, etc are not affected by makeLazy*().

The intended use of makeLazyGhost() and makeLazyProxy() is to call
them either on an object created with
ReflectionClass::newInstanceWithoutConstructor(), or on $this in a
constructor. The latter is the reason why these APIs take an existing
object.

The proposed patch integrates into the object handlers fallback code
path used to manage accesses to undefined properties. We implement
lazy initialization by hooking into undefined property accesses,
without impacting the fast path.

Consider this example:

 class Foo {
   public function __destruct() { echo __METHOD__; }
 }

 class Bar {
   public string $s;
   public ?Foo $foo;

  public function __destruct() { echo __METHOD__; }
 }

 $bar = new Bar();
 $bar->foo = new Foo();

 ReflectionLazyObject::makeLazyProxy($bar, function (Bar $bar) {
   $result = new Bar();
   $result->foo = null;
   $result->s = 'init';
   return $result;
 });

 var_dump($bar->s);

My understanding is that this will dump string(4) "init". Will the
destructor of Foo be called? Will the destructor of Bar be called?

This will print:

Foo::__destruct (during makeLazyProxy())
string(4) "init" (during `var_dump()`)

and eventually

Bar::__destruct (when $bar is released)

• What happens if I make an object lazy that already has all properties
  initialized? Will that be a noop? Will that throw? Will that create a
  lazy object that will never automatically be initialized?

All properties are unset as described earlier, and the object is
flagged as lazy. The object will automatically initialize when trying
to observe its properties.

However, making a fully initialized object lazy is not the intended use-case.

• Cloning, unless __clone() is implemented and accesses a property.

The semantics of cloning a lazy object should be explicitly spelled out
in the RFC, ideally with an example of the various edge cases (should
any exist).

Agreed. We are working on expanding the RFC about this

• Before calling the initializer, properties that were not initialized
  with ReflectionLazyObject::skipProperty(),
  ReflectionLazyObject::setProperty(),
  ReflectionLazyObject::setRawProperty() are initialized to their default
  value.

Should skipProperty() also skip the initialization to the default value?
My understanding is that it allows skipping the initialization on
access, but when initialization actually happens it should probably be
set to a well-defined value, no?

Am I also correct in my understanding that this should read "initialized
to their default value (if any)", meaning that properties without a
default value are left uninitialized?

The primary effect of skipProperty() is to mark a property as
non-lazy, so that accessing it does not trigger the initialization of
the entire object. It also sets the property to its default value if
any, otherwise it is left as undef.

Accessing this property afterwards has exactly the same effect as
doing so on an object created with
ReflectionClass::newInstanceWithoutConstructor() (including triggering
errors when reading an uninitialized property).

• If an exception is thrown while calling the initializer, the object is
  reverted to its pre-initialization state and is still considered lazy.

Does this mean that the initializer will be called once again when
accessing another property?

Yes. The goal is to prevent transition from lazy to initialized when
an unexpected error occurred in the initializer.

Will the "revert to its pre-initialization"
work properly when you have nested lazy objects? An example would
probably help.

Only the effects on the object itself are reverted. External side
effects are not reverted.

• The initializer is called with the object as first parameter.

What is the behavior of accessing the object properties, while the
initializer is active? Based on the examples, I assume it will not be
recursively called, similarly to how the hooks work?

For ghost objects, the initializer is supposed to initialize the
object itself like a constructor would do. During initializer
execution, the object has exactly the same state and behavior as it
would have in its constructor during new:

• The object is not lazy.
• Properties have their default value (if any) and are accessed
  without triggering a nested initialization.
• If setRawPropertyValue() was used, some properties may have a value
  different from their default.

For virtual proxies, the initializer is supposed to return another
object. Accessing the proxy object during initialization does not
trigger recursive initializations. Some properties will have a value
if setRawPropertyValue() or skipInitializationForProperty().

• The object is marked as non-lazy and the initializer is released.

What does it mean for the initializer to be released? Consider the
following example:

 ReflectionLazyObject::makeLazyGhost($o, $init = function ($o) use

(&$init) {
$o->init = $init;
});

"released" here means that the initializer is not referenced anymore
by this object, and may be freed if it is not referenced anywhere
else.

• The return value of the initializer has to be an instance of a parent
  or a child class of the lazy-object and it must have the same properties.

Would returning a parent class not violate the LSP? Consider the
following example:

 class A { public string $s; }
 class B extends A { public function foo() { } }

 $o = new B();
 ReflectionLazyObject::makeLazyProxy($o, function (B $o) {
   return new A();
 });

 $o->foo(); // works
 $o->s = 'init';
 $o->foo(); // breaks

$o->foo() calls B::foo() in both cases here, as $o is always the proxy
object. We need to double check, but we believe that this rule doesn't
break LSP.

• The destructor of lazy non-initialized objects is not called.

That sounds unsafe. Consider the following example:

 class Mutex {
   public string $s;
   public function __construct() {
     // take lock
   }

   public function __destruct() {
     // release lock
   }
 }

 $m = new Mutex();
 ReflectionLazyObject::makeLazyGhost($m, function ($m) {
 });
 unset($m); // will not release the lock.

Good point. The Mutex constructor is called during "new Mutex()", but
the object is made lazy after that, and the destructor is never
called.

We have made the following changes to the RFC:

• makeLazyGhost / makeLazyProxy will call the object destructor
• A new option flag is added, ReflectionLazyObject::SKIP_DESTRUCTOR,
  that disables this behavior

This is not ideal since the intended use of these methods is to call
them on objects created with newInstanceWithoutConstructor(), or
directly in a constructor, and both of these will need this flag, but
at least it's safe by default.

Thanks again for the feedback.

Best Regards,
Arnaud

Hi Tim,

Thanks for the detailed feedback. Arnaud already answered most of your
questions, here is the remaining one:

Please find all the details here:
https://wiki.php.net/rfc/lazy-objects

We look forward to your thoughts and feedback.

I've gave the RFC three or four passes and I'm not quite sure if I
follow everything, here's a list of some questions / remarks that came
to mind, roughly ordered by the order of things appearing in the RFC.

• "been tested successfully on the Doctrine and on the Symfony projects"

Is there a PoC patch showcasing how the code would change / be
simplified for those pre-existing codebases?

Yes!
See https://github.com/nicolas-grekas/symfony/pull/44 for Symfony. All the
complex code is gone \o/
And if anyone is wondering: No, we're not moving this complexity into the
engine. As Arnaud wrote somewhere: Implementation in core is simple
compared to userland as we are at the right level of abstraction. No code
gen, no edge cases with relative type hints, visibility, readonly, hooks,
etc. We get more consistent and transparent behavior as well compared to
userland impl.

For Doctrine, the URL is
https://github.com/nicolas-grekas/doctrine-orm/pull/6 for now, with the
most important line being the removal of the symfony/var-exporter
dependency.

After yours and Valentin's feedback, we're considering an updated API that
would provide the same capabilities but that might be more consensual.

The RFC isn't updated but below is what we have in our drafts. Let me know
what you think already if you want (otherwise, let us work on the updated
implementation/RFC and we'll let you know about them ASAP).

Nicolas
PS: I understand that the concepts in the RFC might be difficult to grasp.
They were certainly challenging for me to summarize. I would happily accept
any help to improve the wording if anyone is willing.

class ReflectionLazyClass extends ReflectionClass
{
public int const SKIP_INITIALIZATION_ON_SERIALIZE = 1;
public int const SKIP_DESTRUCTOR = 2;

public function __construct(object|string $objectOrClass);

public function newLazyGhostInstance(callable $initializer, int $options = 0
): object;
public function newLazyProxyInstance(callable $initializer, int $options = 0
): object;

public function makeInstanceLazyGhost(object $object, callable $initializer,
int $options = 0): void;
public function makeInstanceLazyProxy(object $object, callable $initializer,
int $options = 0): void;
public static function isInitialized(object $instance): bool;
/**

• Initializes a lazy object (no-op if the object is already initialized.)
• The backing object is returned, which can be another instance than the
  lazy object when the virtual strategy is used.
  /
  public function initialize(object $object, bool $skipInitializer = false):
  object;
  /*
• Marks a property as not triggering initialization when being accessed.
• This method is useful to bypass initialization when setting a property.
  /
  public function skipInitializerForProperty(object $object, string $name,
  string $class = null): void;
  /*
• Sets a property without triggering initialization while skipping hooks
  if any.
  */
  public function setRawPropertyValue(object $object, string $name, mixed $
  value, string $class = null): void;
  }

Hi Marco,

Thank you for the very detailed feedback. Please find my answers below.
Nicolas will follow-up on some points.

• lazy proxies should probably explore replacing object identity further

We have thought about a few approaches for that, but none is really
concluding:

Fusioning the identity of the proxy and the real instance, such that both
objects are considered to have the same identity with regard to
spl_object_id(), SplObjectStorage, WeakMap, and strict equality after
initialization will lead to weird effects.

For example, we don't know what the behavior of this should be:

$reflector = new ReflectionClass(MyClass::class);

$realInstance = new MyClass();
$proxy = $reflector->newLazyProxy(function () use ($realInstance) {
    return $realInstance;
});

$store = new SplObjectStorage();
$store[$realInstance] = 1;
$store[$proxy] = 2;

$reflector->initialize($proxy);

var_dump(count($store)); // 1 or 2 ?

A second approach, suggested by Benjamin, would be that properties of the
instance returned by the factory are copied to the proxy, the proxy marked
as initialized (so it's not a proxy anymore), and the instance returned by
the factory discarded. One problem of this approach is that the instance
may continue to exist independently of the proxy if it's referenced
somewhere. So, proper usage of the lazy proxy API would require the factory
to be aware of that, and to return an object that is not referenced
anywhere. As we implemented the proxy strategy primarily for use-cases
where we don't control the factory, this approach would not work.

A third approach would be to replace all references to the proxy by
references to the backing instance after initialization. Implementing this
approach would be prohibitively slow as it requires to scan the entire
object graph of the process.

None of these approaches are concluding unfortunately. Having two distinct
identities for the proxy and the real instance doesn't appear to be an
issue in practice, however (e.g. in Symfony).

• don't like expanding ReflectionClass further: LazyGhost and

LazyProxy classes (or such) instead

The rationale for expanding ReflectionClass and ReflectionProperty is that
code creating lazy objects tend to also use these two classes, for
introspection or to initialize the object. Also, we feel that the new
methods are directly related to existing methods. E.g. newLazyGhost() is
just another variant of newInstance() and newInstanceWithoutConstructor(),
and setRawValueWithoutLazyInitialization() is just another variant of
setValue() and setRawValue() (added in the hooks RFC).

• initialize() shouldn't have a boolean behavioral switch parameter: make

2 methods

Agreed. We have updated the RFC to split the method into initalize() and
markAsInitialized().

• flags should be a list<SomeEnumAroundProxies> instead. A bitmask for
  a new API feels unsafe and anachronistic, given the tiny performance hit.

Unfortunately this leads to a 30% slowdown in newLazyGhost() when switching
to an array of enums, in a micro benchmark. I'm not sure how this would
impact a real application, but given this is a performance critical
feature, the slowdown is an issue. Besides that, no existing API in core is
using an array of enums, and we don't want to introduce this concept in
this RFC.

From an abstraction point of view, lazy objects from this RFC are
indistinguishable from non-lazy ones

• do the following aspects always apply? I understand they don't for lazy

proxies, just for ghosts?

• spl_object_id($object) === spl_object_id($proxy)?
• get_class($object) === get_class($proxy)?

Good catch, this phrase is not true for proxies, with relation to the
identity of a proxy and its real instance. Apart from that, the main point
of this phrase remains: interaction with a proxy has the same behavior as
interaction with a real instance, and they can be used without knowing they
are lazy.

Proxies: The initializer returns a new instance, and interactions with
the proxy object are forwarded to this instance

• another note on naming: I used "value holder" inside ProxyManager,
  because using just "proxy" as a name led to a lot of confusion. This also
  applies to me trying to distinguish proxy types inside the RFC and this
  discussion.

The name "Value Holder" appears to be taken for another pattern already:
https://martinfowler.com/eaaCatalog/lazyLoad.html
The exact name of the pattern used in this RFC is the "Virtual
State-Proxy", but others have suggested using just "Proxy" in the RFC. In
the API we use "LazyProxy".

Internal objects are not supported because their state is usually not
managed via regular properties.

• sad, but understandable limitation
• what happens if a class extends an internal engine class, like the
  gruesome ArrayObject?

This also applies to sub-classes of internal objects. This is specified
under ReflectionClass::newLazyGhost(), but I've clarified that here too.

• Given the recent improvements around closures and the ... syntax (
  https://wiki.php.net/rfc/first_class_callable_syntax), is it worth having
  Closure only as argument type?
• should we declare generic types in the RFC/docs, even if just in the
  stubs?
  • they would serve as massive documentation improvement for Psalm and
    PHPStan
  • it would be helpful to document $initializer and $factory as
    :void or :object functions
    • can the engine check that, perhaps? I have no idea if Closure
      can provide such information on return types, inside the engine.

Could you say more about the benefits of type hinting as Closure instead of
callable? Is this purely to be able to type check the return type earlier?
We may be able to achieve this while retaining the callable type hint, when
a Closure is given, but this would be unusual. Maybe this is something we
can push in a different RFC?

• what happens if ReflectionClass#reset*() methods are used on a
  different class instance?
  • considered?

The object must be an instance of the class represented by ReflectionClass
(including of a sub-class)

$reflector->getProperty('id')->skipLazyInitialization($post);

• perfect for partial objects / understanding why this was implemented
  • would it make sense to have an API to set "bulk" values in an object
    this way, instead of having to do this for each property manually?
    • avoids instantiating reflection properties / marking individual
      properties manually
    • perhaps future scope?
      • thinking (new GhostObject($class))->initializePropertiesTo(['foo' => 'bar', 'baz' => 'tab'])

This is something we thought about but it's not as simple as it seems: we
have to support setting private properties of parent classes, so the
argument has to represent that. A format that would be able to represent
that is as follows:

• The argument is a map of class names to properties
• The properties are a map of property name to property value. To support
  skipping a property (and setting it to its default value), numeric keys (no
  key specified) denote that the value is a property name to skip.

Example:

class ParentOfA {
private $c;
private $d = 1;
}
class A extends ParentOfA {
private $a;
private $b;
}

->initializePropertiesTo([
A::class => ['a' => 'value-a', 'b' => 'value-b'],
ParentOfA::class => ['c' => 'value-c', 'd'], // 'd' is init to its
default value
])

An alternative is to use the same binary format as
get_mangled_object_vars().

WDYT?

Initialization Triggers

• really happy to see all these edge cases being considered here!
  • how much of this new API has been tried against the test suite of
    (for example) ocramius/proxy-manager?
    • mostly asking because there's tons of edge cases noted in there

Nicolas has tested the implementation extensively on the VarExporter and
DIC components, and on Doctrine. We would be happy if you could check with
the ocramius/proxy-manager test suite.

Cloning, unless __clone() is implemented and accesses a property.

• how is the initializer of a cloned proxy used?
  • Is the initializer cloned too?

The initializer is not cloned. I've clarified this in the RFC. The
Initialization Sequence section has an example of how an initializer can
detect being called for a clone of the origin lazy object, if necessary:

$init = function ($object) use (&$originalObject) {
if ($object !== $originalObject) {
// we are initializing a clone
}};$originalObject = $reflector->newLazyProxy($init);

* what about the object that a lazy proxy forwards state access to? Is

it cloned too?

Cloning an initialized proxy is the same as cloning the real instance (this
clones the real instance and returns it).

The following special cases do not trigger initialization of a lazy
object:

• Will accessing a property via a debugger (such as XDebug) trigger
  initialization here?
  • asking because debugging proxy initialization often led to problems,
    in the past
    • sometimes even IDEs crashing, or segfaults

Good point, I will check this. The implementation is biased towards
initialization, so accessing a lazy object will usually initialize it.
However the internal APIs used by var_dump and get_mangled_object_vars() do
not trigger initialization, so if a debugger uses that, it shouldn't
trigger initialization.

• this wording is a bit confusing:

Proxy Objects
The actual instance is set to the return value.

• considering the following paragraph:

The proxy object is not replaced or substituted for the actual
instance.

Indeed. "actual instance" is supposed to designate the instance that the
proxy forwards to, but I see why it's confusing. I've renamed "actual
instance" to "real instance". WDYT?

After initialization, property accesses on the proxy are forwarded to
the actual instance.
Observing properties of the proxy has the same result as observing
properties of the actual instance.

• This is some sort of "quantum locking" of both objects?
• How hard is it to break this linkage?
  • Can properties be unset(), for example?
  • what happens to dynamic properties?
    • I don't use them myself, and I discourage their usage, but it
      would be OK to just document the expected behavior

The linkage can not be broken. unset() and dynamic properties are not
special, in that these are just property accesses. All property accesses on
the proxy are forwarded to the real instance.

If the initializer throws, the object properties are reverted to their
pre-initialization state and the object is
marked as lazy again.

• this is some sort of "transactional" behavior
  • welcome API, but is it worth having this complexity?
    • is there a performance tradeoff?
    • is a copy of the original state kept during initializer calls?
    • OK with it myself, just probing design considerations

I believe it's worth having this, as it prevents leaving an object in a
corrupt state, which could then be accessed later, in case of temporary
initializer failure.

The performance overhead and complexity are small. A shallow copy of the
original state is kept during initialization. As the copy is shallow this
is just a few pointer copies and refcount increases.

• the example uses setRawValueWithoutLazyInitialization(), and
  initialization then accesses public properties
  • shouldn't a property that now has a value not trigger
    initialization anymore?
    • or does that require
      ReflectionProperty#skipLazyInitialization() calls, for that to work?

setRawValueWithoutLazyInitialization() has the same effect as
skipLazyInitialization(), in addition to setting the specified value. I've
clarified this in the RFC.

ReflectionClass::SKIP_INITIALIZATION_ON_SERIALIZE: By default,
serializing a lazy object triggers its initialization
This flag disables that behavior, allowing lazy objects to be serialized
as empty objects.

• how would one deserialize an empty object into a proxy again?
  • would this understanding be deferred to the (de-)serializer of
    choice?
  • exercise for userland?

Yes this is left as exercise to userland when this flag is used.

ReflectionClass::newLazyProxy()
The factory should return a new object: the actual instance.

• what happens if the user mis-implements the factory as function (object $proxy): object { return $proxy; }?
  • this is obviously a mistake on their end, but is it somehow
    preventable?

Returning a lazy object (including an initialized proxy) is not allowed and
will throw. I've clarified this in the RFC (the RFC specified that
returning a lazy object was not allowed, but whether this included
initialized proxies was not clear).

ReflectionClass::resetAsLazyProxy()
The proxy and the actual instance are distinct objects, with distinct
identities.

• When creating a lazy proxy, all property accesses are forwarded to a new
  instance
  • are all property accesses re-bound to the new instance?
  • are there any leftovers pointing to the old instance anywhere?
    • thinking dynamic properties and similar

Yes all property accesses are forwarded to the new instance after that.
There can not be any leftovers to the old instance anywhere, including in
dynamic properties (the resetAsLazy*() methods reset the object entirely).

ReflectionProperty::setRawValueWithoutLazyInitialization()
The method does not call hooks, if any, when setting the property value.

• So far, it has been possible to unset($object->property) to force
  __get and __set to be called
  • will setRawValueWithoutLazyInitialization skip also this "unset
    properties" behavior that is possible in userland?
    • this is fine, just a documentation detail to note
    • if it is like that, is it worth renaming the method
      setValueWithoutCallingHooks or such?
      • not important, just noting this opportunity