Skip to content

Commit

Permalink
Moved common help parsing code into HelpParser. Action methods now ha…
Browse files Browse the repository at this point in the history 
…ve default implementation.
  • Loading branch information
@samdark
samdark committed Sep 4, 2014
1 parent d44f424 commit 21440d7
Show file tree
Hide file tree
Showing 4 changed files with 119 additions and 59 deletions.
16 changes: 9 additions & 7 deletions framework/console/Action.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,25 +22,27 @@
class Action extends \yii\base\Action
{
/**
* Returns a short description (one line) of information about the action.
* Returns one-line short summary describing this action.
*
* The default implementation returns help information retrieved from the PHPDoc comments.
* You may override this method to return customized summary.
* The default implementation returns first line from the PHPDoc comment.
*
* @return string
*/
public function getDescription()
public function getHelpSummary()
{
return null;
return HelpParser::getSummary(new \ReflectionClass($this));
}

/**
* Returns help information for the action.
* Returns help information for this action.
*
* The default implementation returns help information retrieved from the PHPDoc comments.
* You may override this method to return customized help.
* The default implementation returns help information retrieved from the PHPDoc comment.
* @return string
*/
public function getHelp()
{
return null;
return HelpParser::getDescriptionForConsole(new \ReflectionClass($this));
}
}
93 changes: 48 additions & 45 deletions framework/console/Controller.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@

use Yii;
use yii\base\Action;
use yii\base\InlineAction;
use yii\base\InvalidRouteException;
use yii\helpers\Console;

Expand Down Expand Up @@ -56,7 +57,7 @@ class Controller extends \yii\base\Controller
*/
public function isColorEnabled($stream = \STDOUT)
{
return $this->color === null ? Console::streamSupportsAnsiColors($stream) : $this->color;
return $this->color === null ? Console::streamSupportsAnsiColors($stream) : $this->color;
}

/**
Expand Down Expand Up @@ -99,7 +100,7 @@ public function runAction($id, $params = [])
*/
public function bindActionParams($action, $params)
{
if ($action instanceof \yii\base\InlineAction) {
if ($action instanceof InlineAction) {
$method = new \ReflectionMethod($this, $action->actionMethod);
} else {
$method = new \ReflectionMethod($action, 'run');
Expand Down Expand Up @@ -275,67 +276,69 @@ public function options($actionId)
}

/**
* Returns a short description (one line) of information about this controller or it's action (if specified).
* Returns one-line short summary describing this controller.
*
* You may override this method to return customized description.
* The default implementation returns help information retrieved from the PHPDoc comments
* of the controller class.
* You may override this method to return customized summary.
* The default implementation returns first line from the PHPDoc comment.
*
* @param string $actionID action to get description for. null means overall controller description.
* @return string
*/
public function getDescription($actionID = null)
public function getHelpSummary()
{
$action = null;
if ($actionID === null) {
$class = new \ReflectionClass($this);
return HelpParser::getSummary(new \ReflectionClass($this));
}

/**
* Returns one-line short summary describing this controller action.
*
* You may override this method to return customized summary.
* The default implementation returns first line from the PHPDoc comment.
*
* @param string $actionID action to get summary for
* @return string
*/
public function getActionHelpSummary($actionID)
{
$action = $this->createAction($actionID);
if ($action instanceof InlineAction) {
$class = new \ReflectionMethod($this, $action->actionMethod);
} else {
$action = $this->createAction($actionID);
if ($action instanceof \yii\base\InlineAction) {
$class = new \ReflectionMethod($this, $action->actionMethod);
} else {
$class = new \ReflectionClass($action);
}
$class = new \ReflectionClass($action);
}

$docLines = preg_split('~\R~', $class->getDocComment());
if (isset($docLines[1])) {
return trim($docLines[1], ' *');
}
return '';
return HelpParser::getSummary($class);
}

/**
* Returns help information for this controller or it's action (if specified).
* Returns help information for this controller.
*
* You may override this method to return customized help.
* The default implementation returns help information retrieved from the PHPDoc comments
* of the controller class.
* @param string $actionID action to get help for. null means overall controller help.
* The default implementation returns help information retrieved from the PHPDoc comment.
* @return string
*/
public function getHelp($actionID = null)
public function getHelp()
{
$action = null;
if ($actionID === null) {
$class = new \ReflectionClass($this);
} else {
$action = $this->createAction($actionID);
return HelpParser::getFull(new \ReflectionClass($this));
}

if ($action instanceof \yii\base\InlineAction) {
$class = new \ReflectionMethod($this, $action->actionMethod);
} else {
$class = new \ReflectionClass($action);
}
}
/**
* Returns help information for this controller action.
*
* You may override this method to return customized help.
* The default implementation returns help information retrieved from the PHPDoc comment.
* @param string $actionID action to get help for
* @return string
*/
public function getActionHelp($actionID)
{
$action = $this->createAction($actionID);

$comment = strtr(trim(preg_replace('/^\s*\**( |\t)?/m', '', trim($class->getDocComment(), '/'))), "\r", '');
if (preg_match('/^\s*@\w+/m', $comment, $matches, PREG_OFFSET_CAPTURE)) {
$comment = trim(substr($comment, 0, $matches[0][1]));
}
if ($comment !== '') {
return rtrim(Console::renderColoredString(Console::markdownToAnsi($comment)));
if ($action instanceof InlineAction) {
$class = new \ReflectionMethod($this, $action->actionMethod);
} else {
$class = new \ReflectionClass($action);
}
return '';

return HelpParser::getFull($class);
}
}
52 changes: 52 additions & 0 deletions framework/console/HelpParser.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/

namespace yii\console;

use yii\helpers\Console;

/**
* HelpParser contains methods used to get help information from phpDoc.
*
* @author Alexander Makarov <[email protected]>
* @since 2.0
*/
class HelpParser
{
/**
* Returns the first line of docblock.
*
* @param \Reflector $reflector
* @return string
*/
public static function getSummary(\Reflector $reflector)
{
$docLines = preg_split('~\R~', $reflector->getDocComment());
if (isset($docLines[1])) {
return trim($docLines[1], ' *');
}
return '';
}

/**
* Returns full description from the docblock.
*
* @param \Reflector $reflector
* @return string
*/
public static function getFull(\Reflector $reflector)
{
$comment = strtr(trim(preg_replace('/^\s*\**( |\t)?/m', '', trim($reflector->getDocComment(), '/'))), "\r", '');
if (preg_match('/^\s*@\w+/m', $comment, $matches, PREG_OFFSET_CAPTURE)) {
$comment = trim(substr($comment, 0, $matches[0][1]));
}
if ($comment !== '') {
return rtrim(Console::renderColoredString(Console::markdownToAnsi($comment)));
}
return '';
}
}
17 changes: 10 additions & 7 deletions framework/console/controllers/HelpController.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@

use Yii;
use yii\base\Application;
use yii\base\InlineAction;
use yii\console\Action;
use yii\console\Controller;
use yii\console\Exception;
Expand Down Expand Up @@ -61,7 +62,7 @@ public function actionIndex($command = null)

$actions = $this->getActions($controller);
if ($actionID !== '' || count($actions) === 1 && $actions[0] === $controller->defaultAction) {
$this->getActionHelp($controller, $actionID);
$this->getControllerActionHelp($controller, $actionID);
} else {
$this->getControllerHelp($controller);
}
Expand Down Expand Up @@ -94,7 +95,8 @@ protected function getCommandDescriptions()
$result = Yii::$app->createController($command);
if ($result !== false) {
list($controller, $actionID) = $result;
$description = $controller->getDescription();
/** @var Controller $controller */
$description = $controller->getHelpSummary();
}

$descriptions[$command] = $description;
Expand Down Expand Up @@ -253,10 +255,10 @@ protected function getActionSummary($controller, $actionID)
$action = $controller->createAction($actionID);

if ($action instanceof Action) {
$description = $action->getDescription();
$description = $action->getHelpSummary();
}
if ($description === null) {
$description = $controller->getDescription($actionID);
$description = $controller->getActionHelpSummary($actionID);
}
return $description;
}
Expand All @@ -267,7 +269,7 @@ protected function getActionSummary($controller, $actionID)
* @param string $actionID action ID
* @throws Exception if the action does not exist
*/
protected function getActionHelp($controller, $actionID)
protected function getControllerActionHelp($controller, $actionID)
{
$action = $controller->createAction($actionID);
if ($action === null) {
Expand All @@ -276,9 +278,10 @@ protected function getActionHelp($controller, $actionID)
]));
}
$description = null;
if ($action instanceof \yii\base\InlineAction) {
if ($action instanceof InlineAction) {
$method = new \ReflectionMethod($controller, $action->actionMethod);
} else {
/** @var Action $action */
$description = $action->getHelp();
$method = new \ReflectionMethod($action, 'run');
}
Expand All @@ -287,7 +290,7 @@ protected function getActionHelp($controller, $actionID)
$options = $this->getOptionHelps($controller, $actionID);

if ($description === null) {
$description = $controller->getHelp($actionID);
$description = $controller->getActionHelp($actionID);
}
if ($description !== '') {
$this->stdout("\nDESCRIPTION\n", Console::BOLD);
Expand Down

0 comments on commit 21440d7

Please sign in to comment.