The VarExporter component provides various tools to deal with the internal state of objects:
VarExporter::export()
allows exporting any serializable PHP data structure to plain PHP code. While doing so, it preserves all the semantics associated with the serialization mechanism of PHP (__wakeup
,__sleep
,Serializable
,__serialize
,__unserialize
);Instantiator::instantiate()
creates an object and sets its properties without calling 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 use VarExporter::export()
vs serialize()
or
igbinary is performance: thanks to
OPcache, the resulting code is significantly faster and more memory efficient
than using unserialize()
or igbinary_unserialize()
.
Unlike var_export()
, this works on any serializable PHP value.
It also provides a few improvements over var_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 a
ClassNotFoundException
instead of being unserialized toPHP_Incomplete_Class
objects; - references involving
SplObjectStorage
,ArrayObject
orArrayIterator
instances are preserved; Reflection*
,IteratorIterator
andRecursiveIteratorIterator
classes throw an exception when being serialized (their unserialized version is broken anyway, see https://bugs.php.net/76737).
Instantiator::instantiate($class)
creates an object of the given class without
calling its constructor nor any other methods.
Hydrator::hydrate()
sets the properties of an existing object, including
private and protected ones. For example:
// Sets the public or protected $object->propertyName property
Hydrator::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 property
Hydrator::hydrate($object, [], [
Bar::class => ['privateBarProperty' => $propertyValue],
]);
The component provides two lazy-loading patterns: ghost objects and virtual proxies (see https://martinfowler.com/eaaCatalog/lazyLoad.html for reference).
Ghost objects work only with concrete and non-internal classes. In the generic case, they are not compatible with using factories in their initializer.
Virtual proxies work with concrete, abstract or internal classes. They provide an API that looks like the actual objects and forward calls to them. They can cause identity problems because proxies might not be seen as equivalents to the actual objects they proxy.
Because of this identity problem, ghost objects should be preferred when
possible. Exceptions thrown by the ProxyHelper
class can help decide when it
can be used or not.
Ghost objects and virtual proxies both provide implementations for the
LazyObjectInterface
which allows resetting them to their initial state or to
forcibly initialize them when needed. Note that resetting a ghost object skips
its read-only properties. You should use a virtual proxy to reset read-only
properties.
By using LazyGhostTrait
either directly in your classes or by using
ProxyHelper::generateLazyGhost()
, you can make their instances lazy-loadable.
This works by creating these instances empty and by computing their state only
when accessing a property.
class FooLazyGhost extends 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(new ReflectionClass(Foo::class));
// $proxyCode contains the reference to LazyProxyTrait
// and should be dumped into a file in production envs
eval('class FooLazyProxy'.$proxyCode);
$foo = FooLazyProxy::createLazyProxy(initializer: function (): Foo {
// [...] Use whatever heavy logic you need here
// to compute the $dependencies of the $instance
$instance = new Foo(...$dependencies);
// [...] Call setters, etc. if needed
return $instance;
});
// $foo is now a lazy-loading virtual proxy object. The initializer will
// be called only when and if a *method* is called.