Controller.php 8 KB
Newer Older
Alexander Makarov committed
1 2 3
<?php
/**
 * @link http://www.yiiframework.com/
Qiang Xue committed
4
 * @copyright Copyright (c) 2008 Yii Software LLC
Alexander Makarov committed
5 6 7 8 9
 * @license http://www.yiiframework.com/license/
 */

namespace yii\console;

Qiang Xue committed
10
use Yii;
Qiang Xue committed
11
use yii\base\Action;
Qiang Xue committed
12
use yii\base\InlineAction;
Qiang Xue committed
13
use yii\base\InvalidRouteException;
14
use yii\helpers\Console;
Qiang Xue committed
15

Alexander Makarov committed
16
/**
Qiang Xue committed
17
 * Controller is the base class of console command classes.
Alexander Makarov committed
18
 *
Qiang Xue committed
19 20
 * A controller consists of one or several actions known as sub-commands.
 * Users call a console command by specifying the corresponding route which identifies a controller action.
21
 * The `yii` program is used when calling a console command, like the following:
Alexander Makarov committed
22
 *
Qiang Xue committed
23
 * ~~~
24
 * yii <route> [--param1=value1 --param2 ...]
Qiang Xue committed
25
 * ~~~
Alexander Makarov committed
26 27 28 29
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
Qiang Xue committed
30
class Controller extends \yii\base\Controller
Alexander Makarov committed
31
{
Qiang Xue committed
32 33 34 35 36 37
	/**
	 * @var boolean whether the call of [[confirm()]] requires a user input.
	 * If false, [[confirm()]] will always return true no matter what user enters or not.
	 */
	public $interactive = true;

38
	/**
39 40 41 42
	 * @var bool whether to enable ANSI style in output.
	 * Setting this will affect [[ansiFormat()]], [[stdout()]] and [[stderr()]].
	 * If not set it will be auto detected using [[yii\helpers\Console::streamSupportsAnsiColors()]] with STDOUT
	 * for [[ansiFormat()]] and [[stdout()]] and STDERR for [[stderr()]].
43
	 */
44
	public $colors;
45

Qiang Xue committed
46 47 48 49 50 51 52 53 54 55 56
	/**
	 * Runs an action with the specified action ID and parameters.
	 * If the action ID is empty, the method will use [[defaultAction]].
	 * @param string $id the ID of the action to be executed.
	 * @param array $params the parameters (name-value pairs) to be passed to the action.
	 * @return integer the status of the action execution. 0 means normal, other values mean abnormal.
	 * @throws InvalidRouteException if the requested action ID cannot be resolved into an action successfully.
	 * @see createAction
	 */
	public function runAction($id, $params = array())
	{
57
		if (!empty($params)) {
Qiang Xue committed
58
			$options = $this->globalOptions();
Qiang Xue committed
59
			foreach ($params as $name => $value) {
Qiang Xue committed
60 61 62
				if (in_array($name, $options, true)) {
					$this->$name = $value;
					unset($params[$name]);
Qiang Xue committed
63 64 65 66 67 68
				}
			}
		}
		return parent::runAction($id, $params);
	}

Qiang Xue committed
69
	/**
Qiang Xue committed
70 71 72 73 74 75 76 77
	 * Binds the parameters to the action.
	 * This method is invoked by [[Action]] when it begins to run with the given parameters.
	 * This method will first bind the parameters with the [[globalOptions()|global options]]
	 * available to the action. It then validates the given arguments.
	 * @param Action $action the action to be bound with parameters
	 * @param array $params the parameters to be bound to the action
	 * @return array the valid parameters that the action can run with.
	 * @throws Exception if there are unknown options or missing arguments
Qiang Xue committed
78
	 */
Qiang Xue committed
79
	public function bindActionParams($action, $params)
Qiang Xue committed
80
	{
81
		if (!empty($params)) {
Qiang Xue committed
82 83 84 85 86 87 88 89
			$options = $this->globalOptions();
			foreach ($params as $name => $value) {
				if (in_array($name, $options, true)) {
					$this->$name = $value;
					unset($params[$name]);
				}
			}
		}
Qiang Xue committed
90

Qiang Xue committed
91 92
		$args = isset($params[Request::ANONYMOUS_PARAMS]) ? $params[Request::ANONYMOUS_PARAMS] : array();
		unset($params[Request::ANONYMOUS_PARAMS]);
93
		if (!empty($params)) {
94
			throw new Exception(Yii::t('yii', 'Unknown options: {params}', array(
Qiang Xue committed
95
				'{params}' => implode(', ', array_keys($params)),
Qiang Xue committed
96
			)));
Qiang Xue committed
97
		}
Qiang Xue committed
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116

		if ($action instanceof InlineAction) {
			$method = new \ReflectionMethod($this, $action->actionMethod);
		} else {
			$method = new \ReflectionMethod($action, 'run');
		}

		$missing = array();
		foreach ($method->getParameters() as $i => $param) {
			$name = $param->getName();
			if (!isset($args[$i])) {
				if ($param->isDefaultValueAvailable()) {
					$args[$i] = $param->getDefaultValue();
				} else {
					$missing[] = $name;
				}
			}
		}

117
		if (!empty($missing)) {
118
			throw new Exception(Yii::t('yii', 'Missing required arguments: {params}', array(
Qiang Xue committed
119
				'{params}' => implode(', ', $missing),
Qiang Xue committed
120
			)));
Alexander Makarov committed
121
		}
Qiang Xue committed
122 123

		return $args;
Alexander Makarov committed
124
	}
Alexander Makarov committed
125

126 127 128 129 130 131 132
	/**
	 * Formats a string with ANSI codes
	 *
	 * You may pass additional parameters using the constants defined in [[yii\helpers\base\Console]].
	 *
	 * Example:
	 * ~~~
133
	 * $this->ansiFormat('This will be red and underlined.', Console::FG_RED, Console::UNDERLINE);
134 135 136 137 138
	 * ~~~
	 *
	 * @param string $string the string to be formatted
	 * @return string
	 */
139
	public function ansiFormat($string)
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211
	{
		if ($this->ansi === true || $this->ansi === null && Console::streamSupportsAnsiColors(STDOUT)) {
			$args = func_get_args();
			array_shift($args);
			$string = Console::ansiFormat($string, $args);
		}
		return $string;
	}

	/**
	 * Prints a string to STDOUT
	 *
	 * You may optionally format the string with ANSI codes by
	 * passing additional parameters using the constants defined in [[yii\helpers\base\Console]].
	 *
	 * Example:
	 * ~~~
	 * $this->stdout('This will be red and underlined.', Console::FG_RED, Console::UNDERLINE);
	 * ~~~
	 *
	 * @param string $string the string to print
	 * @return int|boolean Number of bytes printed or false on error
	 */
	public function stdout($string)
	{
		if ($this->ansi === true || $this->ansi === null && Console::streamSupportsAnsiColors(STDOUT)) {
			$args = func_get_args();
			array_shift($args);
			$string = Console::ansiFormat($string, $args);
		}
		return Console::stdout($string);
	}

	/**
	 * Prints a string to STDERR
	 *
	 * You may optionally format the string with ANSI codes by
	 * passing additional parameters using the constants defined in [[yii\helpers\base\Console]].
	 *
	 * Example:
	 * ~~~
	 * $this->stderr('This will be red and underlined.', Console::FG_RED, Console::UNDERLINE);
	 * ~~~
	 *
	 * @param string $string the string to print
	 * @return int|boolean Number of bytes printed or false on error
	 */
	public function stderr($string)
	{
		if ($this->ansi === true || $this->ansi === null && Console::streamSupportsAnsiColors(STDERR)) {
			$args = func_get_args();
			array_shift($args);
			$string = Console::ansiFormat($string, $args);
		}
		return fwrite(STDERR, $string);
	}

	/**
	 * Prompts the user for input and validates it
	 *
	 * @param string $text prompt string
	 * @param array $options the options to validate the input:
	 *  - required: whether it is required or not
	 *  - default: default value if no input is inserted by the user
	 *  - pattern: regular expression pattern to validate user input
	 *  - validator: a callable function to validate input. The function must accept two parameters:
	 *      - $input: the user input to validate
	 *      - $error: the error value passed by reference if validation failed.
	 * @return string the user input
	 */
	public function prompt($text, $options = array())
	{
212 213 214 215 216
		if ($this->interactive) {
			return Console::prompt($text, $options);
		} else {
			return isset($options['default']) ? $options['default'] : '';
		}
217 218
	}

Alexander Makarov committed
219 220 221 222 223 224 225 226 227
	/**
	 * Asks user to confirm by typing y or n.
	 *
	 * @param string $message to echo out before waiting for user input
	 * @param boolean $default this value is returned if no selection is made.
	 * @return boolean whether user confirmed
	 */
	public function confirm($message, $default = false)
	{
Qiang Xue committed
228
		if ($this->interactive) {
229
			return Console::confirm($message, $default);
Qiang Xue committed
230 231 232 233 234
		} else {
			return true;
		}
	}

235 236 237 238 239 240 241 242 243
	/**
	 * Gives the user an option to choose from. Giving '?' as an input will show
	 * a list of options to choose from and their explanations.
	 *
	 * @param string $prompt the prompt message
	 * @param array  $options Key-value array of options to choose from
	 *
	 * @return string An option character the user chose
	 */
244
	public function select($prompt, $options = array())
245 246 247 248
	{
		return Console::select($prompt, $options);
	}

Qiang Xue committed
249 250
	/**
	 * Returns the names of the global options for this command.
251
	 * A global option requires the existence of a public member variable whose
Qiang Xue committed
252 253
	 * name is the option name.
	 * Child classes may override this method to specify possible global options.
254 255 256 257
	 *
	 * Note that the values setting via global options are not available
	 * until [[beforeAction()]] is being called.
	 *
Qiang Xue committed
258 259
	 * @return array the names of the global options for this command.
	 */
Qiang Xue committed
260 261 262
	public function globalOptions()
	{
		return array();
Alexander Makarov committed
263
	}
Zander Baldwin committed
264
}