Integrating Doctrine ORM with Zend Framework 3

12.3. Integrating Doctrine ORM with Zend Framework 3

For easy integration with Zend Framework 3, Doctrine project provides the following two components (that are actually ZF3 modules):

DoctrineModule is a ZF3 module that provides Doctrine basic functionality required by the ORM component;
DoctrineORMModule integrates Doctrine Object Relational Mapper (ORM) with Zend Framework 3.

Each of the above Doctrine components is distributed as a Composer-installable package and is registered in Packagist.org catalogue. This is very similar to the way that Zend Framework 3 uses for installing its components.

Since Composer packages may depend on each other, it is enough to declare dependency only on DoctrineORMModule. This package depends on DoctrineModule and on some other Doctrine components (Doctrine\ORM, Doctrine\DBAL, Doctrine\Common, Doctrine\Annotations, etc.). So, when you install this component, Composer will install other required components automatically.

12.3.1. Installing Doctrine Components with Composer

In order to install required Doctrine components, we first add a dependency to the composer.json file located in the root directory of the web application (in this book, we typically denote that directory as APP_DIR).

To add the dependency, type the following commands from your command shell (replace the APP_DIR placeholder with the actual directory name of your application):

cd APP_DIR

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

The cd command above is used to make the APP_DIR directory current working directory.

And the require command tells Composer to add the package doctrine/doctrine-orm-module as a dependency to your web application, and to download and install that dependency.

Once you run the commands above, Composer will first modify the composer.json file and create the line like below under its require key:

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

Then Composer will try to locate the dependency packages, download them to the local machine and install the files into the APP_DIR/vendor directory.

Composer will output lines indicating installation process to the terminal. As you can see from the Composer output, when you install DoctrineORMModule component, Composer automatically installs the DoctrineModule and all necessary Doctrine components (Doctrine\DBAL, Doctrine\ORM, etc.)

As a bonus, at the end of installation, Composer "suggests" you to install some additional packages that might be useful for you (doctrine/migrations, doctrine/data-fixtures, etc.) If you strongly wish, you may add those dependencies with the Composer's require command as well.

When the installation has been finished, you can find the Doctrine files in your APP_DIR/vendor directory (see the figure 12.4 below).

Figure 12.4. Doctrine files are installed to vendor directory

You use the php composer.phar require command for the first time you install Doctrine. Once the composer.json (and composer.lock) files have been modified by Composer, you are able to install (or update) all dependencies as usual by typing the php composer.phar install or php composer.phar update commands, respectively, from your command shell.

12.3.2. Loading Doctrine Integration Modules on Application Start Up

Once you have installed the DoctrineORMModule and all its dependencies, you need to add the following lines to your APP_DIR/config/modules.config.php file to enable the modules:

<?php
return [
    // Add the Doctrine integration modules.
    'DoctrineModule',
    'DoctrineORMModule',      
    //...
);

The lines above let ZF3 know that it should load the DoctrineModule module and DoctrineORMModule module on application start up.

12.3.3. Doctrine Configuration Overview

To use Doctrine with your ZF3-based web application, you have to provide its configuration. The configuration tells Doctrine what databases present, how to connect to a database (what database driver, host, user name and password to use), where to locate entity classes and how to extract their annotations (metadata), how to store cached data (in the file system or to use a caching extension), and so on. This section's goal is to give you a general idea of how Doctrine configuration looks like.

The default Doctrine configuration is located in the module.config.php config file of the DoctrineORMModule. Look at the figure 12.5 below to have an idea of how the Doctrine config "tree" may look like ⁴⁷. You may also refer to the module.config.php file of DoctrineORMModule for the same reason.

Figure 12.5. Graphical representation of Doctrine configuration "tree"

⁴⁷⁾ The tree in figure 12.5 may be different than you have in your own application, because some keys were omitted here for simplicity.

As you can see from the figure 12.5, there is the top-level key named doctrine. Under that key, there is a number of subkeys containing the following settings:

the connection key contains the list of all databases that the web application is able to connect to. For each database connection it contains parameters like driver class name, host, user name, password and database name.

By default, there is only one connection named orm_default, and you may add more database connections if required.

the configuration key contains ORM settings like caching configuration and locations of auto-generated entity proxy classes for each available connection.
the driver key contains the information about where to locate entity classes for each available database connection.
the entitymanager key contains settings used for instantiating an entity manager for each database connection.
the eventmanager key contains settings for Doctrine event manager for each available connection.

Doctrine uses its own implementation of event manager. If you want, you can create an event listener class and hooks some events. However, this is an advanced topic and we do not cover it in this book.

the migrations_configuration key contains settings for database migrations. Database migrations are used for initializing and updating database schema in a standard and consistent way.

12.3.4. Overriding the Default Doctrine Configuration

As you already know from Website Operation chapter, in a ZF3-based web application configuration is typically divided into two categories: application-wide configuration and module-specific configuration.

For storing application-wide Doctrine settings, you typically use the APP_DIR/config/autoload/global.php or APP_DIR/config/autoload/local.php config files. The first one suits well for storing settings not depending on particular environment, while the latter one suits well for storing environment-dependent settings (like database connection parameters).
For storing Doctrine settings specific to certain module, you use the module.config.php config file located inside the config directory of that module. This is suitable, for example, for storing the entity location settings.

When ZF3-based website loads its configuration, it merges all configs into a single big array, thus forming the final Doctrine config "tree".

By adding your application-specific Doctrine configuration, you extend and/or override the default configuration tree provided by the DoctrineORMModule.