[GH-9277] deprecate php driver (#9309)

* [GH-9277] Deprecate PHPDriver

* Update UPGRADE.md, fix wrong parameter

* Copy docblock to appease confused Psalm

* Talk about alternatives more

Author: beberlei

UPGRADE.md

@@ -1,5 +1,14 @@
 # Upgrade to 2.11
 
+## Deprecated: `Doctrine\ORM\Mapping\Driver\PHPDriver`
+
+Use `StaticPHPDriver` instead when you want to programmatically configure
+entity metadata.
+
+You can convert mappings with the `orm:convert-mapping` command or more simply
+in this case, `include` the metadata file from the `loadMetadata` static method
+used by the `StaticPHPDriver`.
+
 ## Deprecated: `Setup::registerAutoloadDirectory()`
 
 Use Composer's autoloader instead.

docs/en/reference/php-mapping.rst

@@ -9,6 +9,11 @@ the code in PHP files or inside of a static function named
 PHP Files
 ---------
 
+.. note::
+
+   PHPDriver is deprecated and will be removed in 3.0, use StaticPHPDriver
+   instead.
+
 If you wish to write your mapping information inside PHP files that
 are named after the entity and included to populate the metadata
 for an entity you can do so by using the ``PHPDriver``:

lib/Doctrine/ORM/Mapping/Driver/PHPDriver.php

@@ -4,13 +4,28 @@
 
 namespace Doctrine\ORM\Mapping\Driver;
 
+use Doctrine\Deprecations\Deprecation;
+use Doctrine\Persistence\Mapping\Driver\FileLocator;
 use Doctrine\Persistence\Mapping\Driver\PHPDriver as CommonPHPDriver;
 
 /**
  * {@inheritDoc}
  *
- * @deprecated this driver will be removed. Use Doctrine\Persistence\Mapping\Driver\PHPDriver instead
+ * @deprecated this driver will be removed, use StaticPHPDriver or other mapping drivers instead.
  */
 class PHPDriver extends CommonPHPDriver
 {
+    /**
+     * @param string|string[]|FileLocator $locator
+     */
+    public function __construct($locator)
+    {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/9277',
+            'PHPDriver is deprecated, use StaticPHPDriver or other mapping drivers instead.'
+        );
+
+        parent::__construct($locator);
+    }
 }