Browse Source

help command.

tags/2.0.0-beta
Qiang Xue 13 years ago
parent
commit
12932f0d77
  1. 13
      framework/base/Module.php
  2. 83
      framework/console/Application.php
  3. 161
      framework/console/Controller.php
  4. 83
      framework/console/commands/HelpController.php

13
framework/base/Module.php

@ -488,9 +488,9 @@ abstract class Module extends Component implements Initable
* 2. If the segment matches * 2. If the segment matches
* - an ID in [[controllers]], create a controller instance using the corresponding configuration, * - an ID in [[controllers]], create a controller instance using the corresponding configuration,
* and return the controller with the rest part of the route; * and return the controller with the rest part of the route;
* - an ID in [[modules]], call the [[createController()]] method of the corresponding module.
* - a controller class under [[controllerPath]], create the controller instance, and return it * - a controller class under [[controllerPath]], create the controller instance, and return it
* with the rest part of the route; * with the rest part of the route;
* - an ID in [[modules]], call the [[createController()]] method of the corresponding module.
* *
* @param string $route the route which may consist module ID, controller ID and/or action ID (e.g. `post/create`) * @param string $route the route which may consist module ID, controller ID and/or action ID (e.g. `post/create`)
* @return array|boolean the array of controller instance and action ID. False if the route cannot be resolved. * @return array|boolean the array of controller instance and action ID. False if the route cannot be resolved.
@ -521,6 +521,13 @@ abstract class Module extends Component implements Initable
); );
} }
if (($module = $this->getModule($id)) !== null) {
$result = $module->createController($route);
if ($result !== false) {
return $result;
}
}
$className = ucfirst($id) . 'Controller'; $className = ucfirst($id) . 'Controller';
$classFile = $this->getControllerPath() . DIRECTORY_SEPARATOR . $className . '.php'; $classFile = $this->getControllerPath() . DIRECTORY_SEPARATOR . $className . '.php';
if (is_file($classFile)) { if (is_file($classFile)) {
@ -535,10 +542,6 @@ abstract class Module extends Component implements Initable
} }
} }
if (($module = $this->getModule($id)) !== null) {
return $module->createController($route);
}
return false; return false;
} }
} }

83
framework/console/Application.php

@ -20,23 +20,30 @@ use yii\util\ReflectionHelper;
* through a command-based approach: * through a command-based approach:
* *
* - A console application consists of one or several possible user commands; * - A console application consists of one or several possible user commands;
* - Each user command is implemented as a class extending [[Command]]; * - Each user command is implemented as a class extending [[\yii\console\Controller]];
* - User specifies which command to run on the command line; * - User specifies which command to run on the command line;
* - The command processes the user request with the specified parameters. * - The command processes the user request with the specified parameters.
* *
* The command classes reside in the directory specified by [[commandPath]]. * The command classes reside in the directory specified by [[controllerPath]].
* The name of the class should be of the form `<command-name>Command` (e.g. `HelpCommand`). * Their naming should follow the same naming as controllers. For example, the `help` command
* is implemented using the `HelpController` class.
* *
* To run the console application, enter the following on the command line: * To run the console application, enter the following on the command line:
* *
* ~~~ * ~~~
* yiic <command-name> [param 1] [param 2] ... * yiic <route> [...options...]
* ~~~ * ~~~
* *
* You may use the following line to see help instructions about a command: * where `<route>` refers to a controller route in the form of `ModuleID/ControllerID/ActionID`
* (e.g. `sitemap/create`), and `options` refers to a set of named parameters that will be used
* to initialize the command controller instance and the corresponding action (e.g. `--since=0`
* specifies a `since` parameter whose value is 0).
*
* A `help` command is provided by default, which may list available commands and show their usage.
* To use this command, simply type:
* *
* ~~~ * ~~~
* yiic help <command-name> * yiic help
* ~~~ * ~~~
* *
* @author Qiang Xue <qiang.xue@gmail.com> * @author Qiang Xue <qiang.xue@gmail.com>
@ -66,7 +73,7 @@ class Application extends \yii\base\Application
} }
} }
// ensure we have the 'help' command so that we can list the available commands // ensure we have the 'help' command so that we can list the available commands
if ($this->defaultRoute === 'help' && !isset($this->controllers['help'])) { if (!isset($this->controllers['help'])) {
$this->controllers['help'] = 'yii\console\commands\HelpController'; $this->controllers['help'] = 'yii\console\commands\HelpController';
} }
} }
@ -137,68 +144,6 @@ class Application extends \yii\base\Application
return array($route, $params); return array($route, $params);
} }
/**
* Searches for commands under the specified directory.
* @param string $path the directory containing the command class files.
* @return array list of commands (command name=>command class file)
*/
public function findCommands($path)
{
if (($dir = @opendir($path)) === false)
return array();
$commands = array();
while (($name = readdir($dir)) !== false) {
$file = $path . DIRECTORY_SEPARATOR . $name;
if (!strcasecmp(substr($name, -11), 'Command.php') && is_file($file))
$commands[strtolower(substr($name, 0, -11))] = $file;
}
closedir($dir);
return $commands;
}
/**
* Adds commands from the specified command path.
* If a command already exists, the new one will be ignored.
* @param string $path the alias of the directory containing the command class files.
*/
public function addCommands($path)
{
if (($commands = $this->findCommands($path)) !== array()) {
foreach ($commands as $name => $file) {
if (!isset($this->commands[$name]))
$this->commands[$name] = $file;
}
}
}
/**
* @param string $name command name (case-insensitive)
* @return CConsoleCommand the command object. Null if the name is invalid.
*/
public function createCommand($name)
{
$name = strtolower($name);
if (isset($this->commands[$name])) {
if (is_string($this->commands[$name])) // class file path or alias
{
if (strpos($this->commands[$name], '/') !== false || strpos($this->commands[$name], '\\') !== false) {
$className = substr(basename($this->commands[$name]), 0, -4);
if (!class_exists($className, false))
require_once($this->commands[$name]);
}
else // an alias
$className = Yii::import($this->commands[$name]);
return new $className($name, $this);
}
else // an array configuration
return Yii::createComponent($this->commands[$name], $name, $this);
}
else if ($name === 'help')
return new CHelpCommand('help', $this);
else
return null;
}
public function coreCommands() public function coreCommands()
{ {
return array( return array(

161
framework/console/Controller.php

@ -13,36 +13,15 @@ use yii\base\Action;
use yii\base\Exception; use yii\base\Exception;
/** /**
* Command represents an executable console command. * Controller is the base class of console command classes.
* *
* It works like {@link \yii\web\Controller} by parsing command line options and dispatching * A controller consists of one or several actions known as sub-commands.
* the request to a specific action with appropriate option values. * Users call a console command by specifying the corresponding route which identifies a controller action.
* The `yiic` program is used when calling a console command, like the following:
* *
* Users call a console command via the following command format: * ~~~
* <pre> * yiic <route> [...options...]
* yiic CommandName ActionName --Option1=Value1 --Option2=Value2 ... * ~~~
* </pre>
*
* Child classes mainly needs to implement various action methods whose name must be
* prefixed with "action". The parameters to an action method are considered as options
* for that specific action. The action specified as {@link defaultAction} will be invoked
* when a user does not specify the action name in his command.
*
* Options are bound to action parameters via parameter names. For example, the following
* action method will allow us to run a command with <code>yiic sitemap --type=News</code>:
* <pre>
* class SitemapCommand {
* public function actionIndex($type) {
* ....
* }
* }
* </pre>
*
* @property string $name The command name.
* @property CommandRunner $commandRunner The command runner instance.
* @property string $help The command description. Defaults to 'Usage: php entry-script.php command-name'.
* @property array $optionHelp The command option help information. Each array element describes
* the help information for a single action.
* *
* @author Qiang Xue <qiang.xue@gmail.com> * @author Qiang Xue <qiang.xue@gmail.com>
* @since 2.0 * @since 2.0
@ -50,134 +29,22 @@ use yii\base\Exception;
class Controller extends \yii\base\Controller class Controller extends \yii\base\Controller
{ {
/** /**
* This method is invoked when the request parameters do not satisfy the requirement of the specified action.
* The default implementation will throw an exception.
* @param Action $action the action being executed
* @param Exception $exception the exception about the invalid parameters
* @throws Exception whenever this method is invoked
*/
public function invalidActionParams($action, $exception)
{
}
/**
* This method is invoked when extra parameters are provided to an action when it is executed. * This method is invoked when extra parameters are provided to an action when it is executed.
* The default implementation does nothing. * The default implementation does nothing.
* @param Action $action the action being executed * @param Action $action the action being executed
* @param array $expected the expected action parameters (name => value) * @param array $expected the expected action parameters (name => value)
* @param array $actual the actual action parameters (name => value) * @param array $actual the actual action parameters (name => value)
* @throws Exception if any unrecognized parameters are provided
*/ */
public function extraActionParams($action, $expected, $actual) public function extraActionParams($action, $expected, $actual)
{ {
} unset($expected['args'], $actual['args']);
/** $keys = array_diff(array_keys($actual), array_keys($expected));
* Provides the command description. if (!empty($keys)) {
* This method may be overridden to return the actual command description. throw new Exception(\Yii::t('yii', 'Unknown parameters: {params}', array(
* @return string the command description. Defaults to 'Usage: php entry-script.php command-name'. '{params}' => implode(', ', $keys),
*/ )));
public function getHelp()
{
$help = 'Usage: ' . $this->getCommandRunner()->getScriptName() . ' ' . $this->getName();
$options = $this->getOptionHelp();
if (empty($options))
return $help;
if (count($options) === 1)
return $help . ' ' . $options[0];
$help .= " <action>\nActions:\n";
foreach ($options as $option)
$help .= ' ' . $option . "\n";
return $help;
} }
/**
* Provides the command option help information.
* The default implementation will return all available actions together with their
* corresponding option information.
* @return array the command option help information. Each array element describes
* the help information for a single action.
*/
public function getOptionHelp()
{
$options = array();
$class = new \ReflectionClass(get_class($this));
foreach ($class->getMethods(\ReflectionMethod::IS_PUBLIC) as $method) {
$name = $method->getName();
if (!strncasecmp($name, 'action', 6) && strlen($name) > 6) {
$name = substr($name, 6);
$name[0] = strtolower($name[0]);
$help = $name;
foreach ($method->getParameters() as $param) {
$optional = $param->isDefaultValueAvailable();
$defaultValue = $optional ? $param->getDefaultValue() : null;
$name = $param->getName();
if ($optional)
$help .= " [--$name=$defaultValue]";
else
$help .= " --$name=value";
}
$options[] = $help;
}
}
return $options;
}
/**
* Displays a usage error.
* This method will then terminate the execution of the current application.
* @param string $message the error message
*/
public function usageError($message)
{
echo "Error: $message\n\n" . $this->getHelp() . "\n";
exit(1);
}
/**
* Reads input via the readline PHP extension if that's available, or fgets() if readline is not installed.
*
* @param string $message to echo out before waiting for user input
* @param string $default the default string to be returned when user does not write anything.
* Defaults to null, means that default string is disabled.
* @return mixed line read as a string, or false if input has been closed
*/
public function prompt($message, $default = null)
{
if ($default !== null) {
$message .= " [$default] ";
}
else {
$message .= ' ';
}
if (extension_loaded('readline')) {
$input = readline($message);
if ($input) {
readline_add_history($input);
}
} else {
echo $message;
$input = fgets(STDIN);
}
if ($input === false) {
return false;
}
else {
$input = trim($input);
return ($input === '' && $default !== null) ? $default : $input;
}
}
/**
* Asks user to confirm by typing y or n.
*
* @param string $message to echo out before waiting for user input
* @return bool if user confirmed
*/
public function confirm($message)
{
echo $message . ' [yes|no] ';
return !strncasecmp(trim(fgets(STDIN)), 'y', 1);
} }
} }

83
framework/console/commands/HelpController.php

@ -1,8 +1,7 @@
<?php <?php
/** /**
* HelpCommand class file. * HelpController class file.
* *
* @author Qiang Xue <qiang.xue@gmail.com>
* @link http://www.yiiframework.com/ * @link http://www.yiiframework.com/
* @copyright Copyright &copy; 2008-2012 Yii Software LLC * @copyright Copyright &copy; 2008-2012 Yii Software LLC
* @license http://www.yiiframework.com/license/ * @license http://www.yiiframework.com/license/
@ -17,9 +16,11 @@ namespace yii\console\commands;
* about a specific command. * about a specific command.
* *
* To use this command, enter the following on the command line: * To use this command, enter the following on the command line:
* <pre> *
* php path/to/entry_script.php help [command name] * ~~~
* </pre> * yiic help [command name]
* ~~~
*
* In the above, if the command name is not provided, it will display all * In the above, if the command name is not provided, it will display all
* available commands. * available commands.
* *
@ -32,49 +33,53 @@ class HelpController extends \yii\console\Controller
{ {
public function actionIndex($args = array()) public function actionIndex($args = array())
{ {
echo "Yii console command helper (based on Yii v" . \Yii::getVersion() . ").\n";
$commands = $this->getCommands();
if ($commands !== array()) {
echo "\n Usage: yiic <command-name> [...options...]\n\n";
echo "The following commands are available:\n";
foreach ($commands as $command) {
echo " - $command\n";
}
echo "\nTo see individual command help, enter:\n";
echo "\n yiic help <command-name>\n";
} else {
echo "\nNo commands are found.\n";
}
}
protected function getCommands()
{
$commands = $this->getModuleCommands(\Yii::$application);
sort($commands);
return array_unique($commands);
} }
/** /**
* Execute the action. * @param \yii\base\Module $module
* @param array $args command line parameters specific for this command * @return array
*/ */
public function run($args) protected function getModuleCommands($module)
{
$runner=$this->getCommandRunner();
$commands=$runner->commands;
if(isset($args[0]))
{ {
$name=strtolower($args[0]); if ($module === null) {
return array();
} }
if(!isset($args[0]) || !isset($commands[$name]))
{ $commands = array_keys($module->controllers);
if(!empty($commands))
{ foreach ($module->getModules() as $id => $module) {
echo "Yii command runner (based on Yii v".\Yii::getVersion().")\n"; foreach ($this->getModuleCommands($module->getModule($id)) as $command) {
echo "Usage: ".$runner->getScriptName()." <command-name> [parameters...]\n"; $commands[] = $command;
echo "\nThe following commands are available:\n";
$commandNames=array_keys($commands);
sort($commandNames);
echo ' - '.implode("\n - ",$commandNames);
echo "\n\nTo see individual command help, use the following:\n";
echo " ".$runner->getScriptName()." help <command-name>\n";
} else
{
echo "No available commands.\n";
echo "Please define them under the following directory:\n";
echo "\t".\Yii::$app->getCommandPath()."\n";
} }
} else
echo $runner->createCommand($name)->getHelp();
} }
/** $files = scandir($module->getControllerPath());
* Provides the command description. foreach ($files as $file) {
* @return string the command description. if(strcmp(substr($file,-14),'Controller.php') === 0 && is_file($file)) {
*/ $commands[] = lcfirst(substr(basename($file), 0, -14));
public function getHelp() }
{ }
return parent::getHelp().' [command-name]';
return $commands;
} }
} }
Loading…
Cancel
Save