MediaWiki  master
MediaWiki\Shell\Command Class Reference

Class used for executing shell commands. More...

Inheritance diagram for MediaWiki\Shell\Command:

Public Member Functions

 __construct ()
 Don't call directly, instead use Shell::command() More...
 
 __destruct ()
 Makes sure the programmer didn't forget to execute the command after all. More...
 
 __toString ()
 Returns the final command line before environment/limiting, etc are applied. More...
 
 cgroup ( $cgroup)
 Sets cgroup for this command. More...
 
 environment (array $env)
 Sets environment variables which should be added to the executed command environment. More...
 
 execute ()
 Executes command. More...
 
 forwardStderr (bool $yesno=true)
 If this is set to true, text written to stderr by the command will be passed through to PHP's stderr. More...
 
 includeStderr (bool $yesno=true)
 Controls whether stderr should be included in stdout, including errors from limit.sh. More...
 
 input (string $inputString)
 Sends the provided input to the command. More...
 
 limits (array $limits)
 Sets execution limits. More...
 
 logStderr (bool $yesno=true)
 When enabled, text sent to stderr will be logged with a level of 'error'. More...
 
 params (... $args)
 Adds parameters to the command. More...
 
 passStdin (bool $yesno=true)
 Controls whether stdin is passed through to the command, so that the user can interact with the command when it is run in CLI mode. More...
 
 profileMethod (string $method)
 Sets calling function for profiler. More...
 
 restrict (int $restrictions)
 Set restrictions for this request, overwriting any previously set restrictions. More...
 
 unsafeParams (... $args)
 Adds unsafe parameters to the command. More...
 
 whitelistPaths (array $paths)
 If called, only the files/directories that are whitelisted will be available to the shell command. More...
 

Protected Member Functions

 buildFinalCommand (string $command)
 String together all the options and build the final command to execute. More...
 
 hasRestriction (int $restriction)
 Bitfield helper on whether a specific restriction is enabled. More...
 

Protected Attributes

string $command = ''
 
int $restrictions = 0
 Bitfield with restrictions. More...
 

Private Attributes

string false $cgroup = false
 
bool $doIncludeStderr = false
 
bool $doLogStderr = false
 
bool $doPassStderr = false
 
bool $doPassStdin = false
 
string[] $env = []
 
bool $everExecuted = false
 
string $inputString = ''
 
array $limits
 
string $method
 

Detailed Description

Class used for executing shell commands.

Since
1.30

Definition at line 36 of file Command.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Shell\Command::__construct ( )

Don't call directly, instead use Shell::command()

Exceptions
ShellDisabledError

Definition at line 93 of file Command.php.

References MediaWiki\Shell\Shell\isDisabled().

◆ __destruct()

MediaWiki\Shell\Command::__destruct ( )

Makes sure the programmer didn't forget to execute the command after all.

Definition at line 104 of file Command.php.

References MediaWiki\Shell\Command\$command, MediaWiki\$context, and MediaWiki\Shell\Command\$method.

Member Function Documentation

◆ __toString()

MediaWiki\Shell\Command::__toString ( )

Returns the final command line before environment/limiting, etc are applied.

Use string conversion only for debugging, don't try to pass this to some other execution medium.

Returns
string

Definition at line 628 of file Command.php.

◆ buildFinalCommand()

MediaWiki\Shell\Command::buildFinalCommand ( string  $command)
protected

String together all the options and build the final command to execute.

Parameters
string$commandAlready-escaped command to run
Returns
array [ command, whether to use log pipe ]

Reimplemented in MediaWiki\Shell\FirejailCommand.

Definition at line 344 of file Command.php.

References MediaWiki\Shell\Command\$command, MediaWiki\Shell\Command\cgroup(), MediaWiki\Shell\Command\limits(), and wfIsWindows().

Referenced by MediaWiki\Shell\Command\execute().

◆ cgroup()

MediaWiki\Shell\Command::cgroup (   $cgroup)

Sets cgroup for this command.

Parameters
string | false$cgroupAbsolute file path to the cgroup, or false to not use a cgroup
Returns
$this

Definition at line 277 of file Command.php.

References MediaWiki\Shell\Command\$cgroup.

Referenced by MediaWiki\Shell\Command\buildFinalCommand().

◆ environment()

MediaWiki\Shell\Command::environment ( array  $env)

Sets environment variables which should be added to the executed command environment.

Parameters
string[]$envarray of variable name => value
Returns
$this

Definition at line 182 of file Command.php.

References MediaWiki\Shell\Command\$env.

◆ execute()

MediaWiki\Shell\Command::execute ( )

Executes command.

Afterwards, getExitCode() and getOutput() can be used to access execution results.

Returns
Result
Exceptions
Exception
ProcOpenError
ShellDisabledError

Definition at line 407 of file Command.php.

References MediaWiki\Shell\Command\$inputString, $line, $lines, $res, MediaWiki\Shell\Command\buildFinalCommand(), Profiler\instance(), SHELL_MAX_ARG_STRLEN, wfGetCaller(), and wfIsWindows().

◆ forwardStderr()

MediaWiki\Shell\Command::forwardStderr ( bool  $yesno = true)

If this is set to true, text written to stderr by the command will be passed through to PHP's stderr.

To avoid SIGTTIN/SIGTTOU, and to support Result::getStderr(), the file descriptor is not passed through, we just copy the data to stderr as we receive it.

Parameters
bool$yesno
Returns
$this

Definition at line 240 of file Command.php.

◆ hasRestriction()

MediaWiki\Shell\Command::hasRestriction ( int  $restriction)
protected

Bitfield helper on whether a specific restriction is enabled.

Parameters
int$restriction
Returns
bool

Definition at line 318 of file Command.php.

Referenced by MediaWiki\Shell\FirejailCommand\buildFinalCommand().

◆ includeStderr()

MediaWiki\Shell\Command::includeStderr ( bool  $yesno = true)

Controls whether stderr should be included in stdout, including errors from limit.sh.

Default: don't include.

Parameters
bool$yesno
Returns
$this

Definition at line 253 of file Command.php.

◆ input()

MediaWiki\Shell\Command::input ( string  $inputString)

Sends the provided input to the command.

Defaults to an empty string. If you want to pass stdin through to the command instead, use passStdin().

Parameters
string$inputString
Returns
$this

Definition at line 208 of file Command.php.

References MediaWiki\Shell\Command\$inputString.

◆ limits()

MediaWiki\Shell\Command::limits ( array  $limits)

Sets execution limits.

Parameters
array$limitsAssociative array of limits. Keys (all optional): filesize (for ulimit -f), memory, time, walltime.
Returns
$this

Definition at line 165 of file Command.php.

References MediaWiki\Shell\Command\$limits.

Referenced by MediaWiki\Shell\Command\buildFinalCommand().

◆ logStderr()

MediaWiki\Shell\Command::logStderr ( bool  $yesno = true)

When enabled, text sent to stderr will be logged with a level of 'error'.

Parameters
bool$yesno
Returns
$this

Definition at line 265 of file Command.php.

◆ params()

MediaWiki\Shell\Command::params (   $args)

Adds parameters to the command.

All parameters are sanitized via Shell::escape(). Null values are ignored.

Parameters
string|string[]...$args
Returns
$this

Reimplemented in MediaWiki\Shell\FirejailCommand.

Definition at line 124 of file Command.php.

References $args, and MediaWiki\Shell\Shell\escape().

◆ passStdin()

MediaWiki\Shell\Command::passStdin ( bool  $yesno = true)

Controls whether stdin is passed through to the command, so that the user can interact with the command when it is run in CLI mode.

If this is enabled:

  • The wall clock timeout will be disabled to avoid stopping the process with SIGTTIN/SIGTTOU (T206957).
  • The string specified with input() will be ignored.
Parameters
bool$yesno
Returns
$this

Definition at line 225 of file Command.php.

◆ profileMethod()

MediaWiki\Shell\Command::profileMethod ( string  $method)

Sets calling function for profiler.

By default, the caller for execute() will be used.

Parameters
string$method
Returns
$this

Definition at line 194 of file Command.php.

References MediaWiki\Shell\Command\$method.

◆ restrict()

MediaWiki\Shell\Command::restrict ( int  $restrictions)

Set restrictions for this request, overwriting any previously set restrictions.

Add the "no network" restriction:

Allow LocalSettings.php access:

Disable all restrictions:

Since
1.31
Parameters
int$restrictions
Returns
$this

Definition at line 305 of file Command.php.

References MediaWiki\Shell\Command\$restrictions.

◆ unsafeParams()

MediaWiki\Shell\Command::unsafeParams (   $args)

Adds unsafe parameters to the command.

These parameters are NOT sanitized in any way. Null values are ignored.

Parameters
string|string[]...$args
Returns
$this

Definition at line 142 of file Command.php.

References $args.

◆ whitelistPaths()

MediaWiki\Shell\Command::whitelistPaths ( array  $paths)

If called, only the files/directories that are whitelisted will be available to the shell command.

limit.sh will always be whitelisted

Parameters
string[]$paths
Returns
$this

Reimplemented in MediaWiki\Shell\FirejailCommand.

Definition at line 332 of file Command.php.

Member Data Documentation

◆ $cgroup

string false MediaWiki\Shell\Command::$cgroup = false
private

Definition at line 79 of file Command.php.

Referenced by MediaWiki\Shell\Command\cgroup().

◆ $command

string MediaWiki\Shell\Command::$command = ''
protected

◆ $doIncludeStderr

bool MediaWiki\Shell\Command::$doIncludeStderr = false
private

Definition at line 64 of file Command.php.

◆ $doLogStderr

bool MediaWiki\Shell\Command::$doLogStderr = false
private

Definition at line 67 of file Command.php.

◆ $doPassStderr

bool MediaWiki\Shell\Command::$doPassStderr = false
private

Definition at line 73 of file Command.php.

◆ $doPassStdin

bool MediaWiki\Shell\Command::$doPassStdin = false
private

Definition at line 70 of file Command.php.

◆ $env

string [] MediaWiki\Shell\Command::$env = []
private

Definition at line 55 of file Command.php.

Referenced by MediaWiki\Shell\Command\environment().

◆ $everExecuted

bool MediaWiki\Shell\Command::$everExecuted = false
private

Definition at line 76 of file Command.php.

◆ $inputString

string MediaWiki\Shell\Command::$inputString = ''
private

Definition at line 61 of file Command.php.

Referenced by MediaWiki\Shell\Command\execute(), and MediaWiki\Shell\Command\input().

◆ $limits

array MediaWiki\Shell\Command::$limits
private
Initial value:
= [
'time' => 180,
'walltime' => 180,
'memory' => 307200,
'filesize' => 102400,
]

Definition at line 43 of file Command.php.

Referenced by MediaWiki\Shell\Command\limits().

◆ $method

string MediaWiki\Shell\Command::$method
private

◆ $restrictions

int MediaWiki\Shell\Command::$restrictions = 0
protected

Bitfield with restrictions.

Definition at line 86 of file Command.php.

Referenced by MediaWiki\Shell\Command\restrict().


The documentation for this class was generated from the following file:
MediaWiki\Shell\Command\$command
string $command
Definition: Command.php:40
MediaWiki\Shell\Shell\RESTRICT_DEFAULT
const RESTRICT_DEFAULT
Apply a default set of restrictions for improved security out of the box.
Definition: Shell.php:100
MediaWiki\Shell\Shell\NO_NETWORK
const NO_NETWORK
Restrict the request to have no network access.
Definition: Shell.php:75
MediaWiki\Shell\Shell\RESTRICT_NONE
const RESTRICT_NONE
Don't apply any restrictions.
Definition: Shell.php:108
MediaWiki\Shell\Shell\NO_LOCALSETTINGS
const NO_LOCALSETTINGS
Deny access to LocalSettings.php (MW_CONFIG_FILE)
Definition: Shell.php:90