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 2009: Creation of the proposal 0.2 - 27 April 2009: Attachment added (source code in a zip file) 0.3 - 27 April 2009: Sources updated 0.4 - 28 April 2009: Requirements and milestones added 0.5 - 30 April 2009: Class squeletons added 0.6 - 02 May 2009: Use cases added 0.7 - 14 May 2009: Use cases updated 0.8 - 26 January 2010: New version released (wiki revision: 33)

Within Zend Framework, you need to define classes 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.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

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.

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.

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 :

/**
 * My ORM controller
 */
class OrmController extends Zend_Controller_Action
{
	/**
	 * Default action
	 */
	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. Blank 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

class Zend_Orm extends Zend_Generator_Orm_Abstract
{
	/**
	 * Path to the models direcotry
	 * @var	string 
	 */
	protected	$_models_path = null;

	/**
	 * Tables primary and foreign keys
	 * @var array
	 */
	protected	$_keys	= null;

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

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

	/**
	 * Display Zend_Debug dumps
	 * @var boolean
	 */
	public		$debug		= true;


	/**
	 * Constructor
	 * 
	 * @param	$models Path to the models directory
	 * @return	void
	 */
	public function		__construct($models = APPLICATION_MODELS)
	{
		// Models path
		$this->setModelsPath($models);

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

	/**
	 * setModelsPath
	 * Set the path to the models directory
	 * 
	 * @param	string $path
	 * @return	void
	 */
	public function		setModelsPath($path)
	{
		$this->models_path = $path;
		return;		
	}

	/**
	 * getModelsPath
	 * Get the path to the models directory
	 * 
	 * @return	void
	 */
	public function		getModelsPath()
	{
		return ($this->models_path);		
	}

	/**
	 * getKeys
	 * Get primary and foreign keys
	 * 
	 * @return	array
	 */
	protected function	getKeys()
	{		
		if ($this->_keys === null)
		{
			$this->_keys = $this->getPk();
		}
		return ($this->_keys);
	}
	
	

	/**
	 * get Primary Keys
	 * Aggregates data get from database
	 *
	 * @return	an array of data about the database architecture :
	 * 			- dependent tables,
	 * 			- primary and foreign keys,
	 *			- reference map,
	 * 			etc.
	 */
	protected function	getPk()
	{
		foreach ($this->getTablesList() as $table)
		{
			$table = strtolower($table);
			$infos = $this->getDb()->describeTable($table);
			foreach ($infos as $field => $info)
			{
				if ($info['PRIMARY'] === true && $info['IDENTITY'] === true)
				{
					$this->_keys[$table]['pk'][$info['PRIMARY_POSITION']] = $field;
					$this->getFk($table, $field);
				}
			}
		}
		return ($this->_keys);
	}
	
	/**
	 * getFk
	 * get Foreign Keys
	 * 
	 * @return	void
	 */
	protected function	getFk($ftable, $fk)
	{
		foreach ($this->getTablesList() as $ptable)
		{
			if ($ftable != $ptable)
			{
				$infos = $this->getDb()->describeTable($ptable);
				foreach ($infos as $field => $info)
				{
					if ($field == $fk)
					{
						if ($info['PRIMARY'] === false && $info['IDENTITY'] === false)
						{
							// Dependent Table
							$this->_keys[$ftable]['dt'][] = $ptable;
							
							// Reference tables
							$role = ucfirst($ptable)."To".ucfirst($ftable);
							$this->_keys[$ptable]['fk'][$role]['columns']		= $field;
							$this->_keys[$ptable]['fk'][$role]['refTableClass']	= ucfirst($ftable);
							$this->_keys[$ptable]['fk'][$role]['refColumns']	= $field;
						}
						elseif ($info['PRIMARY'] === true && $info['IDENTITY'] === false)
						{
							// Dependent Table
							$this->_keys[$ftable]['dt'][] = $ptable;
							
							// Reference tables
							$role = ucfirst($ptable)."To".ucfirst($ftable);
							$this->_keys[$ptable]['fk'][$role]['columns']		= $field;
							$this->_keys[$ptable]['fk'][$role]['refTableClass']	= ucfirst($ftable);
							$this->_keys[$ptable]['fk'][$role]['refColumns']	= $field;
						}
					}
				}
			}
		}
		return;
	}


	/**
	 * create
	 * Get database specifications and computes data
	 * Create database classes
	 * 
	 * @return	void	
	 */
	public function		create()
    {
		foreach ($this->getKeys() as $table => $properties)
		{
			$table		= ucfirst($table);
			$fileName	= $this->getModelsPath() . DIRECTORY_SEPARATOR . $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;
	}


	/**
	 * update
	 * Get database specifications and computes data
	 * Update database classes
	 * 
	 * @return	void
	 */
	public function		update()
    {
		foreach ($this->getKeys() as $table => $properties)
		{
			$table		= ucfirst($table);
			$fileName	= $this->getModelsPath() . DIRECTORY_SEPARATOR . $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;
	}

	/**
	 * createDbClass
	 * 
	 * @param	resource $fp
	 * @param	string $table
	 * @param	array $properties
	 * @return	void
	 */
	protected 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;
	}

	/**
	 * write_header
	 * 
	 * @param	resource $fp
	 * @param	string $table
	 * @return	void
	 */
	protected 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, " * @see		Zend_Db_Table_Abstract\n");
		fwrite($fp, " * @author	Auto-generated with Zend_Generator_Orm\n");
		fwrite($fp, " */\n");
		fwrite($fp, "\n");
		return;
	}

	/**
	 * write_pk
	 * 
	 * @param	resource $fp
	 * @param	array $properties
	 * @return	void
	 */
	protected function	write_pk($fp, $properties)
	{
		if (isset($properties['pk']))
		{
			fwrite($fp, '	protected	$_primary			= ');
			if (is_array($properties['pk']))
			{
				fwrite($fp, 'array(\'');
				fwrite($fp, implode("', '", $properties['pk']));
				fwrite($fp, '\')');
			}
			else
			{
				fwrite($fp, "\"$key\"");
			}
			fwrite($fp, ";\n");
		}
		return;
	}

	/**
	 * write_fk
	 * 
	 * @param	resource $fp
	 * @param	array $properties
	 * @return	void
	 */
	protected 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;
	}

	/**
	 * write_dependentTable
	 * 
	 * @param	resource $fp
	 * @param	array $properties
	 * @return	void
	 */
	private function 	write_dependentTable($fp, $properties)
	{
		if (isset($properties['dt']))
		{
			fwrite($fp, '	protected	$_dependentTables	= ');
			if (is_array($properties['dt']))
			{
				fwrite($fp, 'array(\'');
				fwrite($fp, implode("', '", $properties['dt']));
				fwrite($fp, '\')');
			}
			else
			{
				fwrite($fp, "\"$dt\"");
			}
			fwrite($fp, ";\n");
		}		
		return;
	}

	/**
	 * write_separator
	 * 
	 * @param	resource $fp
	 * @return	void
	 */
	protected 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;
	}
	
	/**
	 * write_methodes
	 * 
	 * @param	resource $fp
	 * @param	string $table
	 * @param	array $properties
	 * @return	void
	 */
	protected 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, "		\$select->from(array('".$from['alias']."' => '".$from['table']."'));\n");
		if (isset($properties['fk']))
		{
			foreach ($properties['fk'] as $key)
			{
				$to['table'] = strtolower($key['refTableClass']);
				$to['alias'] = substr($to['table'], 0, 2);
				fwrite($fp, "		\$select->join(array('".$to['alias']."' => '".$to['table']."'), '".$from['alias'].".".$key['refColumns']." = ".$to['alias'].".".$key['refColumns']."');\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