symfony · fancyweb · Sep 24, 2020
diff --git a/src/Symfony/Component/OptionsResolver/CHANGELOG.md b/src/Symfony/Component/OptionsResolver/CHANGELOG.md
@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+5.2.0
+-----
+
+ * added the `$closureTriggerOptions` argument to the `OptionsResolver::setDeprecated()` method.
+
 5.1.0
 -----
 

diff --git a/src/Symfony/Component/OptionsResolver/OptionsResolver.php b/src/Symfony/Component/OptionsResolver/OptionsResolver.php
@@ -435,11 +435,14 @@ public function isNested(string $option): bool
      * passed to the closure is the value of the option after validating it
      * and before normalizing it.
      *
-     * @param string          $package The name of the composer package that is triggering the deprecation
-     * @param string          $version The version of the package that introduced the deprecation
-     * @param string|\Closure $message The deprecation message to use
+     * @param string          $package               The name of the composer package that is triggering the deprecation
+     * @param string          $version               The version of the package that introduced the deprecation
+     * @param string|\Closure $message               The deprecation message to use
+     * @param string[]        $closureTriggerOptions The options that also trigger the execution of the closure when they are resolved
+     *                                               This is useful when the deprecation is at the same time conditional, actually generated with its default value, and dependent of the value of others options.
+     *                                               In this case, those others options should be passed as the closure trigger options.
      */
-    public function setDeprecated(string $option/*, string $package, string $version, $message = 'The option "%name%" is deprecated.' */): self
+    public function setDeprecated(string $option/*, string $package, string $version, $message = 'The option "%name%" is deprecated.', array $closureTriggerOptions = [] */): self
     {
         if ($this->locked) {
             throw new AccessException('Options cannot be deprecated from a lazy option or normalizer.');
@@ -471,12 +474,38 @@ public function setDeprecated(string $option/*, string $package, string $version
             return $this;
         }
 
+        if (\func_num_args() < 5) {
+            $closureTriggerOptions = [];
+        } else {
+                if (!\is_array($closureTriggerOptions = $args[4])) {
+                throw new InvalidArgumentException(sprintf('Invalid type for the $closureTriggerOptions argument, expected an array of strings, but got "%s".', get_debug_type($closureTriggerOptions)));
+            }
+        }
+
+        if ($closureTriggerOptions && !$message instanceof \Closure) {
+            throw new InvalidArgumentException('The $closureTriggerOptions argument must only be given when the message is a \Closure.');
+        }
+
+        foreach ($closureTriggerOptions as $closureTriggerOption) {
+            if (!isset($this->defined[$closureTriggerOption])) {
+                throw new UndefinedOptionsException(sprintf('The option "%s" does not exist, defined options are: "%s".', $this->formatOptions([$closureTriggerOption]), implode('", "', array_keys($this->defined))));
+            }
+
+            if ($closureTriggerOption === $option) {
+                throw new InvalidArgumentException('The $closureTriggerOptions argument must not contain the deprecated option.');
+            }
+        }
+
         $this->deprecated[$option] = [
             'package' => $package,
             'version' => $version,
             'message' => $message,
         ];
 
+        if ($closureTriggerOptions) {
+            $this->deprecated[$option]['closure_trigger_options'] = $closureTriggerOptions;
+        }
+
         // Make sure the option is processed
         unset($this->resolved[$option]);
 
@@ -1077,9 +1106,24 @@ public function offsetGet($option, bool $triggerDeprecation = true)
             }
         }
 
+        if ($doTriggerDeprecation = $triggerDeprecation && isset($this->deprecated[$option])) {
+            if (!isset($this->given[$option]) && (!$this->calling || !\is_string($this->deprecated[$option]['message']))) {
+                $doTriggerDeprecation = false;
+                if (isset($this->deprecated[$option]['closure_trigger_options'])) {
+                    foreach ($this->deprecated[$option]['closure_trigger_options'] as $closureTriggerOption) {
+                        if (isset($this->given[$closureTriggerOption])) {
+                            $doTriggerDeprecation = true;
+
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+
         // Check whether the option is deprecated
         // and it is provided by the user or is being called from a lazy evaluation
-        if ($triggerDeprecation && isset($this->deprecated[$option]) && (isset($this->given[$option]) || ($this->calling && \is_string($this->deprecated[$option])))) {
+        if ($doTriggerDeprecation) {
             $deprecation = $this->deprecated[$option];
             $message = $this->deprecated[$option]['message'];
 

diff --git a/src/Symfony/Component/OptionsResolver/Tests/Debug/OptionsResolverIntrospectorTest.php b/src/Symfony/Component/OptionsResolver/Tests/Debug/OptionsResolverIntrospectorTest.php
@@ -257,13 +257,15 @@ public function testGetClosureDeprecation()
     {
         $resolver = new OptionsResolver();
         $resolver->setDefined('foo');
-        $resolver->setDeprecated('foo', 'vendor/package', '1.1', $closure = function (Options $options, $value) {});
+        $resolver->setDefined('bar');
+        $resolver->setDeprecated('foo', 'vendor/package', '1.1', $closure = function (Options $options, $value) {}, ['bar']);
 
         $debug = new OptionsResolverIntrospector($resolver);
         $this->assertSame([
             'package' => 'vendor/package',
             'version' => '1.1',
             'message' => $closure,
+            'closure_trigger_options' => ['bar'],
         ], $debug->getDeprecation('foo'));
     }
 

diff --git a/src/Symfony/Component/OptionsResolver/Tests/OptionsResolverTest.php b/src/Symfony/Component/OptionsResolver/Tests/OptionsResolverTest.php
@@ -16,6 +16,7 @@
 use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 use Symfony\Component\OptionsResolver\Debug\OptionsResolverIntrospector;
 use Symfony\Component\OptionsResolver\Exception\AccessException;
+use Symfony\Component\OptionsResolver\Exception\InvalidArgumentException;
 use Symfony\Component\OptionsResolver\Exception\InvalidOptionsException;
 use Symfony\Component\OptionsResolver\Exception\UndefinedOptionsException;
 use Symfony\Component\OptionsResolver\Options;
@@ -750,6 +751,94 @@ function (OptionsResolver $resolver) {
             null,
             0,
         ];
+
+        yield 'The message closure is executed if the deprecated option is not given but one of its closure trigger options is' => [
+            static function (OptionsResolver $resolver): void {
+                $resolver
+                    ->setDefaults([
+                        'foo' => true,
+                        'bar' => null,
+                    ])
+                    ->setDeprecated('foo', 'vendor/package', '1.1', static function (): string {
+                        return 'Writing a test is not deprecated.';
+                    }, [
+                        'bar',
+                    ]);
+            },
+            [
+                'bar' => 'bar value',
+            ],
+            [
+                'type' => \E_USER_DEPRECATED,
+                'message' => 'Since vendor/package 1.1: Writing a test is not deprecated.',
+            ],
+            1,
+        ];
+
+        yield 'The message closure is executed if the deprecated option is given as well as one of its closure trigger options' => [
+            static function (OptionsResolver $resolver): void {
+                $resolver
+                    ->setDefaults([
+                        'foo' => true,
+                        'bar' => null,
+                    ])
+                    ->setDeprecated('foo', 'vendor/package', '1.1', static function (): string {
+                        return 'Writing a test is not deprecated.';
+                    }, [
+                        'bar',
+                    ]);
+            },
+            [
+                'foo' => false,
+                'bar' => 'bar value',
+            ],
+            [
+                'type' => \E_USER_DEPRECATED,
+                'message' => 'Since vendor/package 1.1: Writing a test is not deprecated.',
+            ],
+            1,
+        ];
+
+        yield 'The message closure is not executed if the deprecated option is not given and none of its closure trigger options are' => [
+            static function (OptionsResolver $resolver): void {
+                $resolver
+                    ->setDefaults([
+                        'foo' => true,
+                        'bar' => null,
+                    ])
+                    ->setDeprecated('foo', 'vendor/package', '1.1', static function (): string {
+                        return 'Writing a test is not deprecated.';
+                    }, [
+                        'bar',
+                    ]);
+            },
+            [],
+            null,
+            0,
+        ];
+
+        yield 'The message closure is executed if the deprecated option is given but none of its closure trigger options are' => [
+            static function (OptionsResolver $resolver): void {
+                $resolver
+                    ->setDefaults([
+                        'foo' => true,
+                        'bar' => null,
+                    ])
+                    ->setDeprecated('foo', 'vendor/package', '1.1', static function (): string {
+                        return 'Writing a test is not deprecated.';
+                    }, [
+                        'bar',
+                    ]);
+            },
+            [
+                'foo' => false,
+            ],
+            [
+                'type' => \E_USER_DEPRECATED,
+                'message' => 'Since vendor/package 1.1: Writing a test is not deprecated.',
+            ],
+            1,
+        ];
     }
 
     public function testSetAllowedTypesFailsIfUnknownOption()
@@ -2498,4 +2587,57 @@ public function testSetDeprecatedWithoutPackageAndVersion()
             ->setDeprecated('foo')
         ;
     }
+
+    public function testSetDeprecatedFailsWithInvalidClosureTriggerOptionsType()
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Invalid type for the $closureTriggerOptions argument, expected an array of strings, but got "string".');
+
+        $this->resolver
+            ->setDefined('foo')
+            ->setDeprecated('foo', 'foo/bar', '2.9', static function (): string {
+                return '';
+            }, 'ccc');
+    }
+
+    public function testSetDeprecatedFailsWithClosureTriggerOptionsButStringMessage()
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('The $closureTriggerOptions argument must only be given when the message is a \Closure.');
+
+        $this->resolver
+            ->setDefined('foo')
+            ->setDeprecated('foo', 'foo/bar', '2.9', 'Writing a test is not deprecated.', [
+                'ccc',
+            ]);
+    }
+
+    public function testSetDeprecatedFailsWithUnknownClosureTriggerOption()
+    {
+        $this->expectException(UndefinedOptionsException::class);
+        $this->expectExceptionMessage('The option "ccc" does not exist, defined options are: "foo", "bar".');
+
+        $this->resolver
+            ->setDefined('foo')
+            ->setDefined('bar')
+            ->setDeprecated('foo', 'foo/bar', '2.9', static function (): string {
+                return '';
+            }, [
+                'ccc',
+            ]);
+    }
+
+    public function testSetDeprecatedFailsWithDeprecatedOptionInClosureTriggerOption()
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('The $closureTriggerOptions argument must not contain the deprecated option.');
+
+        $this->resolver
+            ->setDefined('foo')
+            ->setDeprecated('foo', 'foo/bar', '2.9', static function (): string {
+                return '';
+            }, [
+                'foo',
+            ]);
+    }
 }