Дата оновлення перекладу 2022-05-30

Довідник конфігурації 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
     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:[email protected]: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:              UTF8
            logging:              '%kernel.debug%'
            platform_service:     App\DBAL\MyDatabasePlatformService
            server_version:       '5.7'
            mapping_types:
                enum: string
            types:
                custom: App\DBAL\MyCustomType
    
  • 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
    29
    30
    31
    32
    33
    34
    <?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
            http://symfony.com/schema/dic/doctrine
            https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
    
        <doctrine:config>
            <doctrine:dbal
                name="default"
                dbname="database"
                host="localhost"
                port="1234"
                user="user"
                password="secret"
                driver="pdo_mysql"
                driver-class="App\DBAL\MyDatabaseDriver"
                path="%kernel.project_dir%/var/data/data.sqlite"
                memory="true"
                unix-socket="/tmp/mysql.sock"
                wrapper-class="App\DBAL\MyConnectionWrapper"
                charset="UTF8"
                logging="%kernel.debug%"
                platform-service="App\DBAL\MyDatabasePlatformService"
                server-version="5.7">
    
                <doctrine:option key="foo">bar</doctrine:option>
                <doctrine:mapping-type name="enum">string</doctrine:mapping-type>
                <doctrine:type name="custom">App\DBAL\MyCustomType</doctrine:type>
            </doctrine:dbal>
        </doctrine:config>
    </container>
    

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).

Якщо ви не визначили цю опцію і ви ще не створили вашу базу даних, то ви можете отримати помилки PDOException, так як Doctrine буде намагатися вгадати версію серверу бази даних автоматично, а вона не доступна.

Якщо ви хочете сконфгурувати декілька з’єднань в 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() та ім’я з’єднання:

// 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
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

Існує багато інших опцій конфігурації, які ви можете використати для перезапису визначених класів, але вони потрібні лише для дуже просунутих випадків використання.

Скорочений синтаксис конфігурації

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
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
        hydrators:
            # ...
        mappings:
            # ...
        dql:
            # ...
        filters:
            # ...

Ця скорочена версія часто використовується в інших розділах документації. Пам’ятайте, що ви не можете використовувати обидва синтаксиса одночасно.

Кешування драйверів

Використайте будь-який з існуючих пулів Кешу Symfony або визначте нові пули, щоб кешувати кожний з елементів Doctrine ORM (запити, результати та ін.):

# 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: AppORMMyCacheService

Конфігурація відображення

Чітке визначення всіх відображених сутностей - це єдина потрібна конфігурація для 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
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    doctrine:
        # ...
        orm:
            # ...
            auto_mapping: true
            mappings:
                # ...
                AppBundle:
                    type: xml
                    dir: SomeResources/config/doctrine
    
  • XML
     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>
    
  • PHP
     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
     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
    
  • XML
     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>
    
  • PHP
     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 префікс у вигляді шляху пакету.

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.