Справочник конфигурации Doctrine (DoctrineBundle)
Дата обновления перевода 2024-07-25
Справочник конфигурации 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, чтобы узнать больше. Следующий блок показывает все возможные ключи конфигурации:
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
).
Это изменится в Doctrine DBAL 4.x, где вам необходимо будет определять версию в
качестве вывода сервера (например, 10.4.14-MariaDB
).
Всегда помещайте номер версии сервера в кавычки, чтобы анализировать его как строку,
а не как число с плавающей запятой. Иначе проблемы представляения числа с плавающей
запятой могут сделать так, что ваша версия будет считаться другим числом (например,
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): void
{
$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
:
1 2 3 4 5 6 7 8 9 10
doctrine:
# ...
orm:
# ...
auto_mapping: true
mappings:
# ...
AppBundle:
type: xml
dir: SomeResources/config/doctrine
Отображение сущностей вне пакета
Например, следующий код ищет классы сущности в пространстве имён Entity
в каталоге src/Entity
и предоставляет им дополнительное имя App
(чтобы
вы могли писать вещи вроде App:Post
):
1 2 3 4 5 6 7 8 9 10 11 12
doctrine:
# ...
orm:
# ...
mappings:
# ...
SomeEntityNamespace:
type: attribute
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
префикс в виде
пути пакета.