Skip to content

D
doctrine-dbal
Commit 356887c8 authored by guilhermeblanco's avatar guilhermeblanco
Browse files
Options

[2.0] Added docblocks

parent fd89892c
Hide whitespace changes
Inline Side-by-side
Showing with 370 additions and 24 deletions
lib/Doctrine/ORM/Tools/Cli.php
View file @ 356887c8
......@@ -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
lib/Doctrine/ORM/Tools/Cli/AbstractPrinter.php
View file @ 356887c8
......@@ -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);
......
lib/Doctrine/ORM/Tools/Cli/AbstractTask.php
View file @ 356887c8
......@@ -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
lib/Doctrine/ORM/Tools/Cli/Printer/AnsiColor.php
View file @ 356887c8
......@@ -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 != '\\' &&
......
lib/Doctrine/ORM/Tools/Cli/Printer/Normal.php
View file @ 356887c8
......@@ -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;
......
lib/Doctrine/ORM/Tools/Cli/Style.php
View file @ 356887c8
......@@ -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;
......
lib/Doctrine/ORM/Tools/Cli/Task/Help.php
View file @ 356887c8
......@@ -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');
......
lib/Doctrine/ORM/Tools/Cli/Task/Version.php
View file @ 356887c8
......@@ -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');
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment