[VarExporter] Deprecate per-property lazy-initializers

Author: nicolas-grekas

UPGRADE-6.4.md

@@ -38,6 +38,7 @@ Components
 * [Serializer](#Serializer)
 * [Templating](#Templating)
 * [Validator](#Validator)
+* [VarExporter](#VarExporter)
 * [Workflow](#Workflow)
 
 BrowserKit
@@ -230,6 +231,11 @@ Validator
  * Deprecate `ValidatorBuilder::disableAnnotationMapping()`, use `ValidatorBuilder::disableAttributeMapping()` instead
  * Deprecate `AnnotationLoader`, use `AttributeLoader` instead
 
+VarExporter
+-----------
+
+ * Deprecate per-property lazy-initializers
+
 Workflow
 --------
 

src/Symfony/Component/VarExporter/CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+6.4
+---
+
+ * Deprecate per-property lazy-initializers
+
 6.2
 ---
 

src/Symfony/Component/VarExporter/LazyGhostTrait.php

@@ -23,29 +23,20 @@ trait LazyGhostTrait
     /**
      * Creates a lazy-loading ghost instance.
      *
-     * When the initializer is a closure, it should initialize all properties at
-     * once and is given the instance to initialize as argument.
-     *
-     * When the initializer is an array of closures, it should be indexed by
-     * properties and closures should accept 4 arguments: the instance to
-     * initialize, the property to initialize, its write-scope, and its default
-     * value. Each closure should return the value of the corresponding property.
-     * The special "\0" key can be used to define a closure that returns all
-     * properties at once when full-initialization is needed; it takes the
-     * instance and its default properties as arguments.
-     *
-     * Properties should be indexed by their array-cast name, see
+     * Skipped properties should be indexed by their array-cast identifier, see
      * https://php.net/manual/language.types.array#language.types.array.casting
      *
-     * @param (\Closure(static):void
-     *        |array<string, \Closure(static, string, ?string, mixed):mixed>
-     *        |array{"\0": \Closure(static, array<string, mixed>):array<string, mixed>}) $initializer
-     * @param array<string, true>|null $skippedProperties An array indexed by the properties to skip, aka the ones
-     *                                                    that the initializer doesn't set when its a closure
+     * @param (\Closure(static):void   $initializer       The closure should initialize the object it receives as argument
+     * @param array<string, true>|null $skippedProperties An array indexed by the properties to skip, a.k.a. the ones
+     *                                                    that the initializer doesn't initialize, if any
      * @param static|null              $instance
      */
     public static function createLazyGhost(\Closure|array $initializer, array $skippedProperties = null, object $instance = null): static
     {
+        if (\is_array($initializer)) {
+            trigger_deprecation('symfony/var-exporter', '6.4', 'Per-property lazy-initializers are deprecated and won\'t be supported anymore in 7.0, use an object initializer instead.');
+        }
+
         $onlyProperties = null === $skippedProperties && \is_array($initializer) ? $initializer : null;
 
         if (self::class !== $class = $instance ? $instance::class : static::class) {

src/Symfony/Component/VarExporter/README.md

@@ -105,18 +105,6 @@ $foo = FooLazyGhost::createLazyGhost(initializer: function (Foo $instance): void
 // be called only when and if a *property* is accessed.
 ```
 
-You can also partially initialize the objects on a property-by-property basis by
-adding two arguments to the initializer:
-
-```php
-$initializer = function (Foo $instance, string $propertyName, ?string $propertyScope): mixed {
-    if (Foo::class === $propertyScope && 'bar' === $propertyName) {
-        return 123;
-    }
-    // [...] Add more logic for the other properties
-};
-```
-
 ### `LazyProxyTrait`
 
 Alternatively, `LazyProxyTrait` can be used to create virtual proxies:

src/Symfony/Component/VarExporter/Tests/LazyGhostTraitTest.php

@@ -186,6 +186,9 @@ public function testFullInitialization()
         $this->assertSame(1, $counter);
     }
 
+    /**
+     * @group legacy
+     */
     public function testPartialInitialization()
     {
         $counter = 0;
@@ -243,6 +246,9 @@ public function testPartialInitialization()
         $this->assertSame([123, 345, 456, 567, 234, 678], array_values($properties));
     }
 
+    /**
+     * @group legacy
+     */
     public function testPartialInitializationWithReset()
     {
         $initializer = static fn (ChildTestClass $instance, string $property, ?string $scope, mixed $default) => 234;
@@ -275,6 +281,9 @@ public function testPartialInitializationWithReset()
         $this->assertSame(234, $instance->public);
     }
 
+    /**
+     * @group legacy
+     */
     public function testPartialInitializationWithNastyPassByRef()
     {
         $instance = ChildTestClass::createLazyGhost(['public' => fn (ChildTestClass $instance, string &$property, ?string &$scope, mixed $default) => $property = $scope = 123]);
@@ -307,6 +316,9 @@ public function testReflectionPropertyGetValue()
         $this->assertSame(-3, $r->getValue($obj));
     }
 
+    /**
+     * @group legacy
+     */
     public function testFullPartialInitialization()
     {
         $counter = 0;
@@ -335,6 +347,9 @@ public function testFullPartialInitialization()
         $this->assertSame(1000, $counter);
     }
 
+    /**
+     * @group legacy
+     */
     public function testPartialInitializationFallback()
     {
         $counter = 0;
@@ -357,6 +372,9 @@ public function testPartialInitializationFallback()
         $this->assertSame(1000, $counter);
     }
 
+    /**
+     * @group legacy
+     */
     public function testFullInitializationAfterPartialInitialization()
     {
         $counter = 0;

src/Symfony/Component/VarExporter/composer.json

@@ -16,7 +16,8 @@
         }
     ],
     "require": {
-        "php": ">=8.1"
+        "php": ">=8.1",
+        "symfony/deprecation-contracts": "^2.5|^3"
     },
     "require-dev": {
         "symfony/var-dumper": "^5.4|^6.0|^7.0"