[GH-9277] remove deprecated PHPDriver (#9308)

* Remove deprecated PHPDriver mapping driver, use StaticPHPDriver instead.

* Update docs

* Housekeeping

* Update UPGRADE.md

UPGRADE.md

@@ -1,5 +1,10 @@
 # Upgrade to 3.0
 
+## BC Break: Remove `Doctrine\ORM\Mapping\Driver\PHPDriver`
+
+Use `StaticPHPDriver` instead when you want to programmatically configure
+entity metadata.
+
 ## BC BREAK: Remove `Doctrine\ORM\EntityManagerInterface#transactional()`
 
 This method has been replaced by `Doctrine\ORM\EntityManagerInterface#wrapInTransaction()`.

docs/en/reference/php-mapping.rst

@@ -1,92 +1,20 @@
 PHP Mapping
 ===========
 
-Doctrine ORM also allows you to provide the ORM metadata in the form
-of plain PHP code using the ``ClassMetadata`` API. You can write
-the code in PHP files or inside of a static function named
-``loadMetadata($class)`` on the entity class itself.
-
-PHP Files
----------
-
-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``:
-
-.. code-block:: php
-
-    <?php
-    $driver = new PHPDriver('/path/to/php/mapping/files');
-    $em->getConfiguration()->setMetadataDriverImpl($driver);
-
-Now imagine we had an entity named ``Entities\User`` and we wanted
-to write a mapping file for it using the above configured
-``PHPDriver`` instance:
-
-.. code-block:: php
-
-    <?php
-    namespace Entities;
-
-    class User
-    {
-        private $id;
-        private $username;
-    }
-
-To write the mapping information you just need to create a file
-named ``Entities.User.php`` inside of the
-``/path/to/php/mapping/files`` folder:
-
-.. code-block:: php
-
-    <?php
-    // /path/to/php/mapping/files/Entities.User.php
-
-    $metadata->mapField(array(
-       'id' => true,
-       'fieldName' => 'id',
-       'type' => 'integer'
-    ));
-
-    $metadata->mapField(array(
-       'fieldName' => 'username',
-       'type' => 'string',
-       'options' => array(
-           'fixed' => true,
-           'comment' => "User's login name"
-       )
-    ));
-
-    $metadata->mapField(array(
-       'fieldName' => 'login_count',
-       'type' => 'integer',
-       'nullable' => false,
-       'options' => array(
-           'unsigned' => true,
-           'default' => 0
-       )
-    ));
-
-Now we can easily retrieve the populated ``ClassMetadata`` instance
-where the ``PHPDriver`` includes the file and the
-``ClassMetadataFactory`` caches it for later retrieval:
-
-.. code-block:: php
-
-    <?php
-    $class = $em->getClassMetadata('Entities\User');
-    // or
-    $class = $em->getMetadataFactory()->getMetadataFor('Entities\User');
+Doctrine ORM also allows you to provide the ORM metadata in the form of plain
+PHP code using the ``ClassMetadata`` API. You can write the code in inside of a
+static function named ``loadMetadata($class)`` on the entity class itself.
 
 Static Function
 ---------------
 
-In addition to the PHP files you can also specify your mapping
-information inside of a static function defined on the entity class
-itself. This is useful for cases where you want to keep your entity
-and mapping information together but don't want to use annotations.
-For this you just need to use the ``StaticPHPDriver``:
+In addition to other drivers using configuration languages you can also
+programatically specify your mapping information inside of a static function
+defined on the entity class itself.
+
+This is useful for cases where you want to keep your entity and mapping
+information together but don't want to use annotations.  For this you just need
+to use the ``StaticPHPDriver``:
 
 .. code-block:: php
 

tests/Doctrine/Tests/Models/Cache/City.php

@@ -138,6 +138,68 @@ public function getAttractions(): Collection
 
     public static function loadMetadata(ClassMetadataInfo $metadata): void
     {
-        include __DIR__ . '/../../ORM/Mapping/php/Doctrine.Tests.Models.Cache.City.php';
+        $metadata->setInheritanceType(ClassMetadataInfo::INHERITANCE_TYPE_NONE);
+        $metadata->setPrimaryTable(['name' => 'cache_city']);
+        $metadata->setIdGeneratorType(ClassMetadataInfo::GENERATOR_TYPE_IDENTITY);
+        $metadata->setChangeTrackingPolicy(ClassMetadataInfo::CHANGETRACKING_DEFERRED_IMPLICIT);
+
+        $metadata->enableCache(
+            [
+                'usage' => ClassMetadataInfo::CACHE_USAGE_READ_ONLY,
+            ]
+        );
+
+        $metadata->mapField(
+            [
+                'fieldName' => 'id',
+                'type' => 'integer',
+                'id' => true,
+            ]
+        );
+
+        $metadata->mapField(
+            [
+                'fieldName' => 'name',
+                'type' => 'string',
+            ]
+        );
+
+        $metadata->mapOneToOne(
+            [
+                'fieldName'      => 'state',
+                'targetEntity'   => State::class,
+                'inversedBy'     => 'cities',
+                'joinColumns'    =>
+                    [
+                        [
+                            'name' => 'state_id',
+                            'referencedColumnName' => 'id',
+                        ],
+                    ],
+            ]
+        );
+        $metadata->enableAssociationCache('state', [
+            'usage' => ClassMetadataInfo::CACHE_USAGE_READ_ONLY,
+        ]);
+
+        $metadata->mapManyToMany(
+            [
+                'fieldName' => 'travels',
+                'targetEntity' => Travel::class,
+                'mappedBy' => 'visitedCities',
+            ]
+        );
+
+        $metadata->mapOneToMany(
+            [
+                'fieldName' => 'attractions',
+                'targetEntity' => Attraction::class,
+                'mappedBy' => 'city',
+                'orderBy' => ['name' => 'ASC'],
+            ]
+        );
+        $metadata->enableAssociationCache('attractions', [
+            'usage' => ClassMetadataInfo::CACHE_USAGE_READ_ONLY,
+        ]);
     }
 }