WP_CLI\Dispatcher
Subcommand{} │ WP-CLI 1.0
A leaf node in the command tree.
No Hooks.
Usage
$Subcommand = new Subcommand(); // use class methods
Methods
- public __construct( $parent, $name, $docparser, $when_invoked )
- public can_have_subcommands()
- private static extract_synopsis( $longdesc )
- public get_alias()
- private get_parameters( $spec = [] )
- public get_synopsis()
- public get_usage( $prefix )
- public invoke( $args, $assoc_args, $extra_args )
- private prompt( $question, $default )
- private prompt_args( $args, $assoc_args )
- public set_synopsis( $synopsis )
- public show_usage( $prefix = 'usage: ' )
- private validate_args( $args, $assoc_args, $extra_args )
Notes
- Package: WP_CLI
Subcommand{} Subcommand{} code WP-CLI 2.8.0-alpha
class Subcommand extends CompositeCommand {
private $alias;
private $when_invoked;
public function __construct( $parent, $name, $docparser, $when_invoked ) {
parent::__construct( $parent, $name, $docparser );
$this->when_invoked = $when_invoked;
$this->alias = $docparser->get_tag( 'alias' );
$this->synopsis = $docparser->get_synopsis();
if ( ! $this->synopsis && $this->longdesc ) {
$this->synopsis = self::extract_synopsis( $this->longdesc );
}
}
/**
* Extract the synopsis from PHPdoc string.
*
* @param string $longdesc Command docs via PHPdoc
* @return string
*/
private static function extract_synopsis( $longdesc ) {
preg_match_all( '/(.+?)[\r\n]+:/', $longdesc, $matches );
return implode( ' ', $matches[1] );
}
/**
* Subcommands can't have subcommands because they
* represent code to be executed.
*
* @return bool
*/
public function can_have_subcommands() {
return false;
}
/**
* Get the synopsis string for this subcommand.
* A synopsis defines what runtime arguments are
* expected, useful to humans and argument validation.
*
* @return string
*/
public function get_synopsis() {
return $this->synopsis;
}
/**
* Set the synopsis string for this subcommand.
*
* @param string $synopsis
*/
public function set_synopsis( $synopsis ) {
$this->synopsis = $synopsis;
}
/**
* If an alias is set, grant access to it.
* Aliases permit subcommands to be instantiated
* with a secondary identity.
*
* @return string
*/
public function get_alias() {
return $this->alias;
}
/**
* Print the usage details to the end user.
*
* @param string $prefix
*/
public function show_usage( $prefix = 'usage: ' ) {
\WP_CLI::line( $this->get_usage( $prefix ) );
}
/**
* Get the usage of the subcommand as a formatted string.
*
* @param string $prefix
* @return string
*/
public function get_usage( $prefix ) {
return sprintf(
'%s%s %s',
$prefix,
implode( ' ', get_path( $this ) ),
$this->get_synopsis()
);
}
/**
* Wrapper for CLI Tools' prompt() method.
*
* @param string $question
* @param string $default
* @return string|false
*/
private function prompt( $question, $default ) {
$question .= ': ';
if ( function_exists( 'readline' ) ) {
return readline( $question );
}
echo $question;
$ret = stream_get_line( STDIN, 1024, "\n" );
if ( Utils\is_windows() && "\r" === substr( $ret, -1 ) ) {
$ret = substr( $ret, 0, -1 );
}
return $ret;
}
/**
* Interactively prompt the user for input
* based on defined synopsis and passed arguments.
*
* @param array $args
* @param array $assoc_args
* @return array
*/
private function prompt_args( $args, $assoc_args ) {
$synopsis = $this->get_synopsis();
if ( ! $synopsis ) {
return [ $args, $assoc_args ];
}
// To skip the already provided positional arguments, we need to count
// how many we had already received.
$arg_index = 0;
$spec = array_filter(
SynopsisParser::parse( $synopsis ),
function( $spec_arg ) use ( $args, $assoc_args, &$arg_index ) {
switch ( $spec_arg['type'] ) {
case 'positional':
// Only prompt for the positional arguments that are not
// yet provided, based purely on number.
return $arg_index++ >= count( $args );
case 'generic':
// Always prompt for generic arguments.
return true;
case 'assoc':
case 'flag':
default:
// Prompt for the specific flags that were not provided
// yet, based on name.
return ! isset( $assoc_args[ $spec_arg['name'] ] );
}
}
);
$spec = array_values( $spec );
$prompt_args = WP_CLI::get_config( 'prompt' );
if ( true !== $prompt_args ) {
$prompt_args = explode( ',', $prompt_args );
}
// 'positional' arguments are positional (aka zero-indexed)
// so $args needs to be reset before prompting for new arguments
$args = [];
foreach ( $spec as $key => $spec_arg ) {
// When prompting for specific arguments (e.g. --prompt=user_pass),
// ignore all arguments that don't match.
if ( is_array( $prompt_args ) ) {
if ( 'assoc' !== $spec_arg['type'] ) {
continue;
}
if ( ! in_array( $spec_arg['name'], $prompt_args, true ) ) {
continue;
}
}
$current_prompt = ( $key + 1 ) . '/' . count( $spec ) . ' ';
$default = $spec_arg['optional'] ? '' : false;
// 'generic' permits arbitrary key=value (e.g. [--<field>=<value>] )
if ( 'generic' === $spec_arg['type'] ) {
list( $key_token, $value_token ) = explode( '=', $spec_arg['token'] );
$repeat = false;
do {
if ( ! $repeat ) {
$key_prompt = $current_prompt . $key_token;
} else {
$key_prompt = str_repeat( ' ', strlen( $current_prompt ) ) . $key_token;
}
$key = $this->prompt( $key_prompt, $default );
if ( false === $key ) {
return [ $args, $assoc_args ];
}
if ( $key ) {
$key_prompt_count = strlen( $key_prompt ) - strlen( $value_token ) - 1;
$value_prompt = str_repeat( ' ', $key_prompt_count ) . '=' . $value_token;
$value = $this->prompt( $value_prompt, $default );
if ( false === $value ) {
return [ $args, $assoc_args ];
}
$assoc_args[ $key ] = $value;
$repeat = true;
} else {
$repeat = false;
}
} while ( $repeat );
} else {
$prompt = $current_prompt . $spec_arg['token'];
if ( 'flag' === $spec_arg['type'] ) {
$prompt .= ' (Y/n)';
}
$response = $this->prompt( $prompt, $default );
if ( false === $response ) {
return [ $args, $assoc_args ];
}
if ( $response ) {
switch ( $spec_arg['type'] ) {
case 'positional':
if ( $spec_arg['repeating'] ) {
$response = explode( ' ', $response );
} else {
$response = [ $response ];
}
$args = array_merge( $args, $response );
break;
case 'assoc':
$assoc_args[ $spec_arg['name'] ] = $response;
break;
case 'flag':
if ( 'Y' === strtoupper( $response ) ) {
$assoc_args[ $spec_arg['name'] ] = true;
}
break;
}
}
}
}
return [ $args, $assoc_args ];
}
/**
* Validate the supplied arguments to the command.
* Throws warnings or errors if arguments are missing
* or invalid.
*
* @param array $args
* @param array $assoc_args
* @param array $extra_args
* @return array list of invalid $assoc_args keys to unset
*/
private function validate_args( $args, $assoc_args, $extra_args ) {
$synopsis = $this->get_synopsis();
if ( ! $synopsis ) {
return [ [], $args, $assoc_args, $extra_args ];
}
$validator = new SynopsisValidator( $synopsis );
$cmd_path = implode( ' ', get_path( $this ) );
foreach ( $validator->get_unknown() as $token ) {
\WP_CLI::warning(
sprintf(
'The `%s` command has an invalid synopsis part: %s',
$cmd_path,
$token
)
);
}
if ( ! $validator->enough_positionals( $args ) ) {
$this->show_usage();
exit( 1 );
}
$unknown_positionals = $validator->unknown_positionals( $args );
if ( ! empty( $unknown_positionals ) ) {
\WP_CLI::error(
'Too many positional arguments: ' .
implode( ' ', $unknown_positionals )
);
}
$synopsis_spec = SynopsisParser::parse( $synopsis );
$i = 0;
$errors = [
'fatal' => [],
'warning' => [],
];
$mock_doc = [ $this->get_shortdesc(), '' ];
$mock_doc = array_merge( $mock_doc, explode( "\n", $this->get_longdesc() ) );
$mock_doc = '/**' . PHP_EOL . '* ' . implode( PHP_EOL . '* ', $mock_doc ) . PHP_EOL . '*/';
$docparser = new DocParser( $mock_doc );
foreach ( $synopsis_spec as $spec ) {
if ( 'positional' === $spec['type'] ) {
$spec_args = $docparser->get_arg_args( $spec['name'] );
if ( ! isset( $args[ $i ] ) ) {
if ( isset( $spec_args['default'] ) ) {
$args[ $i ] = $spec_args['default'];
}
}
if ( isset( $spec_args['options'] ) ) {
if ( ! empty( $spec['repeating'] ) ) {
do {
// phpcs:ignore WordPress.PHP.StrictInArray.MissingTrueStrict -- This is a loose comparison by design.
if ( isset( $args[ $i ] ) && ! in_array( $args[ $i ], $spec_args['options'] ) ) {
\WP_CLI::error( 'Invalid value specified for positional arg.' );
}
$i++;
} while ( isset( $args[ $i ] ) );
} else {
// phpcs:ignore WordPress.PHP.StrictInArray.MissingTrueStrict -- This is a loose comparison by design.
if ( isset( $args[ $i ] ) && ! in_array( $args[ $i ], $spec_args['options'] ) ) {
\WP_CLI::error( 'Invalid value specified for positional arg.' );
}
}
}
$i++;
} elseif ( 'assoc' === $spec['type'] ) {
$spec_args = $docparser->get_param_args( $spec['name'] );
if ( ! isset( $assoc_args[ $spec['name'] ] ) && ! isset( $extra_args[ $spec['name'] ] ) ) {
if ( isset( $spec_args['default'] ) ) {
$assoc_args[ $spec['name'] ] = $spec_args['default'];
}
}
if ( isset( $assoc_args[ $spec['name'] ] ) && isset( $spec_args['options'] ) ) {
$value = $assoc_args[ $spec['name'] ];
$options = $spec_args['options'];
// phpcs:ignore WordPress.PHP.StrictInArray.MissingTrueStrict -- This is a loose comparison by design.
if ( ! in_array( $value, $options ) ) {
// Try whether it might be a comma-separated list of multiple values.
$values = array_map( 'trim', explode( ',', $value ) );
$count = count( $values );
if (
$count > 1
&&
count(
array_filter(
$values,
static function ( $value ) use ( $options ) {
return in_array( $value, $options, true );
}
)
) === $count
) {
continue;
}
$errors['fatal'][ $spec['name'] ] = "Invalid value specified for '{$spec['name']}'";
}
}
}
}
list( $returned_errors, $to_unset ) = $validator->validate_assoc(
array_merge( \WP_CLI::get_config(), $extra_args, $assoc_args )
);
foreach ( [ 'fatal', 'warning' ] as $error_type ) {
$errors[ $error_type ] = array_merge( $errors[ $error_type ], $returned_errors[ $error_type ] );
}
if ( 'help' !== $this->name ) {
foreach ( $validator->unknown_assoc( $assoc_args ) as $key ) {
$suggestion = Utils\get_suggestion(
$key,
$this->get_parameters( $synopsis_spec ),
$threshold = 2
);
$errors['fatal'][] = sprintf(
'unknown --%s parameter%s',
$key,
! empty( $suggestion ) ? PHP_EOL . "Did you mean '--{$suggestion}'?" : ''
);
}
}
if ( ! empty( $errors['fatal'] ) ) {
$out = 'Parameter errors:';
foreach ( $errors['fatal'] as $key => $error ) {
$out .= "\n {$error}";
$desc = $docparser->get_param_desc( $key );
if ( '' !== $desc ) {
$out .= " ({$desc})";
}
}
\WP_CLI::error( $out );
}
array_map( '\\WP_CLI::warning', $errors['warning'] );
return [ $to_unset, $args, $assoc_args, $extra_args ];
}
/**
* Invoke the subcommand with the supplied arguments.
* Given a --prompt argument, interactively request input
* from the end user.
*
* @param array $args
* @param array $assoc_args
*/
public function invoke( $args, $assoc_args, $extra_args ) {
static $prompted_once = false;
if ( 'help' !== $this->name ) {
if ( \WP_CLI::get_config( 'prompt' ) && ! $prompted_once ) {
list( $_args, $assoc_args ) = $this->prompt_args( $args, $assoc_args );
$args = array_merge( $args, $_args );
$prompted_once = true;
}
}
$extra_positionals = [];
foreach ( $extra_args as $k => $v ) {
if ( is_numeric( $k ) ) {
if ( ! isset( $args[ $k ] ) ) {
$extra_positionals[ $k ] = $v;
}
unset( $extra_args[ $k ] );
}
}
$args += $extra_positionals;
list( $to_unset, $args, $assoc_args, $extra_args ) = $this->validate_args( $args, $assoc_args, $extra_args );
foreach ( $to_unset as $key ) {
unset( $assoc_args[ $key ] );
}
$path = get_path( $this->get_parent() );
$parent = implode( ' ', array_slice( $path, 1 ) );
$cmd = $this->name;
if ( $parent ) {
WP_CLI::do_hook( "before_invoke:{$parent}", $parent );
$cmd = $parent . ' ' . $cmd;
}
WP_CLI::do_hook( "before_invoke:{$cmd}", $cmd );
// Check if `--prompt` arg passed or not.
if ( $prompted_once ) {
// Unset empty args.
$actual_args = $assoc_args;
foreach ( $actual_args as $key ) {
if ( empty( $actual_args[ $key ] ) ) {
unset( $actual_args[ $key ] );
}
}
WP_CLI::log(
sprintf(
'wp %s %s',
$cmd,
ltrim( Utils\assoc_args_to_str( $actual_args ), ' ' )
)
);
}
call_user_func( $this->when_invoked, $args, array_merge( $extra_args, $assoc_args ) );
if ( $parent ) {
WP_CLI::do_hook( "after_invoke:{$parent}", $parent );
}
WP_CLI::do_hook( "after_invoke:{$cmd}", $cmd );
}
/**
* Get an array of parameter names, by merging the command-specific and the
* global parameters.
*
* @param array $spec Optional. Specification of the current command.
*
* @return array Array of parameter names
*/
private function get_parameters( $spec = [] ) {
$local_parameters = array_column( $spec, 'name' );
$global_parameters = array_column(
SynopsisParser::parse( $this->get_global_params() ),
'name'
);
return array_unique( array_merge( $local_parameters, $global_parameters ) );
}
}