Page MenuHomePhorge

final class PhutilExecPassthru
libphutil Technical Documentation (Futures)

Execute a command which takes over stdin, stdout and stderr, similar to passthru(), but which preserves TTY semantics, escapes arguments, and is traceable.

Passthru commands use the STDIN, STDOUT and STDERR of the parent process, so input can be read from the console and output is printed to it. This is primarily useful for executing things like $EDITOR from command line scripts.

$exec = new PhutilExecPassthru('nano -- %s', $filename);
$err = $exec->resolve();

You can set the current working directory for the command with setCWD(), and set the environment with setEnv().

Tasks

Configuring the Command

  • final public function setEnv($env, $wipe_process_env) — Set environmental variables for the command.
  • final public function updateEnv($key, $value) — Set the value of a specific environmental variable for this command.
  • final public function hasEnv() — Returns `true` if this command has a configured environment.
  • final public function getEnv() — Get the configured environment.
  • final public function setCWD($cwd) — Set the current working directory for the subprocess (that is, set where the subprocess will execute). If not set, the default value is the parent's current working directory.
  • final public function getCWD() — Get the command's current working directory.

Executing Passthru Commands

Other Methods

Methods

public function __get($name)
Inherited

This method is not documented.
Parameters
$name
Return
wild

public function __set($name, $value)
Inherited

This method is not documented.
Parameters
$name
$value
Return
wild

public function current()
Inherited

This method is not documented.
Return
wild

public function key()
Inherited

This method is not documented.
Return
wild

public function next()
Inherited

This method is not documented.
Return
wild

public function rewind()
Inherited

This method is not documented.
Return
wild

public function valid()
Inherited

This method is not documented.
Return
wild

private function throwOnAttemptedIteration()
Inherited

This method is not documented.
Return
wild

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

Phobject

Read the value of a class constant.

This is the same as just typing self::CONSTANTNAME, but throws a more useful message if the constant is not defined and allows the constant to be limited to a maximum length.

Parameters
string$keyName of the constant.
int|null$byte_limitMaximum number of bytes permitted in the value.
Return
stringValue of the constant.

public function isReady()

Future

Is this future's process complete? Specifically, can this future be resolved without blocking?

PhutilExecPassthru
This method is not documented.
Return
boolIf true, the external process is complete and resolving this future will not block.

public function resolve()
Inherited

Future

Resolve a future and return its result, blocking until the result is ready if necessary.

Return
wildFuture result.

final public function updateFuture()
Inherited

This method is not documented.
Return
wild

private function startServiceProfiler()
Inherited

This method is not documented.
Return
wild

private function endServiceProfiler()
Inherited

This method is not documented.
Return
wild
This method is not documented.
Return
wild
This method is not documented.
Return
wild

public function getReadSockets()
Inherited

Future

Retrieve a list of sockets which we can wait to become readable while a future is resolving. If your future has sockets which can be select()ed, return them here (or in getWriteSockets()) to make the resolve loop do a select(). If you do not return sockets in either case, you'll get a busy wait.

Return
listA list of sockets which we expect to become readable.

public function getWriteSockets()
Inherited

Future

Retrieve a list of sockets which we can wait to become writable while a future is resolving. See getReadSockets().

Return
listA list of sockets which we expect to become writable.

public function getDefaultWait()
Inherited

Future

Default amount of time to wait on stream select for this future. Normally 1 second is fine, but if the future has a timeout sooner than that it should return the amount of time left before the timeout.

Return
wild

public function start()
Inherited

This method is not documented.
Return
wild

final protected function getResult()
Inherited

Future

Retrieve the final result of the future.

Return
wildFinal resolution of this future.

final protected function setResult($result)
Inherited

This method is not documented.
Parameters
$result
Return
wild

final public function hasResult()
Inherited

This method is not documented.
Return
wild

private function setException($exception)
Inherited

This method is not documented.
Parameters
$exception
Return
wild

private function getException()
Inherited

This method is not documented.
Return
wild

final public function hasException()
Inherited

This method is not documented.
Return
wild

final public function setFutureKey($key)
Inherited

This method is not documented.
Parameters
$key
Return
wild

final public function getFutureKey()
Inherited

This method is not documented.
Return
wild

final public function setRaiseExceptionOnStart($raise)
Inherited

This method is not documented.
Parameters
$raise
Return
wild

final public function getHasFutureStarted()
Inherited

This method is not documented.
Return
wild

final public function canResolve()
Inherited

This method is not documented.
Return
wild

private function endFuture()
Inherited

This method is not documented.
Return
wild

final public function __construct($pattern)
Inherited

This method is not documented.
Parameters
$pattern
Return
this//Implicit.//

protected function didConstruct()
Inherited

This method is not documented.
Return
wild

final public function setResolveOnError($resolve_on_error)
Inherited

This method is not documented.
Parameters
$resolve_on_error
Return
wild

final public function getResolveOnError()
Inherited

This method is not documented.
Return
wild

final public function getCommand()
Inherited

This method is not documented.
Return
wild

final public function setEnv($env, $wipe_process_env)
Inherited

PhutilExecutableFuture

Set environmental variables for the command.

By default, variables are added to the environment of this process. You can optionally wipe the environment and pass only the specified values.

// Env will have "X" and current env ("PATH", etc.)
$exec->setEnv(array('X' => 'y'));

// Env will have ONLY "X".
$exec->setEnv(array('X' => 'y'), $wipe_process_env = true);
Parameters
map<string,$envstring> Dictionary of environmental variables.
bool$wipe_process_envOptionally, pass `true` to replace the existing environment.
Return
this

final public function updateEnv($key, $value)
Inherited

PhutilExecutableFuture

Set the value of a specific environmental variable for this command.

Parameters
string$keyEnvironmental variable name.
string|null$valueNew value, or null to remove this variable.
Return
this

final public function hasEnv()
Inherited

PhutilExecutableFuture

Returns true if this command has a configured environment.

Return
boolTrue if this command has an environment.

final public function getEnv()
Inherited

PhutilExecutableFuture

Get the configured environment.

Return
map<string, string>Effective environment for this command.

final public function setCWD($cwd)
Inherited

PhutilExecutableFuture

Set the current working directory for the subprocess (that is, set where the subprocess will execute). If not set, the default value is the parent's current working directory.

Parameters
string$cwdDirectory to execute the subprocess in.
Return
this

final public function getCWD()
Inherited

PhutilExecutableFuture

Get the command's current working directory.

Return
stringWorking directory.

public function write($data)

This method is not documented.
Parameters
$data
Return
wild

public function execute()

This method is not documented.
Return
wild

private function executeCommand()

Execute this command.

Return
intError code returned by the subprocess.