Skip to content

Commit

Permalink
Merge pull request #714 from driehle/feature/custom-type-docs
Browse files Browse the repository at this point in the history 
Updated docs in regard of custom types and type comments
  • Loading branch information
@driehle
driehle authored Feb 14, 2022
2 parents 43b8e32 + 3438103 commit 2edb480
Show file tree
Hide file tree
Showing 3 changed files with 40 additions and 62 deletions.
6 changes: 3 additions & 3 deletions .github/workflows/continuous-integration.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ jobs:
- "8.1"
dbal-version:
- "2.13.0"
- "3.1.0"
- "3.3.0"
dependencies:
- "highest"
optional-dependencies:
Expand All @@ -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

Expand Down
92 changes: 33 additions & 59 deletions docs/en/configuration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
-----------------

Expand All @@ -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,
],
],
],
Expand Down Expand Up @@ -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' => [
Expand Down Expand Up @@ -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',
],
Expand Down Expand Up @@ -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>`__
Expand All @@ -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>`__
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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.
4 changes: 4 additions & 0 deletions src/Options/DBALConnection.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down

0 comments on commit 2edb480

Please sign in to comment.