CConsoleCommand
| Пакет | system.console |
|---|---|
| Наследование | абстрактный класс CConsoleCommand » CComponent |
| Подклассы | CHelpCommand |
| С версии | 1.0 |
| Исходный код | framework/console/CConsoleCommand.php |
Он работает подобно CController, анализируя параметры командной строки и отправляя запрос на выполнение определённого действия с соответствующими значениями параметров.
Пользователи вызывают консольную команду в следующем формате:
yiic CommandName ActionName --Option1=Value1 --Option2=Value2 ...
Подклассы в основном должны реализовывать различные методы действий, имена которых должны начинаться с "action". Параметры метода действия считаются параметрами для этого конкретного действия. Действие, указанное как defaultAction, будет вызываться, когда пользователь не указывает имя действия в своей команде.
Параметры привязываются к параметрам действия по именам параметров. Например, следующий метод действия позволит нам выполнить команду с
yiic sitemap --type=News:
class SitemapCommand extends CConsoleCommand {
public function actionIndex($type) {
....
}
}
С версии 1.1.11 значение возвращаемого типа методов действий будет использоваться как код завершения приложения, если это целое число.
Общедоступные свойства
| Свойство | Тип | Описание | Определено в |
|---|---|---|---|
| commandRunner | CConsoleCommandRunner | экземпляр обработчика команд | CConsoleCommand |
| defaultAction | строка | имя по умолчанию для действия. | CConsoleCommand |
| help | строка | Предоставляет описание команды. | CConsoleCommand |
| name | строка | имя команды. | CConsoleCommand |
| optionHelp | массив | Предоставляет информацию о помощи по параметрам команды. | CConsoleCommand |
Общедоступные методы
| Метод | Описание | Определено в |
|---|---|---|
| __call() | Вызывает метод по имени, который не является методом класса. | CComponent |
| __construct() | Конструктор. | CConsoleCommand |
| __get() | Возвращает значение свойства, список обработчиков событий или поведение на основе его имени. | CComponent |
| __isset() | Проверяет, является ли значение свойства нулевым. | CComponent |
| __set() | Устанавливает значение свойства компонента. | CComponent |
| __unset() | Устанавливает свойство компонента в значение null. | CComponent |
| asa() | Возвращает объект поведения по имени. | CComponent |
| attachBehavior() | Присоединяет поведение к компоненту. | CComponent |
| attachBehaviors() | Присоединяет список поведений к компоненту. | CComponent |
| attachEventHandler() | Присоединяет обработчик событий к событию. | CComponent |
| behaviors() | Возвращает список поведений, по которым должна действовать эта команда. | CConsoleCommand |
| buildFileList() | Создаёт список файлов в каталоге. | CConsoleCommand |
| canGetProperty() | Определяет, можно ли прочитать свойство. | CComponent |
| canSetProperty() | Определяет, можно ли установить свойство. | CComponent |
| confirm() | Запрашивает подтверждение у пользователя, введя y или n. | CConsoleCommand |
| copyFiles() | Копирует список файлов из одного места в другое. | CConsoleCommand |
| detachBehavior() | Отсоединяет поведение от компонента. | CComponent |
| detachBehaviors() | Отсоединяет все поведения от компонента. | CComponent |
| detachEventHandler() | Отсоединяет существующий обработчик событий. | CComponent |
| disableBehavior() | Отключает присоединённое поведение. | CComponent |
| disableBehaviors() | Отключает все присоединённые поведения к данному компоненту. | CComponent |
| enableBehavior() | Включает присоединённое поведение. | CComponent |
| enableBehaviors() | Включает все присоединённые к этому компоненту поведения. | CComponent |
| ensureDirectory() | Создаёт все родительские каталоги, если они не существуют. | CConsoleCommand |
| evaluateExpression() | Вычисляет PHP выражение или обратный вызов в контексте этого компонента. | CComponent |
| getCommandRunner() | Возвращает экземпляр обработчика команд. | CConsoleCommand |
| getEventHandlers() | Возвращает список присоединённых обработчиков событий для события. | CComponent |
| getHelp() | Предоставляет описание команды. | CConsoleCommand |
| getName() | Возвращает имя команды. | CConsoleCommand |
| getOptionHelp() | Предоставляет информацию о помощи по параметрам команды. | CConsoleCommand |
| hasEvent() | Определяет, определено ли событие. | CComponent |
| hasEventHandler() | Проверяет, имеет ли указанное событие присоединённые обработчики. | CComponent |
| hasProperty() | Определяет, определено ли свойство. | CComponent |
| init() | Инициализирует объект команды. | CConsoleCommand |
| onAfterAction() | Это событие срабатывает после завершения выполнения действия. | CConsoleCommand |
| onBeforeAction() | Это событие срабатывает перед выполнением действия. | CConsoleCommand |
| pluralize() | Преобразует слово в его множественное число. | CConsoleCommand |
| prompt() | Считывает входные данные через расширение readline PHP, если оно доступно, или fgets(), если readline не установлен. | CConsoleCommand |
| raiseEvent() | Вызывает событие. | CComponent |
| renderFile() | Отображает файл представления. | CConsoleCommand |
| run() | Выполняет команду. | CConsoleCommand |
| usageError() | Отображает ошибку использования. | CConsoleCommand |
Защищенные методы
| Метод | Описание | Определен в |
|---|---|---|
| afterAction() | Этот метод вызывается сразу после завершения выполнения действия. | CConsoleCommand |
| beforeAction() | Этот метод вызывается непосредственно перед выполнением действия. | CConsoleCommand |
| resolveRequest() | Парсит аргументы командной строки и определяет, какое действие выполнить. | CConsoleCommand |
События
| Событие | Описание | Определен в |
|---|---|---|
| onBeforeAction | Это событие срабатывает перед выполнением действия. | CConsoleCommand |
| onAfterAction | Это событие срабатывает после завершения выполнения действия. | CConsoleCommand |
Подробное описание свойств
commandRunner свойство только для чтения
public CConsoleCommandRunner getCommandRunner()
экземпляр исполнителя команд
defaultAction свойство (доступно начиная с v1.1.5)
public string $defaultAction;
имя по умолчанию действия. По умолчанию 'index'.
help свойство только для чтения
public string getHelp()
Предоставляет описание команды. Этот метод может быть переопределен для возвращения фактического описания команды.
name свойство только для чтения
public string getName()
имя команды.
optionHelp свойство только для чтения (доступно начиная с v1.1.5)
public array getOptionHelp()
Предоставляет информацию о помощи по параметрам команды. По умолчанию реализация вернет все доступные действия вместе с информацией о параметрах каждого из них.
Подробное описание методов
__construct() метод
public void __construct(string $name, CConsoleCommandRunner $runner) | ||
| $name | string | имя команды |
| $runner | CConsoleCommandRunner | исполнитель команд |
public function __construct($name,$runner)
{
$this->_name=$name;
$this->_runner=$runner;
$this->attachBehaviors($this->behaviors());
}
Конструктор.
afterAction() метод
protected integer afterAction(string $action, array $params, integer $exitCode=0) | ||
| $action | string | имя действия |
| $params | array | параметры, которые передаются методу действия. |
| $exitCode | integer | код завершения приложения, возвращённый методом действия. |
| {return} | integer | код завершения приложения (возвращаемое значение доступно начиная с версии 1.1.11) |
protected function afterAction($action,$params,$exitCode=0)
{
$event=new CConsoleCommandEvent($this,$params,$action,$exitCode);
if($this->hasEventHandler('onAfterAction'))
$this->onAfterAction($event);
return $event->exitCode;
}
Этот метод вызывается сразу после завершения выполнения действия. Вы можете переопределить этот метод для выполнения некоторых постпроцессинговых операций для действия.
beforeAction() метод
protected boolean beforeAction(string $action, array $params) | ||
| $action | string | имя действия |
| $params | array | параметры, которые передаются методу действия. |
| {return} | boolean | должен ли быть выполнен метод действия. |
protected function beforeAction($action,$params)
{
if($this->hasEventHandler('onBeforeAction'))
{
$event = new CConsoleCommandEvent($this,$params,$action);
$this->onBeforeAction($event);
return !$event->stopCommand;
}
else
{
return true;
}
}
Этот метод вызывается непосредственно перед выполнением действия. Вы можете переопределить этот метод, чтобы выполнить подготовку действия в последний момент.
behaviors() метод (доступно начиная с v1.1.11)
public array behaviors() | ||
| {return} | array | конфигурации поведения (имя_поведения=>конфигурация_поведения) |
public function behaviors()
{
return array();
}
Возвращает список поведений, которые должна иметь эта команда. Значение должно быть массивом конфигураций поведения с индексами по имени поведения. Каждая конфигурация поведения может быть либо строкой, определяющей класс поведения, либо массивом следующей структуры:
'behaviorName'=>array(
'class'=>'path.to.BehaviorClass',
'property1'=>'value1',
'property2'=>'value2',
)
Обратите внимание, что классы поведения должны реализовывать IBehavior или наследовать от CBehavior. Поведения, объявленные в этом методе, будут прикреплены к контроллеру при его создании.
Для получения более подробной информации о поведении, см. CComponent.
buildFileList() метод
public array buildFileList(string $sourceDir, string $targetDir, string $baseDir='', array $ignoreFiles=array ( ), array $renameMap=array ( )) | ||
| $sourceDir | string | исходная директория |
| $targetDir | string | целевая директория |
| $baseDir | string | базовая директория |
| $ignoreFiles | array | список имен файлов, которые следует игнорировать при построении списка. Доступно начиная с версии 1.1.11. |
| $renameMap | array | массив хешей имён файлов, которые следует переименовать. Пример значения: array('1.old.txt'=>'2.new.txt'). Доступно начиная с версии 1.1.11. |
| {return} | array | список файлов (см. copyFiles) |
public function buildFileList($sourceDir, $targetDir, $baseDir='', $ignoreFiles=array(), $renameMap=array())
{
$list=array();
$handle=opendir($sourceDir);
while(($file=readdir($handle))!==false)
{
if(in_array($file,array('.','..','.svn','.gitignore')) || in_array($file,$ignoreFiles))
continue;
$sourcePath=$sourceDir.DIRECTORY_SEPARATOR.$file;
$targetPath=$targetDir.DIRECTORY_SEPARATOR.strtr($file,$renameMap);
$name=$baseDir===''?$file : $baseDir.'/'.$file;
$list[$name]=array('source'=>$sourcePath, 'target'=>$targetPath);
if(is_dir($sourcePath))
$list=array_merge($list,$this->buildFileList($sourcePath,$targetPath,$name,$ignoreFiles,$renameMap));
}
closedir($handle);
return $list;
}
Строит список файлов в директории. Этот метод перебирает указанную директорию и строит список файлов и поддиректорий, которые она содержит. Результат этой функции можно передать в copyFiles.
confirm() метод (доступно начиная с v1.1.9)
public boolean confirm(string $message, boolean $default=false) | ||
| $message | string | вывод перед ожиданием ввода пользователя |
| $default | boolean | это значение возвращается, если выбор не сделан. Этот параметр доступен начиная с версии 1.1.11. |
| {return} | boolean | подтвердил ли пользователь |
public function confirm($message,$default=false)
{
echo $message.' (yes|no) [' . ($default ? 'yes' : 'no') . ']:';
$input = trim(fgets(STDIN));
return empty($input) ? $default : !strncasecmp($input,'y',1);
}
Запрашивает у пользователя подтверждение, введя y или n.
copyFiles() метод
public void copyFiles(array $fileList, boolean $overwriteAll=false) | ||
| $fileList | array | список файлов, которые нужно скопировать (имя=>спецификация). Ключи массива — имена, отображаемые во время копирования, а значения — спецификации для копируемых файлов. Каждое значение массива должно быть массивом следующей структуры:
|
| $overwriteAll | boolean | перезаписывать все файлы. |
public function copyFiles($fileList,$overwriteAll=false)
{
foreach($fileList as $name=>$file)
{
$source=strtr($file['source'],'/\\',DIRECTORY_SEPARATOR.DIRECTORY_SEPARATOR);
$target=strtr($file['target'],'/\\',DIRECTORY_SEPARATOR.DIRECTORY_SEPARATOR);
$callback=isset($file['callback']) ? $file['callback'] : null;
$params=isset($file['params']) ? $file['params'] : null;
if(is_dir($source))
{
$this->ensureDirectory($target);
continue;
}
if($callback!==null)
$content=call_user_func($callback,$source,$params);
else
$content=file_get_contents($source);
if(is_file($target))
{
if($content===file_get_contents($target))
{
echo " unchanged $name\n";
continue;
}
if($overwriteAll)
echo " overwrite $name\n";
else
{
echo " exist $name\n";
echo " ...overwrite? [Yes|No|All|Quit] ";
$answer=trim(fgets(STDIN));
if(!strncasecmp($answer,'q',1))
return;
elseif(!strncasecmp($answer,'y',1))
echo " overwrite $name\n";
elseif(!strncasecmp($answer,'a',1))
{
echo " overwrite $name\n";
$overwriteAll=true;
}
else
{
echo " skip $name\n";
continue;
}
}
}
else
{
$this->ensureDirectory(dirname($target));
echo " generate $name\n";
}
file_put_contents($target,$content);
}
}
Копирует список файлов из одного места в другое.
См. также
ensureDirectory() метод
public void ensureDirectory(string $directory) | ||
| $directory | строка | директория, подлежащая проверке |
public function ensureDirectory($directory)
{
if(!is_dir($directory))
{
$this->ensureDirectory(dirname($directory));
echo " mkdir ".strtr($directory,'\\','/')."\n";
mkdir($directory);
}
}
Создаёт все родительские директории, если они не существуют.
getCommandRunner() метод
public CConsoleCommandRunner getCommandRunner() | ||
| {возвращает} | CConsoleCommandRunner | экземпляр обработчика команд |
public function getCommandRunner()
{
return $this->_runner;
}
getHelp() метод
public string getHelp() | ||
| {возвращает} | строка | описание команды. По умолчанию 'Использование: php entry-script.php command-name'. |
public function getHelp()
{
$help='Usage: '.$this->getCommandRunner()->getScriptName().' '.$this->getName();
$options=$this->getOptionHelp();
if(empty($options))
return $help."\n";
if(count($options)===1)
return $help.' '.$options[0]."\n";
$help.=" <action>\nActions:\n";
foreach($options as $option)
$help.=' '.$option."\n";
return $help;
}
Предоставляет описание команды. Этот метод может быть переопределён для возвращения фактического описания команды.
getName() метод
public string getName() | ||
| {возвращает} | строка | имя команды. |
public function getName()
{
return $this->_name;
}
getOptionHelp() метод (доступен начиная с v1.1.5)
public array getOptionHelp() | ||
| {возвращает} | массив | информация о помощи по опциям команды. Каждый элемент массива описывает информацию о помощи для одного действия. |
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;
if(is_array($defaultValue)) {
$defaultValue = str_replace(array("\r\n", "\n", "\r"), "", print_r($defaultValue, true));
}
$name=$param->getName();
if($name==='args')
continue;
if($optional)
$help.=" [--$name=$defaultValue]";
else
$help.=" --$name=value";
}
$options[]=$help;
}
}
return $options;
}
Предоставляет информацию о помощи по опциям команды. Стандартная реализация вернёт всю доступную информацию об действиях вместе с соответствующей информацией об опциях.
init() метод (доступен начиная с v1.1.6)
public void init() |
Инициализирует объект команды. Этот метод вызывается после создания и инициализации объекта команды с конфигурациями. Вы можете переопределить этот метод, чтобы дополнительно настроить команду перед её выполнением.
onAfterAction() метод (доступен начиная с v1.1.11)
public void onAfterAction(CConsoleCommandEvent $event) | ||
| $event | CConsoleCommandEvent | параметр события |
public function onAfterAction($event)
{
$this->raiseEvent('onAfterAction',$event);
}
Это событие срабатывает после завершения выполнения действия.
onBeforeAction() метод (доступен начиная с v1.1.11)
public void onBeforeAction(CConsoleCommandEvent $event) | ||
| $event | CConsoleCommandEvent | параметр события |
public function onBeforeAction($event)
{
$this->raiseEvent('onBeforeAction',$event);
}
Это событие срабатывает перед выполнением действия.
pluralize() метод
public string pluralize(string $name) | ||
| $name | строка | слово, которое нужно привести к множественному числу |
| {возвращает} | строка | слово во множественном числе |
public function pluralize($name)
{
$rules=array(
'/(m)ove$/i' => '\1oves',
'/(f)oot$/i' => '\1eet',
'/(c)hild$/i' => '\1hildren',
'/(h)uman$/i' => '\1umans',
'/(m)an$/i' => '\1en',
'/(s)taff$/i' => '\1taff',
'/(t)ooth$/i' => '\1eeth',
'/(p)erson$/i' => '\1eople',
'/([m|l])ouse$/i' => '\1ice',
'/(x|ch|ss|sh|us|as|is|os)$/i' => '\1es',
'/([^aeiouy]|qu)y$/i' => '\1ies',
'/(?:([^f])fe|([lr])f)$/i' => '\1\2ves',
'/(shea|lea|loa|thie)f$/i' => '\1ves',
'/([ti])um$/i' => '\1a',
'/(tomat|potat|ech|her|vet)o$/i' => '\1oes',
'/(bu)s$/i' => '\1ses',
'/(ax|test)is$/i' => '\1es',
'/s$/' => 's',
);
foreach($rules as $rule=>$replacement)
{
if(preg_match($rule,$name))
return preg_replace($rule,$replacement,$name);
}
return $name.'s';
}
Преобразует слово в его форму множественного числа.
prompt() метод (доступен начиная с v1.1.9)
public mixed prompt(string $message, string $default=NULL) | ||
| $message | строка | вывод перед ожиданием ввода пользователя |
| $default | строка | строка по умолчанию, возвращаемая, если пользователь ничего не вводит. По умолчанию null, значит, строка по умолчанию отключена. Этот параметр доступен начиная с версии 1.1.11. |
| {возвращает} | смешанный тип | прочитанная строка, или false, если ввод был закрыт |
public function prompt($message,$default=null)
{
if($default!==null)
$message.=" [$default] ";
else
$message.=' ';
if(extension_loaded('readline'))
{
$input=readline($message);
if($input!==false)
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;
}
}
Читает ввод через расширение readline PHP, если оно доступно, или fgets(), если readline не установлен.
renderFile() метод
public mixed renderFile(string $_viewFile_, array $_data_=NULL, boolean $_return_=false) | ||
| $_viewFile_ | строка | путь к файлу представления |
| $_data_ | массив | дополнительные данные, которые будут извлечены в качестве локальных переменных представления |
| $_return_ | логическое | отображать ли результат рендеринга, вместо того, чтобы отображать его |
| {возвращает} | смешанный тип | результат рендеринга, если требуется. Иначе null. |
public function renderFile($_viewFile_,$_data_=null,$_return_=false)
{
if(is_array($_data_))
extract($_data_,EXTR_PREFIX_SAME,'data');
else
$data=$_data_;
if($_return_)
{
ob_start();
ob_implicit_flush(false);
require($_viewFile_);
return ob_get_clean();
}
else
require($_viewFile_);
}
Рендерит файл представления.
resolveRequest() метод (доступен начиная с v1.1.5)
protected array resolveRequest(array $args) | ||
| $args | массив | аргументы командной строки |
| {возвращает} | массив | имя действия, именованные опции (имя=>значение) и неименованные опции |
protected function resolveRequest($args)
{
$options=array(); // named parameters
$params=array(); // unnamed parameters
foreach($args as $arg)
{
if(preg_match('/^--(\w+)(=(.*))?$/',$arg,$matches)) // an option
{
$name=$matches[1];
$value=isset($matches[3]) ? $matches[3] : true;
if(isset($options[$name]))
{
if(!is_array($options[$name]))
$options[$name]=array($options[$name]);
$options[$name][]=$value;
}
else
$options[$name]=$value;
}
elseif(isset($action))
$params[]=$arg;
else
$action=$arg;
}
if(!isset($action))
$action=$this->defaultAction;
return array($action,$options,$params);
}
Парсит аргументы командной строки и определяет, какое действие выполнить.
run() метод
public integer run(array $args) | ||
| $args | массив | параметры командной строки для этой команды. |
| {возвращает} | целое число | код завершения приложения, возвращаемый вызванным действием. 0, если действие ничего не вернуло. (значение возврата доступно начиная с версии 1.1.11) |
public function run($args)
{
list($action, $options, $args)=$this->resolveRequest($args);
$methodName='action'.$action;
if(!preg_match('/^\w+$/',$action) || !method_exists($this,$methodName))
$this->usageError("Unknown action: ".$action);
$method=new ReflectionMethod($this,$methodName);
$params=array();
// named and unnamed options
foreach($method->getParameters() as $i=>$param)
{
$name=$param->getName();
if(isset($options[$name]))
{
if($param->isArray())
$params[]=is_array($options[$name]) ? $options[$name] : array($options[$name]);
elseif(!is_array($options[$name]))
$params[]=$options[$name];
else
$this->usageError("Option --$name requires a scalar. Array is given.");
}
elseif($name==='args')
$params[]=$args;
elseif($param->isDefaultValueAvailable())
$params[]=$param->getDefaultValue();
else
$this->usageError("Missing required option --$name.");
unset($options[$name]);
}
// try global options
if(!empty($options))
{
$class=new ReflectionClass(get_class($this));
foreach($options as $name=>$value)
{
if($class->hasProperty($name))
{
$property=$class->getProperty($name);
if($property->isPublic() && !$property->isStatic())
{
$this->$name=$value;
unset($options[$name]);
}
}
}
}
if(!empty($options))
$this->usageError("Unknown options: ".implode(', ',array_keys($options)));
$exitCode=0;
if($this->beforeAction($action,$params))
{
$exitCode=$method->invokeArgs($this,$params);
$exitCode=$this->afterAction($action,$params,is_int($exitCode)?$exitCode:0);
}
return $exitCode;
}
Выполняет команду. Стандартная реализация проанализирует входные параметры и передаст запрос команды соответствующему действию со значениями соответствующих опций
usageError() метод
public void usageError(string $message) | ||
| $message | строка | сообщение об ошибке |
public function usageError($message)
{
echo "Error: $message\n\n".$this->getHelp()."\n";
exit(1);
}
Отображает ошибку использования. Этот метод затем завершит выполнение текущего приложения.
© 2008–2017 by Yii Software LLC
Licensed under the three clause BSD license.
http://www.yiiframework.com/doc/api/1.1/CConsoleCommand