Довідник конфігурації Doctrine (DoctrineBundle)
Дата оновлення перекладу 2024-05-29
Довідник конфігурації 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
).
Якщо ви не визначили цю опцію і ви ще не створили вашу базу даних, то
ви можете отримати помилки 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): void
{
$connection = $doctrine->getConnection('customer');
$result = $connection->fetchAllAssociative('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 або визначте нові пули, щоб кешувати кожний з елементів 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
префікс у
вигляді шляху пакету.