Интеграция ORM Doctrine и Zend Framework 3

12.3. Интеграция ORM Doctrine и Zend Framework 3

Для легкой интеграции с Zend Framework 3, Doctrine предоставляет два следующих компонента (которые, на самом деле, являются модулями ZF3):

DoctrineModule - это модуль ZF3, который предоставляет необходимую для компонента ORM базовую функциональность Doctrine;
DoctrineORMModule предназначен для интеграции объектно-реляционного преобразователя (ORM) Doctrine и Zend Framework 3.

Оба этих компонента распространяются в качестве пакета, устанавливаемого Composer'ом и зарегистрированного в каталоге Packagist.org. Этот способ похож на тот, что использует Zend Framework 3 для установки своих компонентов.

Так как пакеты Composer могут зависеть друг от друга, достаточно объявить зависимость только от DoctrineORMModule. Этот пакет зависит от DoctrineModule и некоторых других компонентов Doctrine (Doctrine\ORM, Doctrine\DBAL, Doctrine\Common, Doctrine\Annotations и др.). Таким образом, при установке этого компонента, Composer автоматически установит другие необходимые компоненты.

12.3.1. Установка компонентов Doctrine с помощью Composer

Для того чтобы установить необходимые компоненты Doctrine, сперва мы добавим зависимость в файл composer.json, находящийся в корневом каталоге веб-приложения (в данной книге это, как правило, каталог APP_DIR).

Чтобы добавить зависимость, наберите в командной оболочке следующие команды (замените плейсхолдер APP_DIR именем каталога вашего приложения):

cd APP_DIR

php composer.phar require doctrine/doctrine-orm-module

Команда cd используется для того, чтобы сделать APP_DIR текущим рабочим каталогом.

Команда require указывает Composer'у добавить пакет doctrine/doctrine-orm-module в качестве зависимости к вашему веб-приложению и скачать и установить эту зависимость.

Как только вы запустите приведенные выше команды, Composer сперва изменит файл composer.json, а затем создаст такую строку под ключом require:

{
    ...  
    "require": {    
        "doctrine/doctrine-orm-module": "^1.0.9",    
        ...
    },
    ...  
}

После этого Composer попытается определить местонахождение пакетов зависимостей, загрузить их на локальную машину и установить файлы в каталог APP_DIR/vendor.

Composer выведет в консоль информацию о процессе установки. Как можно видеть из этих строк, при установке компонента DoctrineORMModule Composer автоматически устанавливает DoctrineModule и все необходимые компоненты Doctrine (Doctrine\DBAL, Doctrine\ORM, и др.)

В качестве бонуса, в конце установки Composer "предложит" вам установить несколько дополнительных пакетов, которые могут быть вам полезны (doctrine/migrations, doctrine/data-fixtures, и др.) Если хотите, можете также добавить эти зависимости с помощью команды Composer'а require.

После завершения установки, файлы Doctrine можно найти в каталоге APP_DIR/vendor (см. рисунок 12.4 ниже).

Рисунок 12.4. Файлы Doctrine, установленные в каталог поставщика

Используйте команду php composer.phar require при первой установке Doctrine. После того, как файлы composer.json (и composer.lock) будут изменены Composer'ом, вы сможете установить (или обновить) все зависимости обычным путем, командами php composer.phar install или php composer.phar update соответственно.

12.3.2. Загрузка модулей интеграции Doctrine при запуске приложения

После того, как вы установили DoctrineORMModule и все его зависимости, нужно добавить следующие строки в файл APP_DIR/config/modules.config.php для включения модулей:

<?php
return [
    // Добавляем модули интеграции Doctrine.
    'DoctrineModule',
    'DoctrineORMModule',      
    //...
);

Этот код сообщает ZF3, что при старте приложения нужно загружать модули DoctrineModule и DoctrineORMModule*.

12.3.3. Обзор конфигурации Doctrine

Чтобы использовать Doctrine в своем веб-приложении, нужно также предоставить ее конфигурацию. Конфигурация указывают Doctrine, какие присутствуют базы данных, как к ним подключиться (какие использовать драйвер БД, хост, имя пользователя и пароль), где искать классы сущностей и как извлекать их аннотации (метаданные), как хранить кэшированные данные (в файловой системе или использовать расширение для кэширование) и т.д. Цель этого раздела - дать вам общее представление о том, как выглядит настройка Doctrine.

Настройка Doctrine по умолчанию распложена в файле конфигурации module.config.php модулями DoctrineORMModule. Как может выглядеть "дерево" конфигурации Doctrine можно посмотреть ниже на рисунке 12.5 ⁴⁷. Также для этого вы можете обратиться к самому файлу module.config.php.

Рисунок 12.5. Графическое представление "дерева" настройки Doctrine

⁴⁷⁾ Дерево на рисунке 12.5 может отличаться от того, которое получилось в вашем приложении, так как некоторые ключи были опущены для простоты.

Как можете видеть из рисунка 12.5, существует ключ верхнего уровня с именем doctrine. Под этим ключом находится большое количество подключей, содержащих следующие настройки:

ключ connection содержит список всех баз данных, к которым может подключиться веб-приложение. Для каждого соединения он также содержит параметры: имя класса драйвера, хост, имя пользователя, пароль и имя БД.

По умолчанию, там находится только одно соединение - orm_default, и, если потребуется, вы можете добавить другие.

ключ configuration содержит такие настройки ORM, как настройка кэширования и местонахождения автосгенерированных классов классов сущностей для каждого доступного соединения.
ключ driver содержит информацию о том, где находятся классы сущностей для каждого доступного соединения.
ключ entitymanager содержит настройки, используемые для инстанцирования менеджера сущностей для каждого доступного соединения.
ключ eventmanager содержит настройки менеджера событий Doctrine для каждого доступного соединения.

Doctrine использует свою собственную реализацию менеджера событий. Если хотите, можете создать класс обработчика событий и его реакции. Однако, подобные продвинутые темы в этой книге мы рассматривать не будем.

ключ migrations_configuration содержит настройки для миграций баз данных. Миграции БД используются для инициализации и обновления схемы базы данных стандартным и непротиворечивым способом.

12.3.4. Переопределение настройки Doctrine по умолчанию

Как вы уже знаете из главы Как работает веб-сайт, конфигурация веб-приложения на базе ZF3, как правило, делится на две категории: настройка на уровне приложения и настройка на уровне модуля.

Для хранения настроек Doctrine на уровне приложения, обычно используются файлы конфигурации APP_DIR/config/autoload/global.php или APP_DIR/config/autoload/local.php. Первый хорошо подходит для хранения настроек, не зависимых от конкретной среды, а второй - наоборот, для хранения настроек, зависимых от среды (например, параметры подключения к базе данных).
Для хранения настроек Doctrine для определенного модуля, используется файл конфигурации module.config.php, находящийся внутри каталога config этого модуля. Это подходит, например, для хранения настроек местонахождения сущности.

Когда сайт на базе ZF3 загружает свои настройки, он объединяет все конфигурации в один большой массив, тем самым формируя окончательное "дерево" конфигурации Doctrine.

Добавляя свою настройку Doctrine на уровне приложения, вы расширяете и/или перезаписываете дерево настроек по умолчанию, предоставляемых DoctrineORMModule.