WP_CLI::runcommand │ public static │ WP-CLI 1.0

Run a WP-CLI command.

Launches a new child process to run a specified WP-CLI command. Optionally:

• Run the command in an existing process.
• Prevent halting script execution on error.
• Capture and return STDOUT, or full details about command execution.
• Parse JSON output if the command rendered it.
• Include additional arguments that are passed to the command.

$options = array(
  'return'       => true,                // Return 'STDOUT'; use 'all' for full object.
  'parse'        => 'json',              // Parse captured STDOUT to JSON array.
  'launch'       => false,               // Reuse the current process.
  'exit_error'   => true,                // Halt script execution on error.
  'command_args' => [ '--skip-themes' ], // Additional arguments to be passed to the $command.
);
$plugins = WP_CLI::runcommand( 'plugin list --format=json', $options );

Method of the class: WP_CLI{}

No Hooks.

Returns

Mixed.

Usage

$result = WP_CLI::runcommand( $command, $options );

$command(string) (required)

WP-CLI command to run, including arguments.

$options(array)

Configuration options for command execution.

Default: []

• launch(true|false)
  Launches a new process (true) or reuses the existing process (false).
  Default: true

• exit_error(true|false)
  Halts the script on error.
  Default: true

• return(true|false|string)
  Returns output as an object when set to 'all' (string), return just the 'stdout', 'stderr', or 'return_code' (string) of command, or print directly to stdout/stderr (false).
  Default: false

• parse(true|false|string)
  Parse returned output as 'json' (string); otherwise, output is unchanged (false).
  Default: false

WP_CLI::runcommand() WP CLI::runcommand code ^{WP-CLI 2.13.0-alpha}

public static function runcommand( $command, $options = [] ) {
	$defaults     = [
		'launch'       => true,  // Launch a new process, or reuse the existing.
		'exit_error'   => true,  // Exit on error by default.
		'return'       => false, // Capture and return output, or render in realtime.
		'parse'        => false, // Parse returned output as a particular format.
		'command_args' => [],    // Include optional command arguments.
	];
	$options      = array_merge( $defaults, $options );
	$launch       = $options['launch'];
	$exit_error   = $options['exit_error'];
	$return       = $options['return'];
	$parse        = $options['parse'];
	$command_args = $options['command_args'];

	if ( ! empty( $command_args ) ) {
		$command .= ' ' . implode( ' ', $command_args );
	}

	$retval = null;
	if ( $launch ) {
		Utils\check_proc_available( 'launch option' );

		$descriptors = [
			0 => STDIN,
			1 => STDOUT,
			2 => STDERR,
		];

		if ( $return ) {
			$descriptors = [
				0 => STDIN,
				1 => [ 'pipe', 'w' ],
				2 => [ 'pipe', 'w' ],
			];
		}

		$php_bin     = escapeshellarg( Utils\get_php_binary() );
		$script_path = $GLOBALS['argv'][0];

		// Persist runtime arguments unless they've been specified otherwise.
		$configurator = self::get_configurator();
		$argv         = array_slice( $GLOBALS['argv'], 1 );

		list( $ignore1, $ignore2, $runtime_config ) = $configurator->parse_args( $argv );
		foreach ( $runtime_config as $k => $v ) {
			if ( preg_match( "|^--{$k}=?$|", $command ) ) {
				unset( $runtime_config[ $k ] );
			}
		}
		$runtime_config = Utils\assoc_args_to_str( $runtime_config );

		$runcommand = "{$php_bin} {$script_path} {$runtime_config} {$command}";

		$pipes = [];
		$proc  = Utils\proc_open_compat( $runcommand, $descriptors, $pipes, getcwd() );

		$stdout = '';
		$stderr = '';

		if ( $return ) {
			$stdout = stream_get_contents( $pipes[1] );
			fclose( $pipes[1] );
			$stderr = stream_get_contents( $pipes[2] );
			fclose( $pipes[2] );
		}
		$return_code = proc_close( $proc );
		if ( -1 === $return_code ) {
			self::warning( 'Spawned process returned exit code -1, which could be caused by a custom compiled version of PHP that uses the --enable-sigchild option.' );
		} elseif ( $return_code && $exit_error ) {
			exit( $return_code );
		}
		if ( true === $return || 'stdout' === $return ) {
			$retval = trim( $stdout );
		} elseif ( 'stderr' === $return ) {
			$retval = trim( $stderr );
		} elseif ( 'return_code' === $return ) {
			$retval = $return_code;
		} elseif ( 'all' === $return ) {
			$retval = (object) [
				'stdout'      => trim( $stdout ),
				'stderr'      => trim( $stderr ),
				'return_code' => $return_code,
			];
		}
	} else {
		$configurator                               = self::get_configurator();
		$argv                                       = Utils\parse_str_to_argv( $command );
		list( $args, $assoc_args, $runtime_config ) = $configurator->parse_args( $argv );
		if ( $return ) {
			$existing_logger = self::$logger;
			self::$logger    = new Execution();
			self::$logger->ob_start();
		}
		if ( ! $exit_error ) {
			self::$capture_exit = true;
		}
		try {
			self::get_runner()->run_command(
				$args,
				$assoc_args,
				[
					'back_compat_conversions' => true,
				]
			);
			$return_code = 0;
		} catch ( ExitException $e ) {
			$return_code = $e->getCode();
		}
		if ( $return ) {
			$execution_logger = self::$logger;
			$execution_logger->ob_end();
			self::$logger = $existing_logger;
			$stdout       = $execution_logger->stdout;
			$stderr       = $execution_logger->stderr;
			if ( true === $return || 'stdout' === $return ) {
				$retval = trim( $stdout );
			} elseif ( 'stderr' === $return ) {
				$retval = trim( $stderr );
			} elseif ( 'return_code' === $return ) {
				$retval = $return_code;
			} elseif ( 'all' === $return ) {
				$retval = (object) [
					'stdout'      => trim( $stdout ),
					'stderr'      => trim( $stderr ),
					'return_code' => $return_code,
				];
			}
		}
		if ( ! $exit_error ) {
			self::$capture_exit = false;
		}
	}
	if ( ( true === $return || 'stdout' === $return )
		&& 'json' === $parse ) {
		$retval = json_decode( $retval, true );
	}
	return $retval;
}