Zend Framework: Zend_Generator_Orm Component Proposal

Proposed Component Name	Zend_Generator_Orm
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Generator_Orm
Proposers	Thomas VEQUAUD
Revision	0.1 - 27 April 2008: Creation of the proposal 0.2 - 27 April 2008: Attachment added (source code in a zip file) 0.3 - 27 April 2008: Sources updated 0.4 - 28 April 2008: Requirements and milestones added 0.5 - 30 April 2008: Class squeletons added 0.6 - 02 May 2008: Use cases added 0.7 - 14 May 2008: Use cases updated (wiki revision: 29)

Within Zend Framework, you need to define a class in 'models' directory that extends Zend_Db_Table_Abstract for each table in your database that you want to access. For each class, you need to declare various protected variables like the name of the table in $_name, the primary(ies) key(s) in $_primary, the dependent tables $_dependentTables, the linked tables in $_referenceMap, etc. At least, you spent a lot of time to create the same things and at each modification of your database, you have to edit again your models!
Zend_Generator_Orm Proposal is a simple component that reads the architecture of your database and generates Zend models automatically. This generator creates and/or updates your models with predefined methods and keep intact your own implemented methods in it.

Français

Au sein du Framework Zend, vous avez besoin de définir une classe dans le répertoire 'models' qui étend Zend_Db_table_Abstract pour chaque table de votre base de données que vous voulez accéder. Pour chacune de ces classes, vous avez besoin de déclarer des variables protected comme le nom de la table dans $_name, les clé(s) primaire(s) dans $_primary, les tables dépendantes dans $_dependentTables, les tables liées dans $_referenceMap, etc. Au final, vous passez un temps fou à créer les mêmes choses et, à chaque modification de votre base de données, vous devez encore éditer vos modèles!
Zend_Generator_Orm est un composant simple qui lit l'architecture de votre base de données et génères automatiquement les modèles Zend. Ce générateur de classes fonctionne que ce soit en création ou en update tout en conservant les méthodes implémentées par l'utilisateur.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

English

Having not the possibility to know by programming with a describeTable if the field is a foreign key, I had to fiddle with a naming convention. This naming convention allows to fix this problem. These rules seem to me basic in the database development because by this way you can easily identify the foreign keys, the table where they come from and every field is unique :

tables names : lowercase, only letters (category for example);
fields names : lowercase, singular, prefixed by the table name followed by an underscore (category_name for example);
foreign keys keep their name of primaries keys : by this way, with a regexp, I can know if it's a foreign key and which table this id comes from.

Français

N'ayant pas la possibilité de savoir par programmation avec un describeTable si le champs est une foreign key, il a fallu bidouiller un peu. Vous devez donc respecter une règle de nommage qui permet de pallier à ce problème. Ces règles me semblent élémentaires ds le développement de bases de données car de cette manière la lecture devient plus aisée (on identifie d'un seul coup d'oeil les foreign key et leur table de provenance) et chaque champs est unique :

noms des tables en minuscule, au singulier, en lettres uniquement (par exemple category) ;
noms des champs en minuscule, préfixés par le nom de la table suivi d'un underscore (par exemple category_name) ;
les clés étrangères conservent leurs noms de clés primaires : de cette manière, avec une regexp, je peux de suite savoir si il s'agit d'une foreign key et de quelle table vient cet id.

Acceptance criteria

This component will correctly read a database architecture.
This component will generate and update the models class within zend models directory.
Updates will not rewrite the methods implemented in every model class.
This component will work for all databases.
This component will implement 'magic' methodes.

4. Dependencies on Other Framework Components

Zend_Db
Zend_Db_Table
Zend_Exception

5. Theory of Operation

Load the class 'Zend_Orm' and instantiate it... Then just call the methods update() and/or create().
You have an example below...

6. Milestones / Tasks

Milestones :

[DONE] Developing the ORM generator
[DONE] Packaging for Zend architecture
[DONE] Suggesting it on Zend Framework Proposals
Working prototype checked into the incubator supporting use cases #1

7. Class Index

Zend_Orm
Zend_Generator_Exception
Zend_Generator_Orm_Abstract
Zend_Generator_Orm_Exception

8. Use Cases

The main use case is when you need to change the database schema of an application : you have to update or create a model for each table in your database schema... Busy work!
Zend_Generator_Orm makes it for you.

UC-01

Database configuration
Implement a controller 'OrmController' in your application/controller directory in your own Zend Application :

/** Zend_Controller_Action */
require_once('Zend/Controller/Action.php');

class OrmController extends Zend_Controller_Action
{
	/**
	 * Class initialization
	 */
	public function		init()
	{
		Zend_Loader::loadClass('Zend_Orm');
		return;
	}

	public function		indexAction()
	{
		$orm = new Zend_Orm();
		unset($orm);
		return;
	}

}

Implement a view 'index' in your application/views/scripts/orm directory :

<html>
	<head>
		<title>Zend_Orm::Use Cases</title>
	</head>
	<body>
		<strong>Report</strong>
		<?php
			foreach ($this->errors as $error)
				print($error."<br />\n");
			print($this->files['created']." new files created<br />\n");
			print($this->files['updated']." files updated<br />\n");
		?>
	</body>
</html>

In your browser, call the URL http://root_url/url_base/orm/ and then check a possible exception. IBlank page instead? Congratulation! You can go the UC-02...

UC-02

Create new models with Zend_Orm component
Add the create action in the controller OrmController previously implemented :

public function		createAction()
	{
		$orm = new Zend_Orm();
		$orm->create();
		$this->view->files	= $orm->getFiles();
		$this->view->errors	= $orm->getErrors();
		unset($orm);
		return;
	}

In your browser, call the URL http://root_url/url_base/orm/create and then check :

The content of your application/model directory.
The content of a chosen class model.

UC-03

Update models previously created by Zend_Orm component
Modify the structure of your database.
Modify (before and after the separator) the content of the chosen class model of the generated class models :

protected	$_primary			= array("address_id");

	/** End of auto-generated code - /!\ DO NOT REMOVE THIS LINE /!\ */
	/** BE CAREFUL : write your own code starting here, NOT before! */

	public function 	getAll()
	{

Add the update action in the controller OrmController previously implemented :

public function		updateAction()
	{
		$orm = new Zend_Orm();
		$orm->update();
		$this->view->files	= $orm->getFiles();
		$this->view->errors	= $orm->getErrors();
		unset($orm);
		return;
	}

In your browser, call the URL http://root_url/url_base/orm/update and then check the content of your modified model.

9. Class Skeletons

Zend/Orm.php

/**
* Abstract master class for extension.
*/
require_once('Zend/Generator/Orm/Abstract.php');


class Zend_Orm extends Zend_Generator_Orm_Abstract
{
	/**
	 * Data collected on database
	 * @var array
	 */
	private	$_data		= array();

	/**
	 * List of the tables in the database
	 *
	 * @var unknown_type
	 */
	private $_lstTables	= array();

	/**
	 * Number of files created or updated
	 * @var array
	 */
	private	$_files		= array();

	/**
	 * Errors reported
	 * @var array
	 */
	private	$_errors	= array();


    /**
     * Constructor
     * Get connection to the database
     */
	function __construct()
	{
		// Database
		$this->_db = Zend_Db_Table::getDefaultAdapter();
		$this->_db->getConnection();
		$this->_lstTables = $this->_db->listTables();
		$this->_data = $this->aggregateData();

		// Counters
		$this->_files['created'] = 0;
		$this->_files['updated'] = 0;
	}

    /**
     * Aggregates data get from database
     *
     * @return	an array of data about the database architecture :
     * 			- dependent tables,
     * 			- primary and foreign keys,
     *			- reference map,
     * 			etc.
     */
	private function	aggregateData()
    {
		// for each table
		foreach ($this->_lstTables as $table)
		{
			$sequence   = false;
			$desc       = $this->_db->describeTable($table);
			foreach ($desc as $field => $properties)
			{
				// if field is an id
				if (preg_match('`^(([[:alpha:]]*[_])?([[:alpha:]]*))_id$`', $field, $out) == true)
				{
					// Si l'id est une clé primaire
					if ($properties['PRIMARY'] == true)
					{
						if ($properties['IDENTITY'] == true)
							$data[$table]['sequence'] = true;
						$data[$table]['pk'][] = $properties['COLUMN_NAME'];
					}

					// if id is a foreign key
					if ($out[1] != $table)
					{
						$out[3] = ucfirst($out[3]);
						
						// Reference Table
						$role = ucfirst($table)."To".$out[3];
						$data[$table]['fk'][$role]['columns']       = $out[0];
						$data[$table]['fk'][$role]['refTableClass'] = $out[3];
						$data[$table]['fk'][$role]['refColumns']    = $out[0];
						
						// Dependent Table
						$data[$out[3]]['dt'][] = $table;
					}
				}
			}
		}
        return ($data);
	}

	/**
	 * Get database specifications and computes data
	 * Create database classes
	 */
	public function create()
    {
		foreach ($this->_data as $table => $properties)
		{
			$table		= ucfirst($table);
			$fileName	= MODEL_DIR."/$table.php";

			if (!file_exists($fileName))
			{
				// Open file in write mode
				if (($fp = fopen($fileName, "w")) == false)
					$this->_errors[] = "Cannot open file $fileName.";
				else
				{
					$this->createDbClass($fp, $table, $properties);
					fwrite($fp, "\n");
					$this->write_methodes($fp, $table, $properties);
					fwrite($fp, "}\n");
					// Close opened file
					if (fclose($fp) == true)
						$this->_files['created']++;
					else
						$this->_errors[] = "Table class '$table' generation failed.";
				}
			}
		}
		return;
	}


	/**
	 * Get database specifications and computes data
	 * Update database classes
	 */
	public function update()
    {
		foreach ($this->_data as $table => $properties)
		{
			$table		= ucfirst($table);
			$fileName	= MODEL_DIR."/$table.php";

			if (file_exists($fileName))
			{
				// Bufferise implemented functions in the current class
				if (($fp = fopen($fileName, "r")) == false)
					$this->_errors[] = "Cannot open file $fileName.";
				else
				{
					while (($line = fgets($fp)) && ($line != "	/** BE CAREFUL : write your own code starting here, NOT before! */\n"))
						;
					$buffer = '';
					while (!feof($fp))
					 	$buffer .= fgets($fp);
					fclose($fp);
				}
		
				// Rewrite class
				if (($fp = fopen($fileName, "w")) == false)
					$this->_errors[] = "Cannot open file $fileName.";
				else
				{
					$this->createDbClass($fp, $table, $properties);		
					fwrite($fp, $buffer);
					// Close opened file
					if (fclose($fp) == true)
						$this->_files['updated']++;
					else
						$this->_errors[] = "Table class '$table' generation failed.";
				}
			}
		}
		return;
	}

	private	function 	createDbClass($fp, $table, $properties)
	{		
		$this->write_header($fp, $table, $properties);
		
		// Write the beginning of the class
		fwrite($fp, "class $table	extends Zend_Db_Table_Abstract \n");
		fwrite($fp, "{\n");
		fwrite($fp, "	protected 	\$_name				= \"".strtolower($table)."\";\n");
		fwrite($fp, "	protected	\$_sequence			= ");
		(isset($properties['sequence']) && $properties['sequence']) ? fwrite($fp, "true;\n") : fwrite($fp, "false;\n");

		$this->write_pk($fp, $properties);
		$this->write_dependentTable($fp, $properties);
		$this->write_fk($fp, $properties);
		$this->write_separator($fp);
		return;
	}

	private	function 	write_header($fp, $table)
	{
		fwrite($fp, "<?php\n");
		fwrite($fp, "\n");
		fwrite($fp, "/**\n");
		fwrite($fp, " * $table implémente la classe de gestion de la table du même nom en base de\n");
		fwrite($fp, " * données.\n");
		fwrite($fp, " * \n");
		fwrite($fp, " * Zend_Db_Table est une classe abstraite : nous devons donc en hériter pour\n");
		fwrite($fp, " * définir notre classe spécifique aux pays. Il est logique de donner à cette\n");
		fwrite($fp, " * classe le nom de la table de la base de données. Ainsi, notre classe\n");
		fwrite($fp, " * s'appelle $table.\n");
		fwrite($fp, " * Pour indiquer à Zend_Db_Table le nom de la table qu'il devra gérer, nous\n");
		fwrite($fp, " * devons remplir la propriété protected \$_name avec le nom de la table. De\n");
		fwrite($fp, " * plus, Zend_Db_Table suppose que la table a une clef primaire qui est auto\n");
		fwrite($fp, " * incrementée par la base de données. Le nom de ce champ est précisé également\n");
		fwrite($fp, " * à l'aide de la propriété \$_primary.\n");
		fwrite($fp, " * @see		Zend_Db_Table_Abstract\n");
		fwrite($fp, " * \n");
		fwrite($fp, " * @author	Thomas VEQUAUD	<thomas.vequaud@gmail.com>\n");
		fwrite($fp, " */\n");
		fwrite($fp, "\n");
		return;
	}

	private function	write_pk($fp, $properties)
	{
		if (isset($properties['pk']))
		{
			fwrite($fp, "	protected	\$_primary			= ");
			if (is_array($properties['pk']))
			{
				fwrite($fp, "array(");
				$i = 0;
				$len = sizeof($properties['pk']) - 1;
				foreach ($properties['pk'] as $key)
				{
					fwrite($fp, "\"$key\"");
					if ($i != $len)
						fwrite($fp, ", ");
					$i++;
				}
				fwrite($fp, ")");
			}
			else
				fwrite($fp, "\"$key\"");
			fwrite($fp, ";\n");
		}
		return;
	}

	private function	write_fk($fp, $properties)
	{
		if (isset($properties['fk']))
		{
			fwrite($fp, "	protected	\$_referenceMap		= array(");
			$i = 0;
			$len = sizeof($properties['fk']) - 1;
			foreach ($properties['fk'] as $property => $key)
			{
				fwrite($fp, "'$property'	=> array('columns' => '".$key['columns']."',\n");
				fwrite($fp, "																	 'refTableClass' => '".$key['refTableClass']."',\n");
				fwrite($fp, "																	 'refColumns' => '".$key['refColumns']."')");
				if ($i != $len)
					fwrite($fp, ",\n											");
				$i++;
			}
			fwrite($fp, ");\n");
		}
		return;
	}
	
	private function 	write_dependentTable($fp, $properties)
	{
		if (isset($properties['dt']))
		{
			fwrite($fp, "	protected	\$_dependentTables	= ");
			if (is_array($properties['dt']))
			{
				fwrite($fp, "array(");
				$i = 0;
				$len = sizeof($properties['dt']) - 1;
				foreach ($properties['dt'] as $dt)
				{
					fwrite($fp, "\"$dt\"");
					if ($i != $len)
						fwrite($fp, ", ");
					$i++;
				}
				fwrite($fp, ")");
			}
			else
				fwrite($fp, "\"$dt\"");
			fwrite($fp, ";\n");
		}		
		return;
	}

	private function	write_separator($fp)
	{
		fwrite($fp, "\n");
		fwrite($fp, "	/** End of auto-generated code - /!\ DO NOT REMOVE THIS LINE /!\ */\n");
		fwrite($fp, "	/** BE CAREFUL : write your own code starting here, NOT before! */\n");
		return;
	}
	
	private function	write_methodes($fp, $table, $properties)
	{
		// getAll
		$from['table'] = strtolower($table);
		$from['alias'] = substr($from['table'], 0, 2);
		fwrite($fp, "	public function 	getAll()\n");
		fwrite($fp, "	{\n");
		fwrite($fp, "		\$select = \$this->select();\n");
		fwrite($fp, "		\$select->setIntegrityCheck(false)\n");
		fwrite($fp, "			   ->from(array('".$from['alias']."' => '".$from['table']."'))");
		if (isset($properties['fk']) == false)
			fwrite($fp, ";\n");
		else
		{
			fwrite($fp, "\n");
			$i = 0;
			$len = sizeof($properties['fk']) - 1;
			foreach ($properties['fk'] as $property => $key)
			{
				$to['table'] = strtolower($key['refTableClass']);
				$to['alias'] = substr($to['table'], 0, 2);
				fwrite($fp, "			   ->join(array('".$to['alias']."' => '".$to['table']."'), '".$from['alias'].".".$key['refColumns']." = ".$to['alias'].".".$key['refColumns']."')");
				if ($i != $len)
					fwrite($fp, "\n");
				$i++;
			}
			fwrite($fp, ";\n");
		}
		fwrite($fp, "		return (\$this->fetchAll(\$select));\n");
		fwrite($fp, "	}\n");
		return;
	}

	/**
	 * Gettors
	 */
	public function	getErrors() { return ($this->_errors); }
	public function	getFiles() { return ($this->_files); }
}

Zend/Generator/Exception.php

require_once('Zend/Exception.php');

class Zend_Generator_Exception extends Zend_Exception
{
}

Zend/Generator/Orm/Abstract.php

require_once('Zend/Db.php');
require_once('Zend/Db/Table.php');

abstract class Zend_Generator_Orm_Abstract
{
}

Zend/Generator/Orm/Exception.php

require_once('Zend/Generator/Exception.php');

class Zend_Generator_Orm_Exception extends Zend_Generator_Exception
{
}

Page Operations

Browse Space

Zend_Generator_Orm - Thomas VEQUAUD

Labels

Zend Framework: Zend_Generator_Orm Component Proposal

Table of Contents

1. Overview

English

Français

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

English

Français

Acceptance criteria

4. Dependencies on Other Framework Components

5. Theory of Operation

6. Milestones / Tasks

7. Class Index

8. Use Cases

9. Class Skeletons