christian.soronellas

Introducción a los entronos de CLI

Los entornos CLI son entornos ejecutados directamente en el shell del sistema operativo. Su nombre CLI es acrónimo de Command Line Interface (Interfaz de Linea de Comandos) y son usados para la ejecución de tareas muy especificas. Para el caso que nos ocupa, ambas herramientas disponen de sus respectivas herramientas CLI: la Zend Tool por parte de Zend Framework y la Doctrine CLI por parte de Doctrine 2. Ambas herramientas CLI, están pensadas para la generación de código y para aligerar tareas de mantenimiento de aplicaciones web. Por ejemplo: la creación de una aplicación web Zend Framework con su layout especifico, la creación de las distintas clases del modelo de dominio de Zend_Db por parte de Zend Tool o la creación de Entities, Proxies o Repositories en Doctrine 2.

Primeros pasos. Entendiendo las entrañas de Zend Tool

Zend Tool, consta de varios componentes que facilitan la integración de tareas en su contexto. Por una parte está la familia de componentes Zend_Tool_Framework que, a grandes rasgos, facilita la integración de tareas independientes de aplicaciones web. Por ejemplo si tuviéramos que diseñar una tarea que sirviera cómo interface al cron del sistema (por poner un ejemplo) sin que este debiera usar recursos de la aplicación web, muy probablemente la mejor manera sea usando Zend_Tool_Framework. En cambio si la tarea que debemos diseñar depende en algún momento de algún recurso de la aplicación web, seguro necesitará conocer determinados aspectos de la misma. Y esto se puede conseguir a través de la familia de componentes de Zend_Tool_Project (qué es el componente que vamos a usar aquí y ahora).

Una vez ya con las tareas diseñadas e implementadas, se le debe notificar a la Zend Tool de la existencia de las mismas a través del archivo .zf.ini situado dentro del espacio del usuario que ejecuta el shell.

Música, maestro!

En este artículo voy a detallar, la creación de dos tareas que se van a vincular a una aplicación web Zend Framework con Doctrine 2 integrado cómo O/RM. Estas dos tareas, se van a encargar principalmente de configurar Zend Application para que pueda ejecutar Doctrine 2 sin problemas (el cómo lo expliqué en mi anterior artículo, puedes verlo aquí) y de generar diferentes archivos útiles para su ejecución (proxies y repositories).

Analizando un poco qué arquitectura de tanto Zend Tool Project cómo de Doctrine 2 CLI vamos a plantear una clase genérica que sirva para preparar todo el entorno de Doctrine 2 y se pueda extender para crear diferentes providers de tareas.

<?php
/**
 * Archivo ubicado en /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.');
        }
    }
}

Esta clase abstracta nos va a permitir ejecutar tareas del CLI de Doctrine a través de las opciones definidas en al archivo application.ini. Así de este modo definimos las siguientes tareas

Provider para configurar Doctrine 2

<?php

/**
 * Archivo '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.");
	}
}

Provider para la generación de Entities, Proxies y Repositories

<?php

/**
 * Archivo /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
        ));
    }
}

Concluyendo

Llegados hasta aquí sólo falta notificar a Zend Tool de la existencia de estas tareas en nuestro entorno CLI. Para ello, cómo he dicho antes vamos a usar el archivo “.zf.ini” situado en nuestra carpeta de usuario del sistema. Editamos dicho archivo y le modificamos el include_path para que apunte también al directorio library de nuestro proyecto y además le añadimos las clases que acabamos de crear.

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"

Con esto deberíamos ser capaces de ejecutar CLI tasks de Doctrine 2, a través de la Zend Tool