A free and open-source book on ZF3 for beginners

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):

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):


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 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:

return [
    // Add the Doctrine integration modules.

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 47. 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" Figure 12.5. Graphical representation of Doctrine configuration "tree"

47) 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:

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

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.

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.

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.