Nette a Doctrine 2 – mé řešení

Přislíbil jsem, že sepíši něco o mém řešení Doctrine 2, takže tak činím… Na úvod jen upozornění, že se jedná o mé řešení integrace s Doctrine 2, neznamená to tedy, že se jedná o nejlepší řešení.

Ještě než začneme psát vůbec nějaký kód, přidáme si pár řádek do config.ini:

; doctrine configuration
[common.doctrine]
entityDir = '%appDir%/Entities'
proxyDir = '%appDir%/Proxies'
proxyNamespace = 'PandaWeb\Proxies'

; connection options
[development.doctrine.connection]
driver = pdo_pgsql
user = pandaweb
password = pandaweb
dbname = pandaweb

Sekce [common.doctrine] obsahuje obecné nastavení složek a namespaces naší aplikace, [development.doctrine.connection] pak nastavení parametrů připojení pro konkrétní prostředí.

Vedle klasického bootstrap.php si vytvoříme další speciální bootstrap čistě pro Doctrine, nazveme ho například bootstrap-doctrine.php. Bude se nám hodit při dalším použití v aplikaci, například v bootstrapu pro testy, nebo ve skriptech pro příkazovou řádku. Důležitá místa v kódu jsem se snažil okomentovat, unsety jsou v kódu kvůli automatizovaným testům v PHPUnit, které si snaží serializovat globální proměnné.

<?php

use Doctrine\ORM\EntityManager;
use Doctrine\ORM\Configuration;
use Nette\Environment;

// načítáme objekt s konfigurací
$doctrine = Environment::getConfig('doctrine');

$config = new Configuration();
// nastavíme složky a namespaces
$config->setProxyDir($doctrine->proxyDir);
$config->setProxyNamespace($doctrine->proxyNamespace);
// v produkčním prostředí nechceme generovat proxy třídy automaticky
// nastavením na FALSE můžeme vynutit manuální vytváření za všech okolností
$config->setAutoGenerateProxyClasses(!Environment::isProduction());

$metadataDriver = $config->newDefaultAnnotationDriver($doctrine->entityDir);
$config->setMetadataDriverImpl($metadataDriver);

// v produkčním prostředí zkusíme použít APCCache, jinak ArrayCache
if (Environment::isProduction() && extension_loaded('apc')) {
	$cache = new Doctrine\Common\Cache\ApcCache();
} else {
	$cache = new Doctrine\Common\Cache\ArrayCache();
}

$config->setMetadataCacheImpl($cache);
$config->setQueryCacheImpl($cache);

// cleanup
unset($cache);

$eventManager = new Doctrine\Common\EventManager();
// nastavení charsetů pro MySQL
if ($doctrine->connection->driver == 'pdo_mysql') {
	$eventManager->addEventSubscriber(new \Doctrine\DBAL\Event\Listeners\MysqlSessionInit('utf8', 'utf8_czech_ci'));
}
// Vytvoření samotného EntityManageru
$entityManager = EntityManager::create((array) $doctrine->connection, $config, $eventManager);
Environment::getServiceLocator()->addService('Doctrine\ORM\EntityManager', $entityManager);

// cleanup
unset($doctrine, $config, $metadataDriver, $eventManager, $entityManager);

Environment::setServiceAlias('Doctrine\\ORM\\EntityManager', 'EntityManager');
Environment::setServiceAlias('PandaWeb\\Application\\DatabaseManager', 'DatabaseManager');

Povšímnětě si také přidání aliasu pro službu PandaWeb\Application\DatabaseManager – jedná se o třídu, kterou používám jako obálku nad EntityManagerem a která mi usnadňuje přístup k repositářům entit a některým funkcím EntityManageru:

<?php

namespace PandaWeb\Application;

use Doctrine\ORM\EntityManager;
use PandaWeb\Entities\BaseEntity;


/**
 * @property-read \Doctrine\ORM\EntityManager $entityManager
 * @property-read \Doctrine\ORM\EntityRepository $page
 * @property-read \PandaWeb\Repositories\UserRepository $user
 * ...
 *
 * @method void clear() clear()
 * @method void flush() flush()
 * @method void remove() remove(BaseEntity $entity)
 * @method void refresh() refresh(BaseEntity $entity)
 * @method void beginTransaction() beginTransaction()
 * @method void commit() commit()
 * @method void rollback() rollback()
 */
class DatabaseManager
{
	/** @var EntityManager */
	protected $entityManager;


	public function __construct()
	{
		$this->entityManager = \Nette\Environment::getService('Doctrine\ORM\EntityManager');
	}

	public function __get($name)
	{
		if ($name == 'entityManager') {
			return $this->entityManager;
		} else {
			return $this->entityManager->getRepository('PandaWeb\\Entities\\' . ucfirst($name));
		}
	}

	public function __call($name, $arguments)
	{
		return \call_user_func_array(array($this->entityManager, $name), $arguments);
	}


	public function persist($entity)
	{
		$this->entityManager->persist($entity);
	}

	public function lock($entity, $version)
	{
		$this->entityManager->lock($entity, \Doctrine\DBAL\LockMode::OPTIMISTIC, $version);
	}
}

Getter nám umožňuje jednoduše přistupovat k jednotlivým repositářům entit: $databaseManager->page nám získá reposítář pro entitu PandaWeb\\Entities\\Page a podobně. Metodu lock() jsem si napsal jako shortcut pro optimistické zamykání, magický __call() se nám postará o předání volání neznámých funkcí přímo EntityManageru. Třída samozřejmě musí být zaregistrovaná jako služba v config.ini:

[common.service]
; ...
PandaWeb-Application-DatabaseManager = PandaWeb\Application\DatabaseManager
; ...

Dále se nám bude hodit třída BaseEntity, od které budeme dědit konkrétní entity:

<?php

namespace PandaWeb\Entities;

use Nette\Object;
use Nette\Environment;
use Nette\Caching\Cache;

/**
 * @MappedSuperclass
 * @HasLifecycleCallbacks
 *
 * @property-read int $id
 */
abstract class BaseEntity extends Object
{
	/**
	 * @Id
	 * @Column(type = "integer")
	 * @GeneratedValue
	 * @var int
	 */
	protected $id;


	/** @var \Doctrine\ORM\EntityRepository */
	private $repository;



	public function persist()
	{
		Environment::getDatabaseManager()->persist($this);
	}

	public function remove()
	{
		Environment::getDatabaseManager()->remove($this);
	}

	public function setValues(array $data)
	{
		foreach ($data as $key => $value) {
			$this->__set($key, $value);
		}
	}


	/** @return \Doctrine\ORM\EntityRepository */
	public function getRepository()
	{
		if ($this->repository === NULL) {
			$this->repository = Environment::getEntityManager()->getRepository(\get_class($this));
		}
		return $this->repository;
	}


	public function free()
	{
		$this->repository = NULL;
	}

	public function __sleep()
	{
		$this->free();
	}


	public function getId()
	{
		return $this->id;
	}

	public function getCacheTags()
	{
		$tags = array();
		if ($this->id !== NULL) {
			$tags[] = get_class($this) . '#' . $this->id;
		}
		return $tags;
	}


	/**
	 * @PostPersist
	 * @PostUpdate
	 * @PostRemove
	 */
	public function cleanCache()
	{
		Environment::getCache()->clean(array(
			Cache::TAGS => array_merge(array(get_class($this)), $this->getCacheTags())
		));
	}

}

Tato třída nám umožňuje volat operace persist() a remove() přímo nad konkrétním objektem. Mnohem zajímavější je však funkce cleanCache() – ta se registruje jako lifecycle callback a při operacích, které nějakým způsobem zasahují do databáze, automaticky invalidují cache. To nám usnadňuje bezpečné a bezstarostné cachování objektů závislých na databázi. Při cachování objektu Nette\Security\Permission tak můžeme jednoduše zapsat

$cache->save('permission', $permission, array(
	Cache::TAGS => array(
		'PandaWeb\Entities\Role',
		'PandaWeb\Entities\Permission'
	)
));

a cache se nám automaticky invaliduje při jakékoliv změně daných tabulek v databázi. Samotřejmě to funguje jen pro modifikace provedené skrz naší aplikaci.

V BasePresenteru si pak objekt DatabaseManger načteme do členské proměnné, abychom nemuseli zatěžovat Nette\IServiceLocator pokaždé, když budeme chtít pracovat s databází:

<?php

// ...

abstract class BasePresenter extends Presenter
{
	public function __construct(\Nette\IComponentContainer $parent = NULL, $name = NULL)
	{
		parent::__construct($parent, $name);

		$this->databaseManager = Environment::getService('PandaWeb\Application\DatabaseManager');
	}

	// ...
}

Další věcí, kterou budeme potřebovat, je nástroj pro práci s databází – tedy něco, co nám umožní při vývoji průběžně aktualizovat databázové schéma podle toho, jak budeme přidávat a upravovat entity. Vytvoříme si tedy na to několik skriptů. Vedle složky app si vytvoříme složku scripts. Do ní si vytvoříme obecný bootstrap pro naše konzolové skripty (bootstrap.php):

use Nette\Environment;
use Nette\Debug;

define('CLI_DIR', __DIR__);
define('APP_DIR', CLI_DIR . '/../app');
define('LIBS_DIR', CLI_DIR . '/../libs');


require LIBS_DIR . '/Nette/loader.php';

Debug::enable();
Environment::loadConfig();

require APP_DIR . '/bootstrap-doctrine.php';

K tomu přihodíme mírně modifikovanou verzi doctrine-cli.php z dokumentace:

<?php

use Nette\Environment;

require __DIR__ . '/bootstrap.php';

$entityManager = Environment::getService('Doctrine\ORM\EntityManager');

$helpers = array(
    'db' => new \Doctrine\DBAL\Tools\Console\Helper\ConnectionHelper($entityManager->getConnection()),
    'em' => new \Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper($entityManager)
);

$helperSet = new \Symfony\Components\Console\Helper\HelperSet();
foreach ($helpers as $alias => $helper)
	$helperSet->set ($helper, $alias);

$cli = new \Symfony\Components\Console\Application('Doctrine Command Line Interface', Doctrine\ORM\Version::VERSION);
$cli->setCatchExceptions(true);
$cli->setHelperSet($helperSet);
$cli->addCommands(array(
    // DBAL Commands
    new \Doctrine\DBAL\Tools\Console\Command\RunSqlCommand(),
    new \Doctrine\DBAL\Tools\Console\Command\ImportCommand(),

    // ORM Commands
    new \Doctrine\ORM\Tools\Console\Command\ClearCache\MetadataCommand(),
    new \Doctrine\ORM\Tools\Console\Command\ClearCache\ResultCommand(),
    new \Doctrine\ORM\Tools\Console\Command\ClearCache\QueryCommand(),
    new \Doctrine\ORM\Tools\Console\Command\SchemaTool\CreateCommand(),
    new \Doctrine\ORM\Tools\Console\Command\SchemaTool\UpdateCommand(),
    new \Doctrine\ORM\Tools\Console\Command\SchemaTool\DropCommand(),
    new \Doctrine\ORM\Tools\Console\Command\EnsureProductionSettingsCommand(),
    new \Doctrine\ORM\Tools\Console\Command\ConvertDoctrine1SchemaCommand(),
    new \Doctrine\ORM\Tools\Console\Command\GenerateRepositoriesCommand(),
    new \Doctrine\ORM\Tools\Console\Command\GenerateEntitiesCommand(),
    new \Doctrine\ORM\Tools\Console\Command\GenerateProxiesCommand(),
    new \Doctrine\ORM\Tools\Console\Command\ConvertMappingCommand(),
    new \Doctrine\ORM\Tools\Console\Command\RunDqlCommand(),
    new \Doctrine\ORM\Tools\Console\Command\ValidateSchemaCommand(),
));
$cli->run();

A pokud pracujeme na Windows, bude se nám možná hodit doctrine-cli.bat:

@echo off
REM cestu k PHP si nastavte podle potřeby
C:\webserverX64\php\php.exe doctrine-cli.php %*

Nyní můžeme jednoduše z příkazové řádky ve složce scripts vytvořit naše databázové schéma:

doctrine-cli orm:schema-tool:create

A aktualizace provádíme příkazem

doctrine-cli orm:schema-tool:update

Příkazy poslušně načtou informace z entity a vytvoří/upraví podle nich databázové schéma.

Pokud jsme odvážnější a chceme jít ještě kousek dál, můžeme si vytvořit vlastní skript, který kromě standartních operací v Doctrine bude umět na databázovém schématu provádět vlastní změny načtené z SQL skriptů. To nám umožní využívat funkce, které jsou specifické pro náš databázový stroj – například triggery, uložené procedury, views, FTS konfigurace v PostgreSQL…

Nejdříve uvedu zdrojové kódy a až pak vysvetlím práci s nimi.

SQLImporter.php:

<?php

namespace PandaWeb;

use Doctrine\ORM\EntityManager;
use Nette\Environment;
use Nette\String;


class SQLImporter
{
	private static $driver;

	private static function getDriver()
	{
		if (self::$driver === NULL) {
			self::$driver = Environment::getConfig('doctrine')->connection->driver;
			if (String::startsWith(self::$driver, 'pdo_')) {
				self::$driver = substr(self::$driver, 4);
			}
		}
		return self::$driver;
	}

	public static function importDir(EntityManager $entityManager, $subdir)
	{
		$connection = $entityManager->getConnection();

		if (file_exists($dir = __DIR__ . '/' . self::getDriver() . '/' . $subdir)) {
			$files = array();
			$iterator = new \RecursiveIteratorIterator($dir = new \RecursiveDirectoryIterator($dir));
			foreach ($iterator as $file) {
				/* @var $file SplFileInfo */
				if ($file->isFile() && String::endsWith($file->getFilename(), '.sql')) {
					$files[$dir->getSubPathname()] = $file->getPathname();
				}
			}
			ksort($files);
			foreach ($files as $subpath => $file) {
				echo 'Importing ' . $subdir . '/' . $subpath . '...';
				$connection->exec(file_get_contents($file));
				echo ' ok' . PHP_EOL;
			}
		}
	}
}

schema-update.php:

<?php

use Nette\Environment;
use Nette\String;

if (!class_exists('\Nette\Environment')) {
	require_once __DIR__ . '/bootstrap.php';
}

require_once __DIR__ . '/SQLImporter.php';

$entityManager = Environment::getService('Doctrine\ORM\EntityManager');
/* @var $entityManager Doctrine\ORM\EntityManager */

$metadata = $entityManager->getMetadataFactory()->getAllMetadata();

echo 'Generating proxies...';
$entityManager->getProxyFactory()->generateProxyClasses($metadata);
echo ' ok' . PHP_EOL;

\PandaWeb\SQLImporter::importDir($entityManager, 'clean');

echo 'Performing schema update...';
$schemaTool = new \Doctrine\ORM\Tools\SchemaTool($entityManager);
$schemaTool->updateSchema($metadata);
echo ' ok' . PHP_EOL;

\PandaWeb\SQLImporter::importDir($entityManager, 'init');

// cleanup
unset($entityManager, $metadata, $schemaTool);

echo 'Schema update done.' . PHP_EOL;

Metoda SQLImporter::importDir bude načítat skripty ze složky %doctrine.connection.driver%/$subdir s tím, že pokud driver bude začínat na pdo_, tak se odtrhne. Skripty pro PostgeSQL se tedy budou načítat z pgsql/$subdir. Aktualizace bude probíhat ve 3 fázích – načtení skriptů z podsložky clean, změna schématu a načtení skriptů z podsložky init.

Fáze clean uvede databázi do stavu, v jakém se nacházela těsně před provedením fáze init. Tento krok je nutný, protože skripty z fáze init mohou modifikovat existující objekty tak, že analýza schématu z Doctrine si nebude vědět s objekty radu (například nebude znát daný typ indexu, sloupce, …) a aktualizace selže.

Lepší ale bude příklad. Ve složce pgsql/init mám skript 20_pages.sql:

CREATE TRIGGER pages_fts_update AFTER INSERT OR UPDATE
   ON pages FOR EACH ROW
   EXECUTE PROCEDURE fts_update('Page');

Vytvořený trigger by měl být ve fázi clean odstraněn, proto ve složce pgsql/clean musím také vytvořit skript 20_pages.sql:

DO $$BEGIN
IF EXISTS(SELECT tablename FROM pg_tables WHERE tablename = 'pages') THEN
	DROP TRIGGER IF EXISTS pages_fts_update ON pages;
END IF;
END$$ LANGUAGE plpgsql;

Pokud bych tento skript nenapsal a později se rozhodl tabulku pro entity PandaWeb\Entities\Page později přejmenovat, došlo by při přištím spuštění aktualizace k nepěkné výjimce – Doctrine by se snažilo odstranit starou tabulku, ale na té by závisel trigger, o kterém Dotrine nemá potuchy a databáze by odmítla takovou operaci provést.

To by bylo asi vše. Doufám, že se mi podařilo to sepsat srozumitelně a že to bude alespoň někomu užitečné. Připomínky, návrhy a Vaše řešení uvítám! A jsem si jistý, že nejen já…

Editoval Panda (17. 8. 2010 20:58)