README

The RdnDoctrine ZF2 module is a simple bridge to the Doctrine ORM library.

How to install

1. Use composer to require the radnan/rdn-doctrine package:

   $ composer require radnan/rdn-doctrine:1.*

2. Activate the module by including it in your application.config.php file:

   <?php
   
   return array(
       'modules' => array(
           'RdnDoctrine',
           // ...
       ),
   );

Dependencies

This module relies on the modules: RdnConsole, RdnDatabase, and RdnFactory.

How to use

Entity managers can be registered with the RdnDoctrine\EntityManagerManager service locator using the rdn_entity_managers configuration option.

<?php

return array(
	'rdn_entity_managers' => array(
		'factories' => array(),
		'invokables' => array(),
	),
);

You can also use the managers key to quickly generate an entity manager using simple configuration options:

<?php

return array(
	'rdn_entity_managers' => array(
		'managers' => array(
			'App' => array(
				/* configuration options */
			),
		),
	),
);

Configuring an entity manager is as simple as that! Here we've configured an entity manager with the name App. Assuming our module name is also App the library will set you up with some sane defaults, all of which you can override.

By default, the manager will expect your entities to live inside the App\Entity namespace (or more generally <MANAGER-NAME>\Entity).

Configuration documentation

Controller plugin

Once an entity manager has been configured, you can access both the entity manager or entity repositories from your controller using the entity() plugin.

Since you can register multiple entity managers with different names, by default the plugin will fetch the entity manager with the same name as the module name:

namespace App\Controller;

use App\Entity;

class User
{
	public function createAction()
	{
		$user = new Entity\User;
		$user->setEmail('pot@example.com');

		$this->entity()->persist($user);
		$this->entity()->flush();
	}
}

In order to access an entity repository we call the same entity($name) plugin, only this time we provide an entity name:

namespace App\Controller;

use App\Entity;

class User
{
	public function editAction()
	{
		$id = $this->params('user-id');

		$user = $this->entity('User')->find($id);

		/**
		 * Alternatively we can be more explicit and request the
		 * User entity within the App module
		 */
		$user = $this->entity('App:User')->find($id);
	}
}

The RdnDoctrine\EntityManager\AliasResolver service is used to resolve aliases when one is not provided. For example, if User is given instead of App:User.

Code completion

If you'd like to have code completion for this plugin, include the following in your AbstractController class:

namespace App\Controller;

use Zend\Mvc\Controller\AbstractActionController;

/**
 * @method \Doctrine\ORM\EntityRepository|\Doctrine\ORM\EntityManager entity(\string $name = null) Get the entity manager or a repository for given entity name.
 */
abstract class AbstractController extends AbstractActionController
{
}

Then, simply extend your controllers off of this abstract controller.

Console commands

The module also comes with a set of console commands to manage the database schema and generate proxies.

You can run vendor/bin/console to run and get help on the console commands in the doctrine: namespace.

Shared entities

Usually you will have one module that will contain all your common entities such as User entities etc. You will also register a single entity manager for your application with the same name as this module.

You will then create separate modules for each section of your site. Each module will depend on the entities provided by the common module in addition to providing its own. But all of the modules will use the single shared entity manager.

Let's say our common module is called App and we have another module called Foo. In this case the configuration for the Foo module would look like this:

<?php

return array(
	'rdn_entity_managers' => array(
		'managers' => array(
			'App' => array(
				'table_prefixes' => array(
					'Foo' => 'foo__',
				),
			),
		),

		'modules' => array(
			'Foo' => 'App',
		),
	),
);

This will add the entities provided by Foo (in the Foo\Entity namespace) to the App entity manager and instruct all plugins to use the App entity manager from within the Foo module.

namespace Foo\Controller;

class Bar
{
	public function editAction()
	{
		// We can now access the Foo entity repositories
		$bar = $this->entity('Bar')->find($id);
		// - OR - more explicitly
		$bar = $this->entity('Foo:Bar')->find($id);

		// We can also access the App entity repositories
		$user = $this->entity('User')->find($id);
		// - OR - more explicitly
		$user = $this->entity('App:User')->find($id);

		// We have access to the shared entity manager
		$this->entity()->flush();
	}
}