[Debug] Trigger a deprecation for new parameters not defined in sub classes

GuilhemN · nicolas-grekas · commit c8fdf03086ed · 2018-09-09T11:30:40.000+02:00
diff --git a/src/Symfony/Component/Debug/DebugClassLoader.php b/src/Symfony/Component/Debug/DebugClassLoader.php
@@ -11,6 +11,8 @@
 
 namespace Symfony\Component\Debug;
 
+use PHPUnit\Framework\MockObject\Matcher\StatelessInvocation;
+
 /**
  * Autoloader checking if the class is really defined in the file found.
  *
@@ -34,6 +36,7 @@ class DebugClassLoader
     private static $deprecated = array();
     private static $internal = array();
     private static $internalMethods = array();
+    private static $annotatedParameters = array();
     private static $darwinCache = array('/' => array('/', array()));
 
     public function __construct(callable $classLoader)
@@ -229,11 +232,12 @@ private function checkClass($class, $file = null)
                 }
             }
 
-            // Inherit @final and @internal annotations for methods
+            // Inherit @final, @internal and @param annotations for methods
             self::$finalMethods[$name] = array();
             self::$internalMethods[$name] = array();
+            self::$annotatedParameters[$name] = array();
             foreach ($parentAndTraits as $use) {
-                foreach (array('finalMethods', 'internalMethods') as $property) {
+                foreach (array('finalMethods', 'internalMethods', 'annotatedParameters') as $property) {
                     if (isset(self::${$property}[$use])) {
                         self::${$property}[$name] = self::${$property}[$name] ? self::${$property}[$use] + self::${$property}[$name] : self::${$property}[$use];
                     }
@@ -258,20 +262,50 @@ private function checkClass($class, $file = null)
                     }
                 }
 
-                // Method from a trait
-                if ($method->getFilename() !== $refl->getFileName()) {
-                    continue;
+                if (isset(self::$annotatedParameters[$name][$method->name])) {
+                    $definedParameters = array();
+                    foreach ($method->getParameters() as $parameter) {
+                        $definedParameters[$parameter->name] = true;
+                    }
+
+                    foreach (array_diff_key(self::$annotatedParameters[$name][$method->name], $definedParameters) as $deprecation) {
+                        @trigger_error(sprintf($deprecation, $name), E_USER_DEPRECATED);
+                    }
                 }
 
                 // Detect method annotations
                 if (false === $doc = $method->getDocComment()) {
                     continue;
                 }
 
-                foreach (array('final', 'internal') as $annotation) {
-                    if (false !== \strpos($doc, $annotation) && preg_match('#\n\s+\* @'.$annotation.'(?:( .+?)\.?)?\r?\n\s+\*(?: @|/$)#s', $doc, $notice)) {
-                        $message = isset($notice[1]) ? preg_replace('#\s*\r?\n \* +#', ' ', $notice[1]) : '';
-                        self::${$annotation.'Methods'}[$name][$method->name] = array($name, $message);
+                $finalOrInternal = false;
+
+                // Skip methods from traits
+                if ($method->getFilename() === $refl->getFileName()) {
+                    foreach (array('final', 'internal') as $annotation) {
+                        if (false !== \strpos($doc, $annotation) && preg_match('#\n\s+\* @'.$annotation.'(?:( .+?)\.?)?\r?\n\s+\*(?: @|/$)#s', $doc, $notice)) {
+                            $message = isset($notice[1]) ? preg_replace('#\s*\r?\n \* +#', ' ', $notice[1]) : '';
+                            self::${$annotation.'Methods'}[$name][$method->name] = array($name, $message);
+                            $finalOrInternal = true;
+                        }
+                    }
+                }
+
+                if ($finalOrInternal || $method->isConstructor() || false === \strpos($doc, '@param') || StatelessInvocation::class === $name) {
+                    continue;
+                }
+
+                if (!preg_match_all('#\n\s+\* @param (.*?)(?<= )\$([a-zA-Z0-9_\x7f-\xff]++)#', $doc, $matches, PREG_SET_ORDER)) {
+                    continue;
+                }
+                $definedParameters = array();
+                foreach ($method->getParameters() as $parameter) {
+                    $definedParameters[$parameter->name] = true;
+                }
+                foreach ($matches as list(, $parameterType, $parameterName)) {
+                    if (!isset($definedParameters[$parameterName])) {
+                        $parameterType = trim($parameterType);
+                        self::$annotatedParameters[$name][$method->name][$parameterName] = sprintf('The "%%s::%s()" method will require a new "%s$%s" argument in the next major version of its parent class "%s", not defining it is deprecated.', $method->name, $parameterType ? $parameterType.' ' : '', $parameterName, $method->class);
                     }
                 }
             }
diff --git a/src/Symfony/Component/Debug/Tests/DebugClassLoaderTest.php b/src/Symfony/Component/Debug/Tests/DebugClassLoaderTest.php
@@ -272,6 +272,20 @@ class_exists('Test\\'.__NAMESPACE__.'\\ExtendsInternals', true);
             'The "Symfony\Component\Debug\Tests\Fixtures\InternalTrait2::internalMethod()" method is considered internal. It may change without further notice. You should not extend it from "Test\Symfony\Component\Debug\Tests\ExtendsInternals".',
         ));
     }
+
+    public function testExtendedMethodDefinesNewParameters()
+    {
+        $deprecations = array();
+        set_error_handler(function ($type, $msg) use (&$deprecations) { $deprecations[] = $msg; });
+        $e = error_reporting(E_USER_DEPRECATED);
+
+        class_exists('Test\\'.__NAMESPACE__.'\\SubClassWithAnnotatedParameters', true);
+
+        error_reporting($e);
+        restore_error_handler();
+
+        $this->assertSame(array('The "Test\Symfony\Component\Debug\Tests\SubClassWithAnnotatedParameters::quzMethod()" method will require a new "Quz $quz" argument in the next major version of its parent class "Symfony\Component\Debug\Tests\Fixtures\ClassWithAnnotatedParameters", not defining it is deprecated.'), $deprecations);
+    }
 }
 
 class ClassLoader
@@ -325,6 +339,12 @@ public function internalMethod() { }
             }');
         } elseif ('Test\\'.__NAMESPACE__.'\ExtendsInternalsParent' === $class) {
             eval('namespace Test\\'.__NAMESPACE__.'; class ExtendsInternalsParent extends \\'.__NAMESPACE__.'\Fixtures\InternalClass implements \\'.__NAMESPACE__.'\Fixtures\InternalInterface { }');
+        } elseif ('Test\\'.__NAMESPACE__.'\SubClassWithAnnotatedParameters' === $class) {
+            eval('namespace Test\\'.__NAMESPACE__.'; class SubClassWithAnnotatedParameters extends \\'.__NAMESPACE__.'\Fixtures\ClassWithAnnotatedParameters {
+                public function fooMethod(string $foo) { }
+                public function barMethod($bar = null) { }
+                public function quzMethod() { }
+            }');
         }
     }
 }
diff --git a/src/Symfony/Component/Debug/Tests/Fixtures/ClassWithAnnotatedParameters.php b/src/Symfony/Component/Debug/Tests/Fixtures/ClassWithAnnotatedParameters.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace Symfony\Component\Debug\Tests\Fixtures;
+
+class ClassWithAnnotatedParameters
+{
+    /**
+     * @param string $foo this is a foo parameter
+     */
+    public function fooMethod(string $foo)
+    {
+    }
+
+    /**
+     * @param string $bar parameter not implemented yet
+     */
+    public function barMethod(/* string $bar = null */)
+    {
+    }
+
+    /**
+     * @param Quz $quz parameter not implemented yet
+     */
+    public function quzMethod(/* Quz $quz = null */)
+    {
+    }
+}
