feat: update Doctrine documentation with PHP configuration examples

vinceAmstoutz · vinceAmstoutz · commit 4aa78dc68bb8 · 2025-06-12T09:56:09.000+02:00
The commit introduces PHP configuration examples in the 'Doctrine' section for methods like connection(), dbal(), etc., along with the existing YAML examples. This is done to provide illustrative examples to users who prefer PHP configuration over YAML, and to ensure the document is consistent with Symfony's new practice of featuring both YAML and PHP particulars.

# Conflicts:
#	reference/configuration/doctrine.rst
diff --git a/reference/configuration/doctrine.rst b/reference/configuration/doctrine.rst
@@ -100,6 +100,36 @@ The following block shows all possible configuration keys:
             </doctrine:config>
         </container>
 
+    .. code-block:: php
+
+        use Symfony\Config\DoctrineConfig;
+
+        return static function (DoctrineConfig $doctrine): void {
+            $dbal = $doctrine->dbal();
+
+            $dbal = $dbal
+                ->connection('default')
+                ->dbname('database')
+                ->host('localhost')
+                ->port(1234)
+                ->user('user')
+                ->password('secret')
+                ->driver('pdo_mysql')
+                ->url('mysql://db_user:db_password@127.0.0.1:3306/db_name') // if the url option is specified, it will override the above config
+                ->driverClass(App\DBAL\MyDatabaseDriver::class) // the DBAL driverClass option
+                ->option('foo', 'bar') // the DBAL driverOptions option
+                ->path('%kernel.project_dir%/var/data/data.sqlite')
+                ->memory(true)
+                ->unixSocket('/tmp/mysql.sock')
+                ->wrapperClass(App\DBAL\MyConnectionWrapper::class) // the DBAL wrapperClass option
+                ->charset('utf8mb4')
+                ->logging('%kernel.debug%')
+                ->platformService(App\DBAL\MyDatabasePlatformService::class)
+                ->serverVersion('8.0.37')
+                ->mappingType('enum', 'string')
+                ->type('custom', App\DBAL\MyCustomType::class);
+        };
+
 .. note::
 
     The ``server_version`` option was added in Doctrine DBAL 2.5, which
@@ -125,7 +155,9 @@ The following block shows all possible configuration keys:
 If you want to configure multiple connections in YAML, put them under the
 ``connections`` key and give them a unique name:
 
-.. code-block:: yaml
+.. configuration-block::
+
+    .. code-block:: yaml
 
     doctrine:
         dbal:
@@ -144,6 +176,29 @@ If you want to configure multiple connections in YAML, put them under the
                     host:             localhost
                     server_version:   '8.2.0'
 
+    .. code-block:: php
+
+        use Symfony\Config\DoctrineConfig;
+
+        return static function (DoctrineConfig $doctrine): void {
+            $dbal = $doctrine->dbal();
+            $dbal->defaultConnection('default');
+
+            $dbal->connection('default')
+                ->dbname('Symfony')
+                ->user('root')
+                ->password('null')
+                ->host('localhost')
+                ->serverVersion('8.0.37');
+
+            $dbal->connection('customer')
+                ->dbname('customer')
+                ->user('root')
+                ->password('null')
+                ->host('localhost')
+                ->serverVersion('8.2.0');
+        };
+
 The ``database_connection`` service always refers to the *default* connection,
 which is the first one defined or the one configured via the
 ``default_connection`` parameter.
@@ -172,7 +227,9 @@ Doctrine ORM Configuration
 This following configuration example shows all the configuration defaults
 that the ORM resolves to:
 
-.. code-block:: yaml
+.. configuration-block::
+
+    .. code-block:: yaml
 
     doctrine:
         orm:
@@ -187,6 +244,32 @@ that the ORM resolves to:
             result_cache_driver: array
             naming_strategy: doctrine.orm.naming_strategy.default
 
+    .. code-block:: php
+
+        use Symfony\Config\DoctrineConfig;
+
+        return static function (DoctrineConfig $doctrine): void {
+            $orm = $doctrine->orm();
+
+            $orm
+                ->entityManager('default')
+                ->connection('default')
+                ->autoMapping(true)
+                ->metadataCacheDriver()
+                    ->type('array')
+                ->queryCacheDriver()
+                    ->type('array')
+                ->resultCacheDriver()
+                    ->type('array')
+                ->namingStrategy('doctrine.orm.naming_strategy.default');
+
+            $orm
+                ->autoGenerateProxyClasses(false) // the standard distribution overrides this to be true in debug, false otherwise
+                ->proxyNamespace('Proxies')
+                ->proxyDir('%kernel.cache_dir%/doctrine/orm/Proxies')
+                ->defaultEntityManager('default');
+        };
+
 There are lots of other configuration options that you can use to overwrite
 certain classes, but those are for very advanced use-cases only.
 
@@ -230,35 +313,70 @@ Caching Drivers
 Use any of the existing :doc:`Symfony Cache </cache>` pools or define new pools
 to cache each of Doctrine ORM elements (queries, results, etc.):
 
-.. code-block:: yaml
+.. configuration-block::
 
-    # config/packages/prod/doctrine.yaml
-    framework:
-        cache:
-            pools:
-                doctrine.result_cache_pool:
-                    adapter: cache.app
-                doctrine.system_cache_pool:
-                    adapter: cache.system
+    .. code-block:: yaml
 
-    doctrine:
-        orm:
-            # ...
-            metadata_cache_driver:
-                type: pool
-                pool: doctrine.system_cache_pool
-            query_cache_driver:
-                type: pool
-                pool: doctrine.system_cache_pool
-            result_cache_driver:
-                type: pool
-                pool: doctrine.result_cache_pool
+        # config/packages/prod/doctrine.yaml
+        framework:
+            cache:
+                pools:
+                    doctrine.result_cache_pool:
+                        adapter: cache.app
+                    doctrine.system_cache_pool:
+                        adapter: cache.system
 
-            # in addition to Symfony Cache pools, you can also use the
-            # 'type: service' option to use any service as the cache
-            query_cache_driver:
-                type: service
-                id: App\ORM\MyCacheService
+        doctrine:
+            orm:
+                # ...
+                metadata_cache_driver:
+                    type: pool
+                    pool: doctrine.system_cache_pool
+                query_cache_driver:
+                    type: pool
+                    pool: doctrine.system_cache_pool
+                result_cache_driver:
+                    type: pool
+                    pool: doctrine.result_cache_pool
+
+                # in addition to Symfony Cache pools, you can also use the
+                # 'type: service' option to use any service as the cache
+                query_cache_driver:
+                    type: service
+                    id: App\ORM\MyCacheService
+
+    .. code-block:: php
+
+        use Symfony\Config\DoctrineConfig;
+        use Symfony\Config\FrameworkConfig;w
+
+        return static function (FrameworkConfig $framework, DoctrineConfig $doctrine): void {
+            $framework
+                ->cache()
+                    ->pool('doctrine.result_cache_pool')
+                        ->adapters('cache.app')
+                    ->pool('doctrine.system_cache_pool')
+                        ->adapters('cache.sytsem');
+
+            $doctrine->orm()
+                // ...
+                ->entityManager('default')
+                ->metadataCacheDriver()
+                    ->type('pool')
+                    ->pool('doctrine.system_cache_pool')
+                ->queryCacheDriver()
+                    ->type('pool')
+                    ->pool('doctrine.system_cache_pool')
+                ->resultCacheDriver()
+                    ->type('pool')
+                    ->pool('doctrine.result_cache_pool')
+
+                // in addition to Symfony Cache pools, you can also use the
+                // 'type: service' option to use any service as the cache
+                ->queryCacheDriver()
+                    ->type('service')
+                    ->id(App\ORM\MyCacheService::class);
+        };
 
 Mapping Configuration
 ~~~~~~~~~~~~~~~~~~~~~
