@@ -95,30 +95,39 @@ file looks like this::
9595 []
9696 );
9797
98- Instantiating PHP Classes
99- -------------------------
98+ Instantiating& Hydrating PHP Classes
99+ -------------------------------------
100100
101- The other main feature provided by this component is an instantiator which can
102- create objects and set their properties without calling their constructors or
103- any other methods::
101+ Istantiator
102+ ~~~~~~~~~~~
103+
104+ This component provides an instantiator, which can create objects and set
105+ their properties without calling their constructors or any other methods::
104106
105107 use Symfony\Component\VarExporter\Instantiator;
106108
107- //creates an empty instance of Foo
109+ //Creates an empty instance of Foo
108110 $fooObject = Instantiator::instantiate(Foo::class);
109111
110- //creates a Foo instance and sets one of its properties
112+ //Creates a Foo instance and sets one of its properties
111113 $fooObject = Instantiator::instantiate(Foo::class, ['propertyName' => $propertyValue]);
112114
113- // creates a Foo instance and sets a private property defined on its parent Bar class
115+ The instantiator also allows you to populate the property of a parent class. Assuming
116+ ``Bar `` is the parent class of ``Foo `` and defines a ``privateBarProperty `` attribute::
117+
118+ use Symfony\Component\VarExporter\Instantiator;
119+
120+ // Creates a Foo instance and sets a private property defined on its parent Bar class
114121 $fooObject = Instantiator::instantiate(Foo::class, [], [
115122 Bar::class => ['privateBarProperty' => $propertyValue],
116123 ]);
117124
118125Instances of ``ArrayObject ``, ``ArrayIterator `` and ``SplObjectHash `` can be
119126created by using the special ``"\0" `` property name to define their internal value::
120127
121- // Creates an SplObjectHash where $info1 is associated with $object1, etc.
128+ use Symfony\Component\VarExporter\Instantiator;
129+
130+ // Creates an SplObjectStorage where $info1 is associated with $object1, etc.
122131 $theObject = Instantiator::instantiate(SplObjectStorage::class, [
123132 "\0" => [$object1, $info1, $object2, $info2...],
124133 ]);
@@ -128,5 +137,52 @@ created by using the special ``"\0"`` property name to define their internal val
128137 "\0" => [$inputArray],
129138 ]);
130139
140+ Hydrator
141+ ~~~~~~~~
142+
143+ The instantiator assumes the object you want to populate doesn't exist yet.
144+ Somehow, you may want to fill properties of an already existing object. This is
145+ the goal of the:class: `Symfony\\ Component\\ VarExporter\\ Hydrator `. Here is a
146+ basic usage of the hydrator populating a property of an object::
147+
148+ use Symfony\Component\VarExporter\Hydrator;
149+
150+ $object = new Foo();
151+ Hydrator::hydrate($object, ['propertyName' => $propertyValue]);
152+
153+ The hydrator also allows you to populate the property of a parent class. Assuming
154+ ``Bar `` is the parent class of ``Foo `` and defines a ``privateBarProperty `` attribute::
155+
156+ use Symfony\Component\VarExporter\Hydrator;
157+
158+ $object = new Foo();
159+ Hydrator::hydrate($object, [], [
160+ Bar::class => ['privateBarProperty' => $propertyValue],
161+ ]);
162+
163+ // Alternatively, you can use the special "\0" syntax
164+ Hydrator::hydrate($object, ["\0Bar\0privateBarProperty" => $propertyValue]);
165+
166+ Instances of ``ArrayObject ``, ``ArrayIterator `` and ``SplObjectHash `` can be
167+ populated by using the special ``"\0" `` property name to define their internal value::
168+
169+ use Symfony\Component\VarExporter\Hydrator;
170+
171+ // Creates an SplObjectHash where $info1 is associated with $object1, etc.
172+ $storage = new SplObjectStorage();
173+ Hydrator::hydrate($storage, [
174+ "\0" => [$object1, $info1, $object2, $info2...],
175+ ]);
176+
177+ // creates an ArrayObject populated with $inputArray
178+ $arrayObject = new ArrayObject();
179+ Hydrator::hydrate($arrayObject, [
180+ "\0" => [$inputArray],
181+ ]);
182+
183+ ..versionadded ::6.2
184+
185+ The:class: `Symfony\\ Component\\ VarExporter\\ Hydrator ` was introduced in Symfony 6.2.
186+
131187.. _`OPcache` :https://www.php.net/opcache
132188.. _`PSR-2` :https://www.php-fig.org/psr/psr-2/