diff --git a/lib/Doctrine/ORM/Tools/Cli.php b/lib/Doctrine/ORM/Tools/Cli.php
index ec933fe59..8bc1a3a84 100644
--- a/lib/Doctrine/ORM/Tools/Cli.php
+++ b/lib/Doctrine/ORM/Tools/Cli.php
@@ -22,6 +22,8 @@
namespace Doctrine\ORM\Tools;
use Doctrine\Common\Util\Inflector,
+ Doctrine\ORM\Tools\Cli\AbstractPrinter,
+ Doctrine\ORM\Tools\Cli\AbstractTask,
Doctrine\ORM\Tools\Cli\Printer;
/**
@@ -30,7 +32,7 @@ use Doctrine\Common\Util\Inflector,
* To include a new Task support, create a task:
*
* [php]
- * class MyProject\Tools\Cli\Tasks\MyTask extends Doctrine\ORM\Tools\Cli\Task {
+ * class MyProject\Tools\Cli\Tasks\MyTask extends Doctrine\ORM\Tools\Cli\AbstractTask {
* public function run();
* public function basicHelp();
* public function extendedHelp();
@@ -59,7 +61,12 @@ use Doctrine\Common\Util\Inflector,
class Cli
{
/**
- * @var Cli\AbstractPrinter CLI Printer instance
+ * @var ORM\Configuration Configuration
+ */
+ //private $_configuration = null;
+
+ /**
+ * @var AbstractPrinter CLI Printer instance
*/
private $_printer = null;
@@ -68,8 +75,12 @@ class Cli
*/
private $_tasks = array();
-
- public function __construct($printer = null)
+ /**
+ * The CLI processor of tasks
+ *
+ * @param AbstractPrinter $printer CLI Output printer
+ */
+ public function __construct(AbstractPrinter $printer = null)
{
//$this->_printer = new Printer\Normal();
$this->_printer = $printer ?: new Printer\AnsiColor();
@@ -83,6 +94,18 @@ class Cli
));
}
+ /**
+ * Add a collection of tasks to the CLI.
+ * To include them, just call the method with the following structure:
+ *
+ * [php]
+ * $cli->addTasks(array(
+ * 'my-custom-task' => 'MyProject\Cli\Tasks\MyCustomTask',
+ * ...
+ * ));
+ *
+ * @param array $tasks CLI Tasks to be included
+ */
public function addTasks($tasks)
{
foreach ($tasks as $name => $class) {
@@ -90,6 +113,16 @@ class Cli
}
}
+ /**
+ * Add a single task to CLI.
+ * Example of inclusion support to a single task:
+ *
+ * [php]
+ * $cli->addTask('my-custom-task', 'MyProject\Cli\Tasks\MyCustomTask');
+ *
+ * @param string $name CLI Task name
+ * @param string $class CLI Task class (FQCN - Fully Qualified Class Name)
+ */
public function addTask($name, $class)
{
// Convert $name into a class equivalent
@@ -99,6 +132,12 @@ class Cli
$this->_tasks[$name] = $class;
}
+ /**
+ * Processor of CLI Tasks. Handles multiple task calls, instantiate
+ * respective classes and run them.
+ *
+ * @param array $args CLI Arguments
+ */
public function run($args = array())
{
// Remove script file argument
@@ -121,18 +160,16 @@ class Cli
$taskName = $this->_processTaskName($taskData['name']);
$taskArguments = $taskData['args'];
- // Always include supported Tasks as argument
- $taskArguments['availableTasks'] = $this->_tasks;
-
// Check if task exists
if (isset($this->_tasks[$taskName]) && class_exists($this->_tasks[$taskName], true)) {
// Instantiate and execute the task
$task = new $this->_tasks[$taskName]();
+ $task->setAvailableTasks($this->_tasks);
$task->setPrinter($this->_printer);
$task->setArguments($taskArguments);
if (isset($taskArguments['help']) && $taskArguments['help']) {
- $task->extendedHelp(); // User explicitly asked for task help
+ $task->extendedHelp(); // User explicitly asked for help option
} else if ($this->_isTaskValid($task)) {
$task->run();
} else {
@@ -248,9 +285,15 @@ class Cli
return $preparedArgs;
}
- private function _isTaskValid($task)
+ /**
+ * Checks if CLI Task is valid based on given arguments.
+ *
+ * @param AbstractTask $task CLI Task instance
+ */
+ private function _isTaskValid(AbstractTask $task)
{
- // TODO: Should we check for required and optional arguments here?
+ // TODO: Should we change the behavior and check for
+ // required and optional arguments here?
return $task->validate();
}
}
\ No newline at end of file
diff --git a/lib/Doctrine/ORM/Tools/Cli/AbstractPrinter.php b/lib/Doctrine/ORM/Tools/Cli/AbstractPrinter.php
index f8199c796..f5d6e7a1b 100644
--- a/lib/Doctrine/ORM/Tools/Cli/AbstractPrinter.php
+++ b/lib/Doctrine/ORM/Tools/Cli/AbstractPrinter.php
@@ -21,14 +21,41 @@
namespace Doctrine\ORM\Tools\Cli;
+/**
+ * CLI Output Printer.
+ * Abstract class responsable to provide basic methods to support output
+ * styling and excerpt limited by output margin.
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link www.doctrine-project.org
+ * @since 2.0
+ * @version $Revision$
+ * @author Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author Jonathan Wage <jonwage@gmail.com>
+ * @author Roman Borschel <roman@code-factory.org>
+ */
abstract class AbstractPrinter
{
+ /**
+ * @var resource Output Stream
+ */
protected $_stream;
+ /**
+ * @var integer Maximum column size
+ */
protected $_maxColumnSize;
+ /**
+ * @var array Array of Styles
+ */
protected $_styles;
+ /**
+ * Creates an instance of Printer
+ *
+ * @param resource $stream Output Stream
+ */
public function __construct($stream = STDOUT)
{
$this->_stream = $stream;
@@ -37,6 +64,10 @@ abstract class AbstractPrinter
$this->_initStyles();
}
+ /**
+ * Initializes Printer Styles
+ *
+ */
protected function _initStyles()
{
// Defines base styles
@@ -49,6 +80,18 @@ abstract class AbstractPrinter
));
}
+ /**
+ * Add a collection of styles to the Printer.
+ * To include them, just call the method with the following structure:
+ *
+ * [php]
+ * $printer->addStyles(array(
+ * 'ERROR' => new Style('BLACK', 'DEFAULT', array('BOLD' => true)),
+ * ...
+ * ));
+ *
+ * @param array $tasks CLI Tasks to be included
+ */
public function addStyles($styles)
{
foreach ($styles as $name => $style) {
@@ -56,11 +99,26 @@ abstract class AbstractPrinter
}
}
+ /**
+ * Add a single Style to Printer.
+ * Example of inclusion to support a new Style:
+ *
+ * [php]
+ * $printer->addStyle('ERROR', new Style('BLACK', 'DEFAULT', array('BOLD' => true)));
+ *
+ * @param string $name Style name
+ * @param Style $style Style instance
+ */
public function addStyle($name, Style $style)
{
$this->_styles[strtoupper($name)] = $style;
}
+ /**
+ * Retrieves a defined Style.
+ *
+ * @return Style
+ */
public function getStyle($name)
{
$name = strtoupper($name);
diff --git a/lib/Doctrine/ORM/Tools/Cli/AbstractTask.php b/lib/Doctrine/ORM/Tools/Cli/AbstractTask.php
index b9e56acaa..a9108b085 100644
--- a/lib/Doctrine/ORM/Tools/Cli/AbstractTask.php
+++ b/lib/Doctrine/ORM/Tools/Cli/AbstractTask.php
@@ -21,36 +21,140 @@
namespace Doctrine\ORM\Tools\Cli;
+/**
+ * CLI Task.
+ * Provides basic methods and requires implementation of methods that
+ * each task should implement in order to correctly work.
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link www.doctrine-project.org
+ * @since 2.0
+ * @version $Revision$
+ * @author Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author Jonathan Wage <jonwage@gmail.com>
+ * @author Roman Borschel <roman@code-factory.org>
+ */
abstract class AbstractTask
{
+ /**
+ * @var AbstractPrinter CLI Output Printer
+ */
protected $_printer;
+
+ /**
+ * @var array CLI argument options
+ */
protected $_arguments;
+ /**
+ * @var array Available CLI tasks
+ */
+ protected $_availableTasks;
+
+ /**
+ * Defines a CLI Output Printer
+ *
+ * @param AbstractPrinter CLI Output Printer
+ */
public function setPrinter(AbstractPrinter $printer)
{
$this->_printer = $printer;
}
+ /**
+ * Retrieves currently used CLI Output Printer
+ *
+ * @return AbstractPrinter
+ */
public function getPrinter()
{
return $this->_printer;
}
+ /**
+ * Defines the CLI arguments
+ *
+ * @param array CLI argument options
+ */
public function setArguments($arguments)
{
$this->_arguments = $arguments;
}
+ /**
+ * Retrieves current CLI arguments
+ *
+ * @return array
+ */
public function getArguments()
{
return $this->_arguments;
}
+ /**
+ * Defines the available CLI tasks
+ *
+ * @param array Available CLI tasks
+ */
+ public function setAvailableTasks($availableTasks)
+ {
+ $this->_availableTasks = $availableTasks;
+ }
+
+ /**
+ * Retrieves the available CLI tasks
+ *
+ * @return array
+ */
+ public function getAvailableTasks()
+ {
+ return $this->_availableTasks;
+ }
+
+ /**
+ * Expose to CLI Output Printer the extended help of the given task.
+ * This means it should detail all parameters, options and the meaning
+ * of each one.
+ * This method is executed when user types in CLI the following command:
+ *
+ * [bash]
+ * ./doctrine task --help
+ *
+ */
abstract public function extendedHelp();
+ /**
+ * Expose to CLI Output Printer the basic help of the given task.
+ * This means it should only expose the basic task call. It is also
+ * executed when user calls the global help; so this means it should
+ * not pollute the Printer.
+ * Basic help exposure is displayed when task does not pass the validate
+ * (which means when user does not type the required options or when given
+ * options are invalid, ie: invalid option), or when user requests to have
+ * description of all available tasks.
+ * This method is executed when user uses the following commands:
+ *
+ * [bash]
+ * ./doctrine task --invalid-option
+ * ./doctrine --help
+ *
+ */
abstract public function basicHelp();
+ /**
+ * Assures the given arguments matches with required/optional ones.
+ * This method should be used to introspect arguments to check for
+ * missing required arguments and also for invalid defined options.
+ *
+ * @return boolean
+ */
abstract public function validate();
+ /**
+ * Safely execution of task.
+ * Each CLI task should implement this as normal flow execution of
+ * what is supposed to do.
+ *
+ */
abstract public function run();
}
\ No newline at end of file
diff --git a/lib/Doctrine/ORM/Tools/Cli/Printer/AnsiColor.php b/lib/Doctrine/ORM/Tools/Cli/Printer/AnsiColor.php
index 25fc9c2a9..5c434fceb 100644
--- a/lib/Doctrine/ORM/Tools/Cli/Printer/AnsiColor.php
+++ b/lib/Doctrine/ORM/Tools/Cli/Printer/AnsiColor.php
@@ -24,42 +24,65 @@ namespace Doctrine\ORM\Tools\Cli\Printer;
use Doctrine\ORM\Tools\Cli\AbstractPrinter,
Doctrine\ORM\Tools\Cli\Style;
+/**
+ * CLI Output Printer for ANSI Color terminal
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link www.doctrine-project.org
+ * @since 2.0
+ * @version $Revision$
+ * @author Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author Jonathan Wage <jonwage@gmail.com>
+ * @author Roman Borschel <roman@code-factory.org>
+ */
class AnsiColor extends AbstractPrinter
{
+ /**
+ * @inheritdoc
+ */
protected function _initStyles()
{
$this->addStyles(array(
- 'ERROR' => new Style('RED', 'WHITE', array('BOLD' => true)),
+ 'ERROR' => new Style('WHITE', 'RED', array('BOLD' => true)),
'INFO' => new Style('GREEN', 'DEFAULT', array('BOLD' => true)),
- 'COMMENT' => new Style('YELLOW', 'DEFAULT'),
+ 'COMMENT' => new Style('DEFAULT', 'YELLOW'),
'HEADER' => new Style('DEFAULT', 'DEFAULT', array('BOLD' => true)),
'NONE' => new Style(),
));
}
+ /**
+ * @inheritdoc
+ */
public function format($message, Style $style)
{
if ( ! $this->_supportsColor()) {
return $message;
}
- $str = $this->getForegroundString($style->getForeground())
- . $this->getBackgroundString($style->getBackground())
- . $this->getOptionsString($style->getOptions());
+ $str = $this->_getForegroundString($style->getForeground())
+ . $this->_getBackgroundString($style->getBackground())
+ . $this->_getOptionsString($style->getOptions());
$styleSet = ($str != '');
return $str . $message . ($styleSet ? chr(27) . '[0m' : '');
}
- public function getForegroundString($foreground)
+ /**
+ * Retrieves the ANSI string representation of requested color name
+ *
+ * @param string $background Background color name
+ * @return string
+ */
+ protected function _getBackgroundString($background)
{
- if (empty($foreground)) {
+ if (empty($background)) {
return '';
}
$esc = chr(27);
- switch ($foreground) {
+ switch ($background) {
case 'BLACK':
return $esc . '[40m';
case 'RED':
@@ -82,15 +105,21 @@ class AnsiColor extends AbstractPrinter
}
}
- public function getBackgroundString($background)
+ /**
+ * Retrieves the ANSI string representation of requested color name
+ *
+ * @param string $foreground Foreground color name
+ * @return string
+ */
+ protected function _getForegroundString($foreground)
{
- if (empty($background)) {
+ if (empty($foreground)) {
return '';
}
$esc = chr(27);
- switch ($background) {
+ switch ($foreground) {
case 'BLACK':
return $esc . '[30m';
case 'RED':
@@ -115,7 +144,13 @@ class AnsiColor extends AbstractPrinter
}
}
- public function getOptionsString($options)
+ /**
+ * Retrieves the ANSI string representation of requested options
+ *
+ * @param array $options Options
+ * @return string
+ */
+ protected function _getOptionsString($options)
{
if (empty($options)) {
return '';
@@ -157,7 +192,11 @@ class AnsiColor extends AbstractPrinter
return $str;
}
-
+ /**
+ * Checks if the current Output Stream supports ANSI Colors
+ *
+ * @return boolean
+ */
private function _supportsColor()
{
return DIRECTORY_SEPARATOR != '\\' &&
diff --git a/lib/Doctrine/ORM/Tools/Cli/Printer/Normal.php b/lib/Doctrine/ORM/Tools/Cli/Printer/Normal.php
index b387e914d..52eb8e4c6 100644
--- a/lib/Doctrine/ORM/Tools/Cli/Printer/Normal.php
+++ b/lib/Doctrine/ORM/Tools/Cli/Printer/Normal.php
@@ -24,8 +24,22 @@ namespace Doctrine\ORM\Tools\Cli\Printer;
use Doctrine\ORM\Tools\Cli\AbstractPrinter,
Doctrine\ORM\Tools\Cli\Style;
+/**
+ * CLI Output Printer for Normal terminal
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link www.doctrine-project.org
+ * @since 2.0
+ * @version $Revision$
+ * @author Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author Jonathan Wage <jonwage@gmail.com>
+ * @author Roman Borschel <roman@code-factory.org>
+ */
class Normal extends AbstractPrinter
{
+ /**
+ * @inheritdoc
+ */
public function format($message, Style $style)
{
return $message;
diff --git a/lib/Doctrine/ORM/Tools/Cli/Style.php b/lib/Doctrine/ORM/Tools/Cli/Style.php
index 67f225c4a..bb563c6bf 100644
--- a/lib/Doctrine/ORM/Tools/Cli/Style.php
+++ b/lib/Doctrine/ORM/Tools/Cli/Style.php
@@ -21,14 +21,39 @@
namespace Doctrine\ORM\Tools\Cli;
+/**
+ * CLI Output Style
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link www.doctrine-project.org
+ * @since 2.0
+ * @version $Revision$
+ * @author Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author Jonathan Wage <jonwage@gmail.com>
+ * @author Roman Borschel <roman@code-factory.org>
+ */
class Style
{
+ /**
+ * @var string Background color
+ */
private $_background;
+ /**
+ * @var string Foreground color
+ */
private $_foreground;
+ /**
+ * @var array Formatting options
+ */
private $_options = array();
+ /**
+ * @param string $foreground Foreground color name
+ * @param string $background Background color name
+ * @param array $options Formatting options
+ */
public function __construct($foreground = null, $background = null, $options = array())
{
$this->_foreground = strtoupper($foreground);
@@ -36,16 +61,31 @@ class Style
$this->_options = $options;
}
+ /**
+ * Retrieves the foreground color name
+ *
+ * @return string
+ */
public function getForeground()
{
return $this->_foreground;
}
+ /**
+ * Retrieves the background color name
+ *
+ * @return string
+ */
public function getBackground()
{
return $this->_background;
}
+ /**
+ * Retrieves the formatting options
+ *
+ * @return string
+ */
public function getOptions()
{
return $this->_options;
diff --git a/lib/Doctrine/ORM/Tools/Cli/Task/Help.php b/lib/Doctrine/ORM/Tools/Cli/Task/Help.php
index 130a07753..92697e0cc 100644
--- a/lib/Doctrine/ORM/Tools/Cli/Task/Help.php
+++ b/lib/Doctrine/ORM/Tools/Cli/Task/Help.php
@@ -23,8 +23,22 @@ namespace Doctrine\ORM\Tools\Cli\Task;
use Doctrine\ORM\Tools\Cli\AbstractTask;
+/**
+ * CLI Task to display available commands help
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link www.doctrine-project.org
+ * @since 2.0
+ * @version $Revision$
+ * @author Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author Jonathan Wage <jonwage@gmail.com>
+ * @author Roman Borschel <roman@code-factory.org>
+ */
class Help extends AbstractTask
{
+ /**
+ * @inheritdoc
+ */
public function extendedHelp()
{
$this->getPrinter()->write('help extended help' . PHP_EOL, 'HEADER');
@@ -34,6 +48,9 @@ class Help extends AbstractTask
$this->getPrinter()->write('help extended help' . PHP_EOL, 'NONE');
}
+ /**
+ * @inheritdoc
+ */
public function basicHelp()
{
$this->getPrinter()->write('help basic help' . PHP_EOL, 'HEADER');
@@ -42,12 +59,19 @@ class Help extends AbstractTask
$this->getPrinter()->write('help basic help' . PHP_EOL, 'COMMENT');
$this->getPrinter()->write('help basic help' . PHP_EOL, 'NONE');
}
-
+
+ /**
+ * @inheritdoc
+ */
public function validate()
{
return true;
}
+ /**
+ * Exposes the available tasks
+ *
+ */
public function run()
{
$this->getPrinter()->write('help run' . PHP_EOL, 'HEADER');
diff --git a/lib/Doctrine/ORM/Tools/Cli/Task/Version.php b/lib/Doctrine/ORM/Tools/Cli/Task/Version.php
index 01580013d..b7ae5b7ed 100644
--- a/lib/Doctrine/ORM/Tools/Cli/Task/Version.php
+++ b/lib/Doctrine/ORM/Tools/Cli/Task/Version.php
@@ -23,8 +23,22 @@ namespace Doctrine\ORM\Tools\Cli\Task;
use Doctrine\ORM\Tools\Cli\AbstractTask;
+/**
+ * CLI Task to display the doctrine version
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link www.doctrine-project.org
+ * @since 2.0
+ * @version $Revision$
+ * @author Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author Jonathan Wage <jonwage@gmail.com>
+ * @author Roman Borschel <roman@code-factory.org>
+ */
class Version extends AbstractTask
{
+ /**
+ * @inheritdoc
+ */
public function extendedHelp()
{
$this->getPrinter()->write('version extended help' . PHP_EOL, 'HEADER');
@@ -34,6 +48,9 @@ class Version extends AbstractTask
$this->getPrinter()->write('version extended help' . PHP_EOL, 'NONE');
}
+ /**
+ * @inheritdoc
+ */
public function basicHelp()
{
$this->getPrinter()->write('version basic help' . PHP_EOL, 'HEADER');
@@ -43,11 +60,18 @@ class Version extends AbstractTask
$this->getPrinter()->write('version basic help' . PHP_EOL, 'NONE');
}
+ /**
+ * @inheritdoc
+ */
public function validate()
{
return true;
}
+ /**
+ * Displays the current version of Doctrine
+ *
+ */
public function run()
{
$this->getPrinter()->write('version run' . PHP_EOL, 'HEADER');