Довідник конфігурації Doctrine (DoctrineBundle)

Дата оновлення перекладу 2022-12-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:              UTF8
        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).

Якщо ви не визначили цю опцію і ви ще не створили вашу базу даних, то ви можете отримати помилки 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() та ім'я з'єднання:

        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
        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 (запити, результати та ін.):

        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 префікс у вигляді шляху пакету.