Merge pull request #714 from driehle/feature/custom-type-docs

Updated docs in regard of custom types and type comments

Author: driehle

.github/workflows/continuous-integration.yml

@@ -22,7 +22,7 @@ jobs:
           - "8.1"
         dbal-version:
           - "2.13.0"
-          - "3.1.0"
+          - "3.3.0"
         dependencies:
           - "highest"
         optional-dependencies:
@@ -34,15 +34,15 @@ jobs:
             dependencies: "lowest"
             optional-dependencies: false
           - php-version: "7.4"
-            dbal-version: "3.1.0"
+            dbal-version: "3.3.0"
             dependencies: "lowest"
             optional-dependencies: false
           - php-version: "7.4"
             dbal-version: "2.13.0"
             dependencies: "lowest"
             optional-dependencies: true
           - php-version: "7.4"
-            dbal-version: "3.1.0"
+            dbal-version: "3.3.0"
             dependencies: "lowest"
             optional-dependencies: true
 

docs/en/configuration.rst

@@ -6,41 +6,24 @@ Register a Custom DQL Function
 
 .. code:: php
 
-    namespace Db;
-
     return [
         'doctrine' => [
             'configuration' => [
                 'orm_default' => [
                     'numeric_functions' => [
-                        'ROUND' => Db\DoctrineExtensions\Query\Mysql\Round::class,
-                    ],
-                ],
-            ],
-        ],
-    ];
-
-
-Register a Type mapping
------------------------
-
-.. code:: php
-
-    return [
-        'doctrine' => [
-            'connection' => [
-                'orm_default' => [
-                    'doctrine_type_mappings' => [
-                        'enum' => 'string',
+                        'ROUND' => \My\DoctrineExtensions\Query\Mysql\Round::class,
                     ],
                 ],
             ],
         ],
     ];
 
+How to add a Custom Type
+------------------------
 
-How to add a new type
----------------------
+First, implement a new type by extending `Doctrine\DBAL\Types\Type`. An example can be found in
+the `ORM cookbook <https://www.doctrine-project.org/projects/doctrine-orm/en/current/cookbook/custom-mapping-types.html#custom-mapping-types>`__
+Then, register your type implementation with DBAL as follows:
 
 .. code:: php
 
@@ -49,48 +32,35 @@ How to add a new type
             'configuration' => [
                 'orm_default' => [
                     'types' => [
-                        'newtype' => 'Db\DBAL\Types\NewType',
+                        'newtype' => \My\Types\NewType::class,
                     ],
                 ],
             ],
         ],
     ];
 
-.. code:: php
-
-    return [
-        'doctrine' => [
-            'connection' => [
-                'orm_default' => [
-                    'doctrine_type_mappings' => [
-                        'mytype' => 'mytype',
-                    ],
-                ],
-            ],
-        ],
-    ];
+.. note::
 
+    If your type uses a database type which is already `mapped by Doctrine <https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/types.html#mapping-matrix>`__,
+    Doctrine will need a comment hint to distinguish your type from other types. In your type class, override
+    `requiresSQLCommentHint()` to return `true` to let Doctrine add a comment hint.
 
-Doctrine Type Comment
----------------------
-
-Option to set the doctrine type comment (DC2Type:myType) for custom types
+Next, you will need to register your custom type with the underlying database platform:
 
 .. code:: php
 
     return [
         'doctrine' => [
             'connection' => [
                 'orm_default' => [
-                    'doctrineCommentedTypes' => [
-                        'mytype',
+                    'doctrine_type_mappings' => [
+                        'mytype' => 'mytype',
                     ],
                 ],
             ],
         ],
     ];
 
-
 Built-in Resolver
 -----------------
 
@@ -103,8 +73,8 @@ How to Define Relationships with Abstract Classes and Interfaces (ResolveTargetE
             'entity_resolver' => [
                 'orm_default' => [
                     'resolvers' => [
-                        'Acme\\InvoiceModule\\Model\\InvoiceSubjectInterface',
-                        'Acme\\CustomerModule\\Entity\\Customer',
+                        \Acme\InvoiceModule\Model\InvoiceSubjectInterface::class,
+                        \Acme\CustomerModule\Entity\Customer::class,
                     ],
                 ],
             ],
@@ -140,7 +110,7 @@ See also `this blog article <https://blog.tomhanderson.com/2016/03/zf2-doctrine-
         'doctrine' => [
             'connection' => [
                 'orm_crawler' => [
-                    'driverClass'   => 'Doctrine\DBAL\Driver\PDO\MySql\Driver',
+                    'driverClass'   => \Doctrine\DBAL\Driver\PDO\MySql\Driver::class,
                     'eventmanager'  => 'orm_crawler',
                     'configuration' => 'orm_crawler',
                     'params'        => [
@@ -172,14 +142,14 @@ See also `this blog article <https://blog.tomhanderson.com/2016/03/zf2-doctrine-
 
             'driver' => [
                 'orm_crawler_annotation' => [
-                    'class' => 'Doctrine\ORM\Mapping\Driver\AnnotationDriver',
+                    'class' => \Doctrine\ORM\Mapping\Driver\AnnotationDriver::class,
                     'cache' => 'array',
                     'paths' => [
                         __DIR__ . '/../src/Crawler/Entity',
                     ],
                 ],
                 'orm_crawler_chain' => [
-                    'class'   => 'Doctrine\ORM\Mapping\Driver\DriverChain',
+                    'class'   => \Doctrine\ORM\Mapping\Driver\DriverChain::class,
                     'drivers' => [
                         'Crawler\Entity' =>  'orm_crawler_annotation',
                     ],
@@ -221,8 +191,8 @@ The ``DoctrineModule\ServiceFactory\AbstractDoctrineServiceFactory`` will create
 You can retrieve them from the service manager via their keys.
 
 
-How to Use Naming Strategy
---------------------------
+How to Use a Naming Strategy
+----------------------------
 
 `Official documentation 
 <https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/namingstrategy.html>`__
@@ -234,20 +204,20 @@ Laminas Configuration
     return [
         'service_manager' => [
             'invokables' => [
-                'Doctrine\ORM\Mapping\UnderscoreNamingStrategy' => 'Doctrine\ORM\Mapping\UnderscoreNamingStrategy',
+                \Doctrine\ORM\Mapping\UnderscoreNamingStrategy::class => \Doctrine\ORM\Mapping\UnderscoreNamingStrategy::class,
             ],
         ],
         'doctrine' => [
             'configuration' => [
                 'orm_default' => [
-                    'naming_strategy' => 'Doctrine\ORM\Mapping\UnderscoreNamingStrategy',
+                    'naming_strategy' => \Doctrine\ORM\Mapping\UnderscoreNamingStrategy::class,
                 ],
             ],
         ],
     ];
 
-How to Use Quote Strategy
--------------------------
+How to Use a Quote Strategy
+---------------------------
 
 `Official
 documentation <https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/basic-mapping.html#quoting-reserved-words>`__
@@ -259,20 +229,20 @@ Laminas Configuration
     return [
         'service_manager' => [
             'invokables' => [
-                'Doctrine\ORM\Mapping\AnsiQuoteStrategy' => 'Doctrine\ORM\Mapping\AnsiQuoteStrategy',
+                \Doctrine\ORM\Mapping\AnsiQuoteStrategy::class => \Doctrine\ORM\Mapping\AnsiQuoteStrategy::class,
             ],
         ],
         'doctrine' => [
             'configuration' => [
                 'orm_default' => [
-                    'quote_strategy' => 'Doctrine\ORM\Mapping\AnsiQuoteStrategy',
+                    'quote_strategy' => \Doctrine\ORM\Mapping\AnsiQuoteStrategy::class,
                 ],
             ],
         ],
     ];
 
 How to Override RunSqlCommand Creation
--------------------------
+--------------------------------------
 
 The following Laminas configuration can be used to override the creation of the
 ``Doctrine\DBAL\Tools\Console\Command\RunSqlCommand`` instance used by this
@@ -288,7 +258,7 @@ module.
         ],
     ];
 
-How to exclude tables from a schema diff
+How to Exclude Tables from a Schema Diff
 ----------------------------------------
 
 The "schema_assets_filter" option can be used to exclude certain tables from being created or deleted in a schema update:
@@ -307,3 +277,7 @@ The "schema_assets_filter" option can be used to exclude certain tables from bei
         ],
     ];
 
+.. note::
+
+    If you want your application config to be cached, you should use a callable in terms of a static
+    function (like `MyFilterClass::filter`) instead of a closure.

src/Options/DBALConnection.php

@@ -119,6 +119,8 @@ public function getDoctrineTypeMappings(): array
     }
 
     /**
+     * @deprecated 5.1.0 Deprecated in DBAL 3.3, use `Type::requiresSQLCommentTypeHint()` instead.
+     *
      * @param mixed[] $doctrineCommentedTypes
      */
     public function setDoctrineCommentedTypes(array $doctrineCommentedTypes): void
@@ -127,6 +129,8 @@ public function setDoctrineCommentedTypes(array $doctrineCommentedTypes): void
     }
 
     /**
+     * @deprecated 5.1.0 Deprecated in DBAL 3.3, use `Type::requiresSQLCommentTypeHint()` instead.
+     *
      * @return mixed[]
      */
     public function getDoctrineCommentedTypes(): array