Repository files navigation

The VarExporter component provides various tools to deal with the internal stateof objects:

• VarExporter::export() allows exporting any serializable PHP data structure toplain PHP code. While doing so, it preserves all the semantics associated withthe serialization mechanism of PHP (__wakeup,__sleep,Serializable,__serialize,__unserialize);
• Instantiator::instantiate() creates an object and sets its properties withoutcalling its constructor nor any other methods;
• Hydrator::hydrate() can set the properties of an existing object;
• Lazy*Trait can make a class behave as a lazy-loading ghost or virtual proxy.

The reason to useVarExporter::export()vsserialize() origbinary is performance: thanks toOPcache, the resulting code is significantly faster and more memory efficientthan usingunserialize() origbinary_unserialize().

Unlikevar_export(), this works on any serializable PHP value.

It also provides a few improvements overvar_export()/serialize():

• the output is PSR-2 compatible;
• the output can be re-indented without messing up with\r or\n in the data;
• missing classes throw aClassNotFoundException instead of being unserializedtoPHP_Incomplete_Class objects;
• references involvingSplObjectStorage,ArrayObject orArrayIteratorinstances are preserved;
• Reflection*,IteratorIterator andRecursiveIteratorIterator classesthrow an exception when being serialized (their unserialized version is brokenanyway, seehttps://bugs.php.net/76737).

Instantiator::instantiate($class) creates an object of the given class withoutcalling its constructor nor any other methods.

Hydrator::hydrate() sets the properties of an existing object, includingprivate and protected ones. For example:

// Sets the public or protected $object->propertyName propertyHydrator::hydrate($object, ['propertyName' =>$propertyValue]);// Sets a private property defined on its parent Bar class:Hydrator::hydrate($object, ["\0Bar\0privateBarProperty" =>$propertyValue]);// Alternative way to set the private $object->privateBarProperty propertyHydrator::hydrate($object, [], [    Bar::class => ['privateBarProperty' =>$propertyValue],]);

The component provides two lazy-loading patterns: ghost objects and virtualproxies (seehttps://martinfowler.com/eaaCatalog/lazyLoad.html for reference).

Ghost objects work only with concrete and non-internal classes. In the genericcase, they are not compatible with using factories in their initializer.

Virtual proxies work with concrete, abstract or internal classes. They provide anAPI that looks like the actual objects and forward calls to them. They can causeidentity problems because proxies might not be seen as equivalents to the actualobjects they proxy.

Because of this identity problem, ghost objects should be preferred whenpossible. Exceptions thrown by theProxyHelper class can help decide when itcan be used or not.

Ghost objects and virtual proxies both provide implementations for theLazyObjectInterface which allows resetting them to their initial state or toforcibly initialize them when needed. Note that resetting a ghost object skipsits read-only properties. You should use a virtual proxy to reset read-onlyproperties.

By usingLazyGhostTrait either directly in your classes or by usingProxyHelper::generateLazyGhost(), you can make their instances lazy-loadable.This works by creating these instances empty and by computing their state onlywhen accessing a property.

class FooLazyGhostextends Foo{use LazyGhostTrait;}$foo = FooLazyGhost::createLazyGhost(initializer:function (Foo$instance):void {// [...] Use whatever heavy logic you need here// to compute the $dependencies of the $instance$instance->__construct(...$dependencies);// [...] Call setters, etc. if needed});// $foo is now a lazy-loading ghost object. The initializer will// be called only when and if a *property* is accessed.

Alternatively,LazyProxyTrait can be used to create virtual proxies:

$proxyCode = ProxyHelper::generateLazyProxy(newReflectionClass(Foo::class));// $proxyCode contains the reference to LazyProxyTrait// and should be dumped into a file in production envseval('class FooLazyProxy'.$proxyCode);$foo = FooLazyProxy::createLazyProxy(initializer:function ():Foo {// [...] Use whatever heavy logic you need here// to compute the $dependencies of the $instance$instance =newFoo(...$dependencies);// [...] Call setters, etc. if neededreturn$instance;});// $foo is now a lazy-loading virtual proxy object. The initializer will// be called only when and if a *method* is called.

• Documentation
• Contributing
• Report issues andsend Pull Requestsin themain Symfony repository