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.

$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.
);
$plugins = WP_CLI::runcommand( 'plugin list --format=json', $options );

Method of the class: WP_CLI{}

No Hooks.

Return

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: []

WP_CLI::runcommand() WP CLI::runcommand code ^{WP-CLI 2.8.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.
	];
	$options    = array_merge( $defaults, $options );
	$launch     = $options['launch'];
	$exit_error = $options['exit_error'];
	$return     = $options['return'];
	$parse      = $options['parse'];
	$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() );

		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;
}