feature symfony#16709 [Bridge\PhpUnit] Display the stack trace of a deprecation on-demand (nicolas-grekas)

This PR was merged into the 2.8 branch.

Discussion
----------

[Bridge\PhpUnit] Display the stack trace of a deprecation on-demand

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

This PR has been essential into making symfony#16708, and I think everyone working on a 3.0 migration will need this.

Example:

```
$ SYMFONY_DEPRECATIONS_HELPER=/FormExtensionBootstrap3LayoutTest/ ./phpunit src/Symfony/Bridge/Twig/
PHPUnit 4.8.18 by Sebastian Bergmann and contributors.

Testing src/Symfony/Bridge/Twig/
................................................
Remaining deprecation triggered by Symfony\Bridge\Twig\Tests\Extension\FormExtensionBootstrap3LayoutTest::testSingleChoiceGrouped:
The value "false" for the "choices_as_values" option is deprecated since version 2.8 and will not be supported anymore in 3.0. Set this option to "true" and flip the contents of the "choices" option instead.
Stack trace:
#0 src/Symfony/Component/Form/Extension/Core/Type/ChoiceType.php(286): trigger_error()
#1 src/Symfony/Component/OptionsResolver/OptionsResolver.php(962): Symfony\Component\Form\Extension\Core\Type\ChoiceType->Symfony\Component\Form\Extension\Core\Type\{closure}()
#2 src/Symfony/Component/Form/Extension/Core/Type/ChoiceType.php(277): Symfony\Component\OptionsResolver\OptionsResolver->offsetGet()
#3 src/Symfony/Component/OptionsResolver/OptionsResolver.php(962): Symfony\Component\Form\Extension\Core\Type\ChoiceType->Symfony\Component\Form\Extension\Core\Type\{closure}()
symfony#4 src/Symfony/Component/OptionsResolver/OptionsResolver.php(791): Symfony\Component\OptionsResolver\OptionsResolver->offsetGet()
symfony#5 src/Symfony/Component/Form/ResolvedFormType.php(156): Symfony\Component\OptionsResolver\OptionsResolver->resolve()
symfony#6 src/Symfony/Component/Form/FormFactory.php(119): Symfony\Component\Form\ResolvedFormType->createBuilder()
symfony#7 src/Symfony/Component/Form/FormFactory.php(48): Symfony\Component\Form\FormFactory->createNamedBuilder()
symfony#8 src/Symfony/Component/Form/Tests/AbstractBootstrap3LayoutTest.php(540): Symfony\Component\Form\FormFactory->createNamed()
symfony#9 [internal function]: Symfony\Component\Form\Tests\AbstractBootstrap3LayoutTest->testSingleChoiceGrouped()
symfony#10 {main}
KO src/Symfony/Bridge/Twig/
```

Commits
-------

5a88fb6 [Bridge\PhpUnit] Display the stack trace of a deprecation on-demand

Author: nicolas-grekas

src/Symfony/Bridge/PhpUnit/DeprecationErrorHandler.php

@@ -47,16 +47,37 @@ public static function register($mode = false)
                 // No-op
             }
 
-            if (0 !== error_reporting()) {
-                $group = 'unsilenced';
-                $ref = &$deprecations[$group][$msg]['count'];
-                ++$ref;
-            } elseif (isset($trace[$i]['object']) || isset($trace[$i]['class'])) {
+            if (isset($trace[$i]['object']) || isset($trace[$i]['class'])) {
                 $class = isset($trace[$i]['object']) ? get_class($trace[$i]['object']) : $trace[$i]['class'];
                 $method = $trace[$i]['function'];
 
-                $group = 0 === strpos($method, 'testLegacy') || 0 === strpos($method, 'provideLegacy') || 0 === strpos($method, 'getLegacy') || strpos($class, '\Legacy') || in_array('legacy', \PHPUnit_Util_Test::getGroups($class, $method), true) ? 'legacy' : 'remaining';
+                if (0 !== error_reporting()) {
+                    $group = 'unsilenced';
+                } elseif (0 === strpos($method, 'testLegacy')
+                    || 0 === strpos($method, 'provideLegacy')
+                    || 0 === strpos($method, 'getLegacy')
+                    || strpos($class, '\Legacy')
+                    || in_array('legacy', \PHPUnit_Util_Test::getGroups($class, $method), true)
+                ) {
+                    $group = 'legacy';
+                } else {
+                    $group = 'remaining';
+                }
+
+                if (isset($mode[0]) && '/' === $mode[0] && preg_match($mode, $class.'::'.$method)) {
+                    $e = new \Exception($msg);
+                    $r = new \ReflectionProperty($e, 'trace');
+                    $r->setAccessible(true);
+                    $r->setValue($e, array_slice($trace, 1, $i));
 
+                    echo "\n".ucfirst($group).' deprecation triggered by '.$class.'::'.$method.':';
+                    echo "\n".$msg;
+                    echo "\nStack trace:";
+                    echo "\n".str_replace(' '.getcwd().DIRECTORY_SEPARATOR, ' ', $e->getTraceAsString());
+                    echo "\n";
+
+                    exit(1);
+                }
                 if ('legacy' !== $group && 'weak' !== $mode) {
                     $ref = &$deprecations[$group][$msg]['count'];
                     ++$ref;
@@ -78,7 +99,7 @@ public static function register($mode = false)
                 restore_error_handler();
                 self::register($mode);
             }
-        } else {
+        } elseif (!isset($mode[0]) || '/' !== $mode[0]) {
             self::$isRegistered = true;
             if (self::hasColorSupport()) {
                 $colorize = function ($str, $red) {

src/Symfony/Bridge/PhpUnit/README.md

@@ -8,7 +8,8 @@ It comes with the following features:
  * disable the garbage collector;
  * enforce a consistent `C` locale;
  * auto-register `class_exists` to load Doctrine annotations;
- * print a user deprecation notices summary at the end of the test suite.
+ * print a user deprecation notices summary at the end of the test suite;
+ * display the stack trace of a deprecation on-demand.
 
 By default any non-legacy-tagged or any non-@-silenced deprecation notices will
 make tests fail.
@@ -51,3 +52,9 @@ You have to decide either to:
  * update your code to not use deprecated interfaces anymore, thus gaining better
    forward compatibility;
  * or move them to the **Legacy** section (by using one of the above way).
+
+In you need to inspect the stack trace of a particular deprecation triggered by
+one of your unit tests, you can set the `SYMFONY_DEPRECATIONS_HELPER` env var to
+a regexp that matches this test case's `class::method` name. For example,
+`SYMFONY_DEPRECATIONS_HELPER=/^MyTest::testMethod$/ phpunit` will stop your test
+suite once a deprecation is triggered by the `MyTest::testMethod` test.

src/Symfony/Component/Form/ChoiceList/ArrayKeyChoiceList.php

@@ -41,6 +41,8 @@
  * ```
  *
  * @author Bernhard Schussek <[email protected]>
+ *
+ * @deprecated since version 2.8, to be removed in 3.0. Use ArrayChoiceList instead.
  */
 class ArrayKeyChoiceList extends ArrayChoiceList
 {