Справочник конфигурации Doctrine (DoctrineBundle)

Дата обновления перевода 2023-01-16

Справочник конфигурации Doctrine (DoctrineBundle)

DoctrineBundle интегрирует как DBAL, так и проекты Doctrine ORM в приложения Symfony. Все эти опции конфигурируются под ключом doctrine в конфигурации вашего приложения.

        1
2
3
4
5
        # отображает значения конфигурации по умолчанию, определенные Symfony
$ php bin/console config:dump-reference doctrine

# отображает реальные значения конфигурации, используемые вашим приложением
$ php bin/console debug:config doctrine
    

Note

При использовании XML, вы должны использовать пространство имен http://symfony.com/schema/dic/doctrine, а связанная схема XSD доступна тут: https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd

Конфигурация Doctrine DBAL

DoctrineBundle поддерживает все параметры, которые принимают драйверы Doctrine по умолчанию, конвертированны в стандарты именования XML или YAML, которые внедряет Symfony. См. документацию DBAL, чтобы узнать больше. Следующий блок показывает все возможные ключи конфигурации:

YAML
XML

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
        doctrine:
    dbal:
        dbname:               database
        host:                 localhost
        port:                 1234
        user:                 user
        password:             secret
        driver:               pdo_mysql
        # если указана опция url, она переопределить конфигурацию выше
        url:                  mysql://db_user:db_password@127.0.0.1:3306/db_name
        # опция DBAL driverClass
        driver_class:         App\DBAL\MyDatabaseDriver
        # оцпия DBAL driverOptions
        options:
            foo: bar
        path:                 '%kernel.project_dir%/var/data/data.sqlite'
        memory:               true
        unix_socket:          /tmp/mysql.sock
        # опция DBAL wrapperClass
        wrapper_class:        App\DBAL\MyConnectionWrapper
        charset:              utf8mb4
        logging:              '%kernel.debug%'
        platform_service:     App\DBAL\MyDatabasePlatformService
        server_version:       '5.7'
        mapping_types:
            enum: string
        types:
            custom: App\DBAL\MyCustomType
    

Note

Опция server_version была добавлена в Doctrine DBAL 2.5, который используется DoctrineBundle 1.3. Значение этой опции должно совпадать с вашей версией сервера DB (используйте команду postgres -V или psql -V, чтобы найти вашу версию PostgreSQL, и mysql -V, чтобы получить вашу версию MySQL).

Если у вас база данных MariaDB, вы должны добавить к значению server_version префикс mariadb- (например, server_version: mariadb-10.4.14).

Всегда помещайте номер версии сервера в кавычки, чтобы анализировать его как строку, а не как число с плавающей запятой. Иначе проблемы представляения числа с плавающей запятой могут сделать так, что ваша версия будет считаться другим числом (например, 5.7 будет округлено как 5.6999999999999996447286321199499070644378662109375).

Если вы не определили эту опцию и вы ещё не создали вашу DB, то вы можете получить ошибки PDOException, так как Doctrine будет пробовать угадать версию сервера DB автоматически, а они не доступны.

Если вы хотите сконфигурировать несколько соединений в YAML, поместите их под ключом connections и дайте им уникальные имена:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        doctrine:
    dbal:
        default_connection:       default
        connections:
            default:
                dbname:           Symfony
                user:             root
                password:         null
                host:             localhost
                server_version:   5.6
            customer:
                dbname:           customer
                user:             root
                password:         null
                host:             localhost
                server_version:   5.7
    

Сервис database_connection всегда ссылатся на соединение по умолчанию, которое является первым определённым или сконфигурированным через параметр default_connection.

Каждое соединение также доступно через сервис doctrine.dbal.[name]_connection, где [name] - это имя соединения. В контроллере, вы можете получить доступ к нему напрямую, используя метод getConnection() и имя соединения:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        // src/Controller/SomeController.php
use Doctrine\Persistence\ManagerRegistry;

class SomeController
{
    public function someMethod(ManagerRegistry $doctrine)
    {
        $connection = $doctrine->getConnection('customer');
        $result = $connection->fetchAll('SELECT name FROM customer');

        // ...
    }
}
    

Конфигурация Doctrine ORM

Следующий пример конфигурации отображает все значения конфигурации по умолчанию, которые разрешает ORM:

        1
2
3
4
5
6
7
8
9
10
11
12
        doctrine:
    orm:
        auto_mapping: true
        # стандартное распределение переопределяет это как true при отладке и как false в других случаях
        auto_generate_proxy_classes: false
        proxy_namespace: Proxies
        proxy_dir: '%kernel.cache_dir%/doctrine/orm/Proxies'
        default_entity_manager: default
        metadata_cache_driver: array
        query_cache_driver: array
        result_cache_driver: array
        naming_strategy: doctrine.orm.naming_strategy.default
    

Существует множество других опций конфигурации, которые вы можете использовать для перезаписи определённых классов, но они нужны только для очень продвинутых случаев использования.

Сокращённый синтаксис конфигурации

Когда вы используете только одного менеджера сущностей, все доступные опции конфигурации могут быть размещены прямо под уровнем конфигурации doctrine.orm.

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
        doctrine:
    orm:
        # ...
        query_cache_driver:
            # ...
        metadata_cache_driver:
            # ...
        result_cache_driver:
            # ...
        connection: ~
        class_metadata_factory_name:  Doctrine\ORM\Mapping\ClassMetadataFactory
        default_repository_class:  Doctrine\ORM\EntityRepository
        auto_mapping: false
        naming_strategy: doctrine.orm.naming_strategy.default
        hydrators:
            # ...
        mappings:
            # ...
        dql:
            # ...
        filters:
            # ...
    

Эта сокращённая версия часто используется в других разделах документации. Помните, что вы не можете использовать оба синтаксиса одновременно.

Кеширование драйверов

Используйте любой из существующих пулов Symfony Cache или определите новые пулы, чтобы кешировать каждый из элементов Doctrine ORM (запросы, результаты, и др.):

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
        # config/packages/prod/doctrine.yaml
framework:
    cache:
        pools:
            doctrine.result_cache_pool:
                adapter: cache.app
            doctrine.system_cache_pool:
                adapter: cache.system

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

        # в дополнение к пулам Кеша Symfony, вы можете также использовать
        # опцию 'type: service', чтобы использовать любой сервис как кеш
        query_cache_driver:
            type: service
            id: App\ORM\MyCacheService
    

Конфигурация отображения

Ясное определение всех отображённых сущностей - это единственная нужная конфигурация для ORM и есть несколько опций конфигурации, которые вы можете контролировать. Существуют следующие опции конфигурации для отображения:

`type`

Одна из annotation (для PHP-аннотаций; это значение по умолчанию), attribute (для PHP-атрибутов), xml, yml, php или staticphp. Указывает, какой тип метаданных использует ваше отображение.

См, Драйверы метеданных Doctrine, чтобы узнать больше об этой опции.

`dir`

Абсолютный путь к отображению или файлам сущностей (в зависимости от драйвера).

`prefix`

Общий префикс пространства имён, который имеют все сущности отображения. Этот префикс не должен конфликовать с префиксами других определённых отображений, иначе некоторые из ваших сущностей не смогут быть найдены Doctrine.

`alias`

Doctrine предоставляет более простоей способ написания дополнительных имён для сущностей пространства имён, более короткие именя для использования с запросами DQL или для доступа к Хранилищу.

`is_bundle`

Эта опция по умолчанию false и считается опцией наследования. Она была полезна только в предыдущих версиях Symfony, когда рекомендовалось использовать пакеты для организации кода приложения.

Пользовательские сущности отображения в пакете

Функция Doctrine auto_mapping загружает конфигурацию аннотации из каталога Entity/ каждого пакета и ищет другие форматы (например, YAML, XML) в каталоге Resources/config/doctrine.

Если вы храните метаданные где-то ещё в вашем пакете, то вы можете определить ваше собственное отображеие, где вы скажите Doctrine где именно искать, вместе с некоторой другой конфигурацией.

Если вы используете конфигурацию auto_mapping, то вам просто надо перезаписать нужные вам конфигурации. В этом случае, важно, чтобы ключ конфигураций отображения совпадал с именем пакета.

Например, представьте, что вы решили хранить вашу конфигурацию XML для сущностей AppBundle в каталоге @AppBundle/SomeResources/config/doctrine:

YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
        doctrine:
    # ...
    orm:
        # ...
        auto_mapping: true
        mappings:
            # ...
            AppBundle:
                type: xml
                dir: SomeResources/config/doctrine
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
        <?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <doctrine:config>
        <doctrine:orm auto-mapping="true">
            <mapping name="AppBundle" dir="SomeResources/config/doctrine" type="xml"/>
        </doctrine:orm>
    </doctrine:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
        use Symfony\Config\DoctrineConfig;

return static function (DoctrineConfig $doctrine) {
    $emDefault = $doctrine->orm()->entityManager('default');

    $emDefault->autoMapping(true);
    $emDefault->mapping('AppBundle')
        ->type('xml')
        ->dir('SomeResources/config/doctrine')
    ;
};
    

Отображение сущностей вне пакета

Например, следующий код ищет классы сущности в пространстве имён Entity в каталоге src/Entity и предоставляет им дополнительное имя App (чтобы вы могли писать вещи вроде App:Post):

YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
11
12
        doctrine:
        # ...
        orm:
            # ...
            mappings:
                # ...
                SomeEntityNamespace:
                    type: annotation
                    dir: '%kernel.project_dir%/src/Entity'
                    is_bundle: false
                    prefix: App\Entity
                    alias: App
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        <?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <doctrine:config>
        <doctrine:orm>
            <mapping name="SomeEntityNamespace"
                type="annotation"
                dir="%kernel.project_dir%/src/Entity"
                is-bundle="false"
                prefix="App\Entity"
                alias="App"
            />
        </doctrine:orm>
    </doctrine:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        use Symfony\Config\DoctrineConfig;

return static function (DoctrineConfig $doctrine) {
    $emDefault = $doctrine->orm()->entityManager('default');

    $emDefault->autoMapping(true);
    $emDefault->mapping('SomeEntityNamespace')
        ->type('annotation')
        ->dir('%kernel.project_dir%/src/Entity')
        ->isBundle(false)
        ->prefix('App\Entity')
        ->alias('App')
    ;
};
    

Определение формата конфигурации отображения

Если type конфигурации пакета не установлен, то DoctrineBundle будет пытаться определить правильный формат конфигурации отображения для пакета.

DoctrineBundle будет искать файлы, совпадающие с *.orm.[FORMAT] (например, Post.orm.yaml) в сконфигурированном dir вашего отображения (если вы отображаете пакет, то dir относителен к каталогу пакета).

Пакет ищет файлы (в этом порядке) XML, YAML и PHP. Используя функцию auto_mapping, каждый пакетможет иметь только один формат конфигурации. Пакет остановится как только найдёт его.

Если определить формат конфигурации для пакета было невозможно, то DoctrineBundle проверит наличие папки Entity в корневом каталоге пакета. Если папка не существует, Doctrine будет использовать драйвер аннотаций.

Значение Dir по умолчанию

Если dir не указан, тогда его значение по умолчанию зависит от того, какой драйвер конфигурации используется. Для драйверов, полагающихся на PHP-файлы (аннотация, staticphp) он будет [Bundle]/Entity. Для драйверов, использующих файлы конфигурации (XML, YAML, ...) он будет [Bundle]/Resources/config/doctrine.

Если конфигурация dir установлена, а конфигурация is_bundle - true, то DoctrineBundle добавит к конфигурации dir префикс в виде пути пакета.