CLI Environtment introduction

The CLI environtments are environtments executed directly on the OS shell. It’s name, CLI, is an acronym of Command Line Interface and are used for specific tasks execution. For this case, both tools have their own CLI tool: the Zend Tool by Zend Framework and the Doctrine CLI by Doctrine 2. Both CLI tools, are intended for code generation and for agilize web application maintenance tasks. For example: the creation of a Zend Framework application with its specific layout, the generation of the different domain model classes of Zend_Db by the Zend Tool or the Doctrine 2 entities, repositories and proxies generation.

Firsts steps. Understanding Zend Tool internals

Zend Tool, consists of several components to make easier the task integration on its context. On one hand there is the Zend_Tool_Framework family components which broadly provides the integration of web application independent tasks. For example, If we have to design a task that provides an entrypoint to the system cron without using web application resources, probably the best way will be using the Zend_Tool_Framework. However, if the task, we have to design, depends in some point on a resource of the web application, sure It will need to know about web application aspects. And this can be done with the Zend_Tool_Project family components (wich is the component that I will use, right here and right now).

Once the tasks have been designed and implemented, Zend Tool must be noticed about of its presence by the .zf.ini file, located on the user home.

Music, maestro!

On this post I’m going to describe, the creation of two tasks that will be linked to a Zend Framework web application with Doctrine 2 integrated as O/RM. This two tasks, will be responsible primarily to configure the Zend Application to be able to execute Doctrine 2 without problems (I have explained how on my previous post, you can check it a here) and to generate several useful files for its execution (proxies and repositories).

Analyzing a bit the Zend Tool Project and the Doctrine 2 CLI architecture we are going to write an abstract class that will be useful to prepare all the Doctrine 2 environment and it can be extended to create diferent provider tasks.

<?php
/**
 * File located at /library/Doctrine/Zend/Tool/Project/Provider/Abstract.php
 */

require_once 'Zend/Tool/Project/Provider/Abstract.php';
require_once 'Doctrine/Common/ClassLoader.php';

abstract class Doctrine_Zend_Tool_Project_Provider_Abstract
    extends Zend_Tool_Project_Provider_Abstract
{
    /**
     * A class property to hold the Zend_Tool_Project_Profile instance.
     * @var Zend_Tool_Project_Profile
     */
    protected $_profile;
    
    /**
     * The application.ini config file
     * @var Zend_Config_Ini
     */
    protected $_config;
    
    /**
     * The path to the application.ini
     * @var string
     */
    protected $_appConfigFilePath;
    
    /**
     * The path to the application directory
     * @var string
     */
    protected $_appPath;
    
    /**
     * The target section of the application.ini we want to work on
     * @var string
     */
    protected $_sectionName;
    
    /**
     * The Doctrine CLI instance, ready to execute tasks
     * @var Symfony\Component\Console\Application
     */
    protected $_doctrineCli = NULL;
    
    /**
     * Prepares Doctrine 2 for task performing, with the application.ini stuff
     * @return \Symfony\Component\Console\Application $cli
     */
    protected function _prepare($sectionName = 'production')
    {
    	if (is_null($this -> _doctrineCli)) {
    		// Load the project profile (.zfproject.xml)
	        $this -> _profile = $this -> _loadProfile(self::NO_PROFILE_THROW_EXCEPTION);
	        $appConfigFileResource = $this -> _profile -> search('applicationConfigFile');
	                
	        if ($appConfigFileResource == FALSE) {
	            throw new Zend_Tool_Project_Exception('A project with an application config file is required to use this provider.');
	        }
	        
	        $this -> _appConfigFilePath = $appConfigFileResource -> getPath();
	        
	        $appDirResource = $this -> _profile -> search('applicationDirectory');
	        $this -> _appPath = $appDirResource -> getPath();
	        
	        // This define it's important in order to work with the application.ini, since it's paths are configured
	        // with the APPLICATION_PATH constants. So define it just before instance the Zend_Config_Ini.
	        define('APPLICATION_PATH', $this -> _appPath);
	        $this -> _config = new Zend_Config_Ini($this -> _appConfigFilePath);
	        
	        $this -> _sectionName = $sectionName;
	        
	        if (!isset($this -> _config -> {$this -> _sectionName})) {
	            throw new Zend_Tool_Project_Exception('The config does not have a ' . $this -> _sectionName . ' section.');
	        }
	        
	        /**
	         * Maybe at this point doctrine isn't configured on the application.ini, do all this stuff only if
	         * configured
	         */
	        if (isset($this -> _config -> {$this -> _sectionName} -> resources -> doctrine)) {
		        $doctrineConsoleHelperSet = $this -> _getDoctrineConsoleHelperSet();
		        $this -> _doctrineCli = new \Symfony\Component\Console\Application('Doctrine Command Line Interface', Doctrine\ORM\Version::VERSION);
				$this -> _doctrineCli -> setCatchExceptions(TRUE);
				$this -> _doctrineCli -> setHelperSet($doctrineConsoleHelperSet);
				$this -> _doctrineCli -> addCommands(array(
				    new \Doctrine\DBAL\Tools\Console\Command\RunSqlCommand(),
				    new \Doctrine\DBAL\Tools\Console\Command\ImportCommand(),
				    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()
				));

				return $this -> _doctrineCli;
			}
		}
    }
    
    /**
     * Builds the Doctrine 2 Entity Manager object, and the helper set, needed by the
     * Doctrine 2 Console.
     * @return \Symfony\Component\Console\Helper\HelperSet $helperSet
     */
    private function _getDoctrineConsoleHelperSet()
    {
    	$classLoader = new \Doctrine\Common\ClassLoader('Doctrine');
		$classLoader->register();
		
		$classLoader = new \Doctrine\Common\ClassLoader('Symfony', 'Doctrine');
		$classLoader->register();
		
    	$classLoader = new \Doctrine\Common\ClassLoader('Application\Models', dirname(APPLICATION_PATH));
		$classLoader->register();
		
		$classLoader = new \Doctrine\Common\ClassLoader('Application\Proxies', dirname(APPLICATION_PATH));
		$classLoader->register();
		
		$classLoader = new \Doctrine\Common\ClassLoader('Application\Repositories', dirname(APPLICATION_PATH));
        $classLoader->register();
		
		$entityManager = $this -> _buildDoctrineEntityManager();
		return new \Symfony\Component\Console\Helper\HelperSet(array(
            'db' => new \Doctrine\DBAL\Tools\Console\Helper\ConnectionHelper($entityManager->getConnection()),
            'em' => new \Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper($entityManager) 
        ));
    }
    
    /**
     * Builds the EntityManager for Doctrine 2
     * @return \Doctrine\ORM\EntityManager
     */
    private function _buildDoctrineEntityManager()
    {
    	$config = new \Doctrine\ORM\Configuration();
		$cache = new \Doctrine\Common\Cache\ArrayCache();
		$config -> setMetadataCacheImpl($cache);
		$config -> setMetadataDriverImpl(\Doctrine\ORM\Mapping\Driver\AnnotationDriver::create(array(
            $this -> _config -> {$this -> _sectionName} -> resources -> doctrine -> entitiesPath
		)));
		$config -> setProxyDir($this -> _config -> {$this -> _sectionName} -> resources -> doctrine -> proxiesPath);
		$config -> setProxyNamespace('Application\Proxies');
		$config -> setAutoGenerateProxyClasses(TRUE);
		
		return \Doctrine\ORM\EntityManager::create($this -> _config -> {$this -> _sectionName} -> resources -> doctrine -> connection -> toArray(), $config);
    }
    
    /**
     * This method will be responsible for running any task on the Doctrine 2 CLI
     * Usage:
     *      
     *     $this -> _run(array(
     *         'command' => 'orm:generate-entities',
     *         'dest-path' => '/application/models'
     *     ), 'production');
     *     
     * @param array $arguments The task arguments
     * @param string $sectionName
     * @throws Zend_Tool_Project_Exception
     */
    protected function _run(array $arguments, $sectionName = 'production')
    {
    	if (is_null($this -> _doctrineCli)) {
            $doctrineCli = $this -> _prepare($sectionName);
    	} else {
    		$doctrineCli = $this -> _doctrineCli;
    	}
    	
        if (!is_null($doctrineCli)) {
            $consoleOutput = new \Symfony\Component\Console\Output\ConsoleOutput();
            $consoleOutput -> setDecorated(TRUE);
            $doctrineCli -> run(new \Symfony\Component\Console\Input\ArrayInput($arguments), $consoleOutput);
        } else {
        	throw new Zend_Tool_Project_Exception('Doctrine has not been configured on this project. Run first, the task configure on the doctrine-config provider.');
        }
    }
}

This abstract class will allow us to execute Doctrine 2 CLI tasks by the options defined on the application.ini file. So then, we define the following tasks

Provider to configure Doctrine 2

<?php

/**
 * File 'Doctrine/Zend/Tool/Project/Provider/DoctrineConfigProvider.php
 */
require_once 'Doctrine/Zend/Tool/Project/Provider/Abstract.php';

class Doctrine_Zend_Tool_Project_Provider_DoctrineConfigProvider
    extends Doctrine_Zend_Tool_Project_Provider_Abstract
{
	/**
	 * This task configures Doctrine environtment on the application.ini.
	 * Usage:
	 *     
	 *     > zf config doctrine-provider \
	 *       'connection[driver]=pdo_sqlite&connection[path]=APPLICATION_PATH "/../data/db/database-dev"' \
	 *       development
	 * 
	 * The available key configurations are as follows:
	 *     · connection: an array with all the key configs needed to configure a doctrine dbal connection
	 *       see http://www.doctrine-project.org/projects/dbal/2.0/docs/reference/configuration/en#configuration for more info
	 *     · entitiesPath: The path where entities will reside
	 *     · proxiesPath: The path where proxies will reside
	 *     · repositoriesPath: The path where repositories will reside
	 *     · cacheClass: The class used to act as a object cache (One from \Doctrine\Common\Cache)
	 * @param string $connectionQueryString
	 * @param string $sectionName
	 * @throws Zend_Tool_Project_Exception
	 */
	public function config($connectionQueryString, $sectionName = 'production')
	{
		$this -> _prepare($sectionName);
		parse_str($connectionQueryString, $options);
		if (isset($options['connection']) && isset($options['connection']['driver']) && method_exists($this, "_{$options['connection']['driver']}")) {
			$method = "_{$options['connection']['driver']}";
			$this -> $method($options, $sectionName);
		} else {
			throw new Zend_Tool_Project_Exception('Unsupported driver (' . $options['connection']['driver'] . ')');
		}
	}
	
	/**
	 * A method to configure the connection to the database. To implement more connections,
	 * define for exemple "_pdo_mysql" or "_pdo_pgsql" with the same signature as this method.
	 * This method only validates the options of the connection. The real implementation is on
	 * the "_setConfig" method.
	 * @param array $options The options defined
	 * @param unknown_type $sectionName
	 * @throws Zend_Tool_Project_Exception
	 */
	protected function _pdo_sqlite(array $options, $sectionName = 'production')
	{
		// Build the options array
		if (!isset($options['connection']['path']) && !isset($options['connection']['memory'])) {
            throw new Zend_Tool_Project_Exception('Malformed connection string');
        }
        
        $this -> _setConfig($options, $sectionName);
	}
	
	/**
	 * This method serializes all the config options from Doctrine 2 CLI to the
	 * application.ini
	 * @param array $options The defined options
	 * @param string $sectionName
	 */
	protected function _setConfig(array $options, $sectionName = 'production')
	{
		$doctrineItem = array(
            'resources' => array(
                'doctrine' => array()
            )
        );
        
        $doctrineItem['resources']['doctrine']['entitiesPath'] = isset($options['entitiesPath']) ? $options['entitiesPath'] : 'APPLICATION_PATH "/models"';
        $doctrineItem['resources']['doctrine']['proxiesPath'] = isset($options['proxiesPath']) ? $options['proxiesPath'] : 'APPLICATION_PATH "/proxies"';
        $doctrineItem['resources']['doctrine']['repositoriesPath'] = isset($options['repositoriesPath']) ? $options['repositoriesPath'] : 'APPLICATION_PATH "/repositories"';
        $doctrineItem['resources']['doctrine']['cacheClass'] = isset($options['cacheClass']) ? $options['cacheClass'] : 'Doctrine\Common\Cache\ApcCache';
        $doctrineItem['resources']['doctrine']['connection'] = $options['connection'];
        $appConfigFileResource = $this -> _profile -> search('applicationConfigFile');
        $appConfigFileResource -> addItem($doctrineItem, $sectionName, NULL);
        $appConfigFileResource -> create();
        $this -> _registry -> getResponse() -> appendContent("A new Doctrine 2 configuration for the section $sectionName, has been stablished.");
	}
}

Entities, Proxies and Repositories generation Provider

<?php

/**
 * File /Doctrine/Zend/Tool/Project/Provider/DoctrineOrmProvider.php
 */
require_once 'Doctrine/Zend/Tool/Project/Provider/Abstract.php';

class Doctrine_Zend_Tool_Project_Provider_DoctrineOrmProvider
    extends Doctrine_Zend_Tool_Project_Provider_Abstract
{
	/**
	 * A task to generate the entity repositories on a defined path
	 * @param string $destPath
	 * @param string $sectionName
	 */
	public function generateRepositories($destPath, $sectionName = 'production')
	{
		$this -> _run(array(
            'command' => 'orm:generate-repositories',
            'dest-path' => $destPath
		));
	}
	
	/**
	 * A task to generate proxies on a defined path
	 * @param string $destPath
	 * @param string $sectionName
	 */
	public function generateProxies($destPath, $sectionName = 'production')
	{
		$this -> _run(array(
            'command' => 'orm:generate-proxies',
            'dest-path' => $destPath
		));
	}
	
	/**
	 * A task to generate entities on a defined path
	 * @param string $destPath
	 * @param string $sectionName
	 */
    public function generateEntities($destPath, $sectionName = 'production')
    {
        $this -> _run(array(
            'command' => 'orm:generate-entities',
            'dest-path' => $destPath
        ));
    }
}

Concluding

The only thing to do from here, is to notice the Zend Tool about the presence of this tasks in our CLI environment. For this, as I said before, we’re going to use the “.zf.ini” file, located on our user’s home directory. We edit this file and update the include_path to point to the library directory of our project and also add the recently created classes.

php.include_path = ".:/path/to/my/zend/framework/project/library:/usr/local/zend/share/pear"
basicloader.classes.0 = "Doctrine_Zend_Tool_Project_Provider_DoctrineConfigProvider"
basicloader.classes.1 = "Doctrine_Zend_Tool_Project_Provider_DoctrineOrmProvider"

With this we should be able to execute Doctrine 2 CLI tasks, by the Zend Tool.