Конфигурация DoctrineBundle ("doctrine")

Полная конфигурация по умолчанию

  • 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
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    # config/packages/doctrine.yaml
    doctrine:
        dbal:
            default_connection:   default
            types:
                # Коллекция пользовательских типов
                # Пример
                some_custom_type:
                    class:                App\DBAL\MyCustomType
                    commented:            true
    
            connections:
                # Коллекция разноименованных соединений (например, default, conn2, и др.)
                default:
                    dbname:               ~
                    host:                 localhost
                    port:                 ~
                    user:                 root
                    password:             ~
                    # набор символов БД
                    charset:              ~
                    # набор символов и сравнение таблиц. Не наследуется из БД
                    default_table_options:
                        charset:          ~
                        collate:          ~
                    path:                 ~
                    memory:               ~
    
                    # unix сокет для использования в MySQL
                    unix_socket:          ~
    
                    # Можно использовать как постоянное соединение для драйвера ibm_db2
                    persistent:           ~
    
                    # Протокол для использования для драйвера ibm_db2 (по умолчанию - TCPIP, если опущено)
                    protocol:             ~
    
                    # Можно использовать dbname в качестве имени сервиса вместо SID для Oracle
                    service:              ~
    
                    # Режим сессии дляиспользования для драйвера oci8
                    sessionMode:          ~
    
                    # Можно использовать пулированный сервер с драйвером oci8
                    pooled:               ~
    
                    # Конфигурирование MultipleActiveResultSets для драйвера pdo_sqlsrv
                    MultipleActiveResultSets:  ~
                    driver:               pdo_mysql
                    platform_service:     ~
    
                    # версия вашего двигателя БД
                    server_version:       ~
    
                    # если true, то запросы логируются в канал monolog 'doctrine'
                    logging:              '%kernel.debug%'
                    profiling:            '%kernel.debug%'
                    driver_class:         ~
                    wrapper_class:        ~
                    # опция DBAL keepSlave
                    keep_slave:           false
                    options:
                        # массив опций
                        key:                  []
                    mapping_types:
                        # массив типов отображений
                        name:                 []
    
                    # Если определ1н, только таблицы, чьи названия совпадают с этим регулярным выражением
                    # обрабатываются инструментом схемы (в этом примере, любые названия таблиц, не начинающиеся с `wp_`)
                    #schema_filter:               '/^(?!wp_)/'
    
                    slaves:
    
                        # коллекция соединений, названных slave (например, slave1, slave2)
                        slave1:
                            dbname:               ~
                            host:                 localhost
                            port:                 ~
                            user:                 root
                            password:             ~
                            charset:              ~
                            path:                 ~
                            memory:               ~
    
                            # Сокет unix для использования с MySQL
                            unix_socket:          ~
    
                            # Можно использовать как постоянное соединение для драйвера ibm_db2
                            persistent:           ~
    
                            # Протокол для использования для драйвера ibm_db2 (по умолчанию - TCPIP, если опущено)
                            protocol:             ~
    
                            # Можно использовать dbname в качестве имени сервиса вместо SID для Oracle
                            service:              ~
    
                            # Режим сессии дляиспользования для драйвера oci8
                            sessionMode:          ~
    
                            # Можно использовать пулированный сервер с драйвером oci8
                            pooled:          ~
    
                            # Конфигурирование MultipleActiveResultSets для драйвера pdo_sqlsrv
                            MultipleActiveResultSets:  ~
    
        orm:
            default_entity_manager:  ~
            auto_generate_proxy_classes:  false
            proxy_dir:            '%kernel.cache_dir%/doctrine/orm/Proxies'
            proxy_namespace:      Proxies
            # искать класс "ResolveTargetEntityListener" для статьи об этом
            resolve_target_entities: []
            entity_managers:
                # Коллекция разноназванных менеджеров сущностей (например, some_em, another_em)
                some_em:
                    query_cache_driver:
                        type:                 array # Required
                        host:                 ~
                        port:                 ~
                        instance_class:       ~
                        class:                ~
                    metadata_cache_driver:
                        type:                 array # Required
                        host:                 ~
                        port:                 ~
                        instance_class:       ~
                        class:                ~
                    result_cache_driver:
                        type:                 array # Required
                        host:                 ~
                        port:                 ~
                        instance_class:       ~
                        class:                ~
                    connection:           ~
                    class_metadata_factory_name:  Doctrine\ORM\Mapping\ClassMetadataFactory
                    default_repository_class:  Doctrine\ORM\EntityRepository
                    auto_mapping:         false
                    hydrators:
    
                        # Массив имён-гидраторов
                        hydrator_name:                 []
                    mappings:
                        # Массив отображений, которые могут быть именем пакета или чем-то другим
                        mapping_name:
                            mapping:              true
                            type:                 ~
                            dir:                  ~
                            alias:                ~
                            prefix:               ~
                            is_bundle:            ~
                    dql:
                        # коллекция функций строки
                        string_functions:
                            # пример
                            # test_string: App\DQL\StringFunction
    
                        # коллекция числовых функций
                        numeric_functions:
                            # пример
                            # test_numeric: App\DQL\NumericFunction
    
                        # колекция дата-временных функций
                        datetime_functions:
                            # пример
                            # test_datetime: App\DQL\DatetimeFunction
    
                    # Зарегистрировать фильтры SQL в менеджере сущностей
                    filters:
                        # Массив фильтров
                        some_filter:
                            class:                ~ # Required
                            enabled:              false
    
  • 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
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    <!-- config/packages/doctrine.xml -->
    <?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
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/doctrine
            http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
    
        <doctrine:config>
            <doctrine:dbal default-connection="default">
                <doctrine:connection
                    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.6"
                    keep-slave="false"
                >
                    <doctrine:option key="foo">bar</doctrine:option>
                    <doctrine:mapping-type name="enum">string</doctrine:mapping-type>
                </doctrine:connection>
                <doctrine:connection name="conn1" />
                <doctrine:type name="custom">App\DBAL\MyCustomType</doctrine:type>
            </doctrine:dbal>
    
            <doctrine:orm
                default-entity-manager="default"
                auto-generate-proxy-classes="false"
                proxy-namespace="Proxies"
                proxy-dir="%kernel.cache_dir%/doctrine/orm/Proxies"
            >
                <doctrine:entity-manager
                    name="default"
                    query-cache-driver="array"
                    result-cache-driver="array"
                    connection="conn1"
                    class-metadata-factory-name="Doctrine\ORM\Mapping\ClassMetadataFactory"
                >
                    <doctrine:metadata-cache-driver
                        type="memcache"
                        host="localhost"
                        port="11211"
                        instance-class="Memcache"
                        class="Doctrine\Common\Cache\MemcacheCache"
                    />
    
                    <doctrine:mapping name="AcmeHelloBundle" />
    
                    <doctrine:dql>
                        <doctrine:string-function name="test_string">
                            App\DQL\StringFunction
                        </doctrine:string-function>
    
                        <doctrine:numeric-function name="test_numeric">
                            App\DQL\NumericFunction
                        </doctrine:numeric-function>
    
                        <doctrine:datetime-function name="test_datetime">
                            App\DQL\DatetimeFunction
                        </doctrine:datetime-function>
                    </doctrine:dql>
                </doctrine:entity-manager>
    
                <doctrine:entity-manager name="em2" connection="conn2" metadata-cache-driver="apc">
                    <doctrine:mapping
                        name="DoctrineExtensions"
                        type="xml"
                        dir="%kernel.project_dir%/vendor/gedmo/doctrine-extensions/lib/DoctrineExtensions/Entity"
                        prefix="DoctrineExtensions\Entity"
                        alias="DExt"
                    />
                </doctrine:entity-manager>
            </doctrine:orm>
        </doctrine:config>
    </container>
    

Конфигурация 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.6
            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
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/doctrine
            http://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.6">
    
                <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. Значение этой опции должно совпадать с вашей версией сервера БД (используйте команду postgres -V или psql -V, чтобы найти вашу версию PostgreSQL, и mysql -V, чтобы получить вашу версию MySQL).

Если вы не хотите определять эту опцию и вы ещё не создали вашу БД, то вы можете получить ошибки 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] - это имя соединения.

Конфигурация 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:
            # ...

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

Кеширующие драйверы

Встроенные типы кеширующих драйверов: array, apc, apcu, memcache, memcached, redis, wincache, zenddata и xcache. Существует специальный тип под названием service, который позволяет вам определять ID вашего собственного кеширующего сервиса.

Следующий пример демонстрирует обзор кеширующих конфигураций:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
doctrine:
    orm:
        auto_mapping: true
        # каждый тип кеширующего драйвера определяет собственные опции конфигурации
        metadata_cache_driver: apc
        result_cache_driver:
            type: memcache
            host: localhost
            port: 11211
            instance_class: Memcache
        # тип 'service' требует определения и опции 'id'
        query_cache_driver:
            type: service
            id: App\ORM\MyCacheService

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

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

type

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

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" charset="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
            http://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
    $container->loadFromExtension('doctrine', array(
        'orm' => array(
            'auto_mapping' => true,
            'mappings' => array(
                'AppBundle' => array('dir' => 'SomeResources/config/doctrine', 'type' => 'xml'),
            ),
        ),
    ));
    

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

Например, следующий код ищет классы сущности в пространстве имён 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" charset="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
            http://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
    $container->loadFromExtension('doctrine', array(
        'orm' => array(
            'auto_mapping' => true,
            'mappings' => array(
                'SomeEntityNamespace' => array(
                    'type'      => 'annotation',
                    'dir'       => '%kernel.project_dir%/src/Entity',
                    'is_bundle' => 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.