feature #20493 [Debug] Trigger deprecation on @final annotation in DebugClassLoader - prepare making some classes final (GuilhemN)

This PR was merged into the 3.3-dev branch.

Discussion
----------

[Debug] Trigger deprecation on `@final` annotation in DebugClassLoader - prepare making some classes final

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets | follows https://github.com/symfony/symfony/pull/19734
| License       | MIT
| Doc PR        |  |

BC promises become quickly huge but making classes `final` can limit these promises.
At the same time, many classes of the symfony codebase are not meant to be extended and could be  `final`; that's the goal of this PR: prepare making them final in 4.0 by triggering deprecations in their constructor:
```php
public function __construct()
{
    if (__CLASS__ !== get_class($this)) {
        @trigger_error(sprintf('Extending %s is deprecated since 3.3 and won\'t be supported in 4.0 as it will be final.', __CLASS__), E_USER_DEPRECATED);
    }
}
```

I updated two classes for now but we can do much more if you like it.

Commits
-------

c2ff111986 [Debug] Trigger deprecation on `@final` annotation in DebugClassLoader

src/Symfony/Component/Debug/DebugClassLoader.php

@@ -27,6 +27,7 @@ class DebugClassLoader
     private $classLoader;
     private $isFinder;
     private static $caseCheck;
+    private static $final = array();
     private static $deprecated = array();
     private static $php7Reserved = array('int', 'float', 'bool', 'string', 'true', 'false', 'null');
     private static $darwinCache = array('/' => array('/', array()));
@@ -163,11 +164,21 @@ class DebugClassLoader
                 throw new \RuntimeException(sprintf('Case mismatch between loaded and declared class names: %s vs %s', $class, $name));
             }
 
+            if (preg_match('#\n \* @final(?:( .+?)\.?)?\r?\n \*(?: @|/$)#s', $refl->getDocComment(), $notice)) {
+                self::$final[$name] = isset($notice[1]) ? preg_replace('#\s*\r?\n \* +#', ' ', $notice[1]) : '';
+            }
+
+            $parent = get_parent_class($class);
+            if ($parent && isset(self::$final[$parent])) {
+                @trigger_error(sprintf('The %s class is considered final%s. It may change without further notice as of its next major version. You should not extend it from %s.', $parent, self::$final[$parent], $name), E_USER_DEPRECATED);
+            }
+
             if (in_array(strtolower($refl->getShortName()), self::$php7Reserved)) {
                 @trigger_error(sprintf('%s uses a reserved class name (%s) that will break on PHP 7 and higher', $name, $refl->getShortName()), E_USER_DEPRECATED);
             } elseif (preg_match('#\n \* @deprecated (.*?)\r?\n \*(?: @|/$)#s', $refl->getDocComment(), $notice)) {
                 self::$deprecated[$name] = preg_replace('#\s*\r?\n \* +#', ' ', $notice[1]);
             } else {
+                // Don't trigger deprecations for classes in the same vendor
                 if (2 > $len = 1 + (strpos($name, '\\', 1 + strpos($name, '\\')) ?: strpos($name, '_'))) {
                     $len = 0;
                     $ns = '';
@@ -181,7 +192,6 @@ class DebugClassLoader
                             break;
                     }
                 }
-                $parent = get_parent_class($class);
 
                 if (!$parent || strncmp($ns, $parent, $len)) {
                     if ($parent && isset(self::$deprecated[$parent]) && strncmp($ns, $parent, $len)) {

src/Symfony/Component/Debug/Tests/DebugClassLoaderTest.php

@@ -267,6 +267,28 @@ class DebugClassLoaderTest extends \PHPUnit_Framework_TestCase
 
         $this->assertSame($xError, $lastError);
     }
+
+    public function testExtendedFinalClass()
+    {
+        set_error_handler(function () { return false; });
+        $e = error_reporting(0);
+        trigger_error('', E_USER_NOTICE);
+
+        class_exists('Test\\'.__NAMESPACE__.'\\ExtendsFinalClass', true);
+
+        error_reporting($e);
+        restore_error_handler();
+
+        $lastError = error_get_last();
+        unset($lastError['file'], $lastError['line']);
+
+        $xError = array(
+            'type' => E_USER_DEPRECATED,
+            'message' => 'The Symfony\Component\Debug\Tests\Fixtures\FinalClass class is considered final since version 3.3. It may change without further notice as of its next major version. You should not extend it from Test\Symfony\Component\Debug\Tests\ExtendsFinalClass.',
+        );
+
+        $this->assertSame($xError, $lastError);
+    }
 }
 
 class ClassLoader
@@ -300,6 +322,8 @@ class ClassLoader
             return $fixtureDir.'notPsr0Bis.php';
         } elseif (__NAMESPACE__.'\Fixtures\DeprecatedInterface' === $class) {
             return $fixtureDir.'DeprecatedInterface.php';
+        } elseif (__NAMESPACE__.'\Fixtures\FinalClass' === $class) {
+            return $fixtureDir.'FinalClass.php';
         } elseif ('Symfony\Bridge\Debug\Tests\Fixtures\ExtendsDeprecatedParent' === $class) {
             eval('namespace Symfony\Bridge\Debug\Tests\Fixtures; class ExtendsDeprecatedParent extends \\'.__NAMESPACE__.'\Fixtures\DeprecatedClass {}');
         } elseif ('Test\\'.__NAMESPACE__.'\DeprecatedParentClass' === $class) {
@@ -310,6 +334,8 @@ class ClassLoader
             eval('namespace Test\\'.__NAMESPACE__.'; class NonDeprecatedInterfaceClass implements \\'.__NAMESPACE__.'\Fixtures\NonDeprecatedInterface {}');
         } elseif ('Test\\'.__NAMESPACE__.'\Float' === $class) {
             eval('namespace Test\\'.__NAMESPACE__.'; class Float {}');
+        } elseif ('Test\\'.__NAMESPACE__.'\ExtendsFinalClass' === $class) {
+            eval('namespace Test\\'.__NAMESPACE__.'; class ExtendsFinalClass extends \\'.__NAMESPACE__.'\Fixtures\FinalClass {}');
         }
     }
 }

src/Symfony/Component/Debug/Tests/Fixtures/FinalClass.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Symfony\Component\Debug\Tests\Fixtures;
+
+/**
+ * @final since version 3.3.
+ */
+class FinalClass
+{
+}

src/Symfony/Component/Serializer/Encoder/ChainDecoder.php

@@ -19,6 +19,8 @@ use Symfony\Component\Serializer\Exception\RuntimeException;
  * @author Jordi Boggiano <j.boggiano@seld.be>
  * @author Johannes M. Schmitt <schmittjoh@gmail.com>
  * @author Lukas Kahwe Smith <smith@pooteeweet.org>
+ *
+ * @final since version 3.3.
  */
 class ChainDecoder implements DecoderInterface
 {

src/Symfony/Component/Serializer/Encoder/ChainEncoder.php

@@ -19,6 +19,8 @@ use Symfony\Component\Serializer\Exception\RuntimeException;
  * @author Jordi Boggiano <j.boggiano@seld.be>
  * @author Johannes M. Schmitt <schmittjoh@gmail.com>
  * @author Lukas Kahwe Smith <smith@pooteeweet.org>
+ *
+ * @final since version 3.3.
  */
 class ChainEncoder implements EncoderInterface
 {