Command
in package
uses
BaseTraits
Defines an object that executes shell commands and keeps track of the output and result codes.
Table of Contents
Properties
- $command : string
- $escape : bool
- $escape_pipe : bool
- $output : string
- $pipe : string
- $redirect : string
- $result_code : int
- $trim_whitespace : bool
- $__log_level : int
Methods
- __construct() : Command
- Defines the Command object including the shell command to execute and optional modifiers. Note: By default, the command output will redirect stderr to stdout so error message will be included in the output.
- escape_command() : string
- Escapes a raw command string by tokenizing it (respecting quoted substrings) and applying escapeshellarg() to every token before re-joining with spaces. This prevents command injection regardless of whether the original string contained pre-quoted or unquoted arguments.
- get_class_fqn() : string
- Obtains the fully qualified name of the called class.
- get_class_shortname() : string
- Obtains the shortname of the called class.
- get_classes_in_namespace() : array<string|int, mixed>
- Obtains all classes associated with this class's current namespace.
- log() : void
- Writes a log entry to the applicable log file
- tokenize_command() : array<string|int, string>
- Parses a raw command string into an array of argument tokens, respecting single- and double-quoted substrings so that spaces inside quotes are not treated as delimiters. Surrounding quotes are stripped from each token so that the value can be re-escaped uniformly by escape_command().
- run_command() : void
- Executes the assigned $command. The $output and $result_code properties will be set after running this method.
Properties
$command
public
string
$command
The shell command this object should execute.
$escape
public
bool
$escape
= true
Whether to automatically escape each token in the command string before execution. Defaults to true. Set to false only when the caller has already performed its own escaping or when shell features such as pipes, redirects, or glob expansion are intentionally required.
$escape_pipe
public
bool
$escape_pipe
= true
Whether to automatically escape the tokens of the $pipe command string. Defaults
to true. Set to false when the pipe command contains shell features (e.g. grep "some pattern") that
must be passed verbatim.
$output
public
string
$output
= ''
The output of the executed shell command.
$pipe
public
string
$pipe
= ''
An optional command string to pipe the output of $command into. When set, the shell
pipeline <command> | <pipe> is constructed. The pipe command is escaped independently according to
$escape_pipe. Use this instead of embedding | in the raw $command string, which would be neutralised
by auto-escaping.
$redirect
public
string
$redirect
An optional shell redirect to append to the end of the $command.
$result_code
public
int
$result_code
= -1
The exit/return code of the executed shell command.
$trim_whitespace
public
bool
$trim_whitespace
= false
Automatically remove excessive whitespace from the command $output.
$__log_level
private
static int
$__log_level
Methods
__construct()
Defines the Command object including the shell command to execute and optional modifiers. Note: By default, the command output will redirect stderr to stdout so error message will be included in the output.
public
__construct(string $command[, bool $trim_whitespace = false ][, string $redirect = '2>&1' ][, bool $escape = true ][, string $pipe = '' ][, bool $escape_pipe = true ]) : Command
Parameters
- $command : string
-
The shell command to execute.
- $trim_whitespace : bool = false
-
Remove excessive whitespace from the command output.
- $redirect : string = '2>&1'
-
An optional shell redirect to append to the end of the $command.
- $escape : bool = true
-
Automatically escape each token in the command string before execution. Defaults to true. Set to false only when the caller has already performed its own escaping or when shell features such as pipes, redirects, or glob expansion are intentionally required.
- $pipe : string = ''
-
An optional command string to pipe the output of $command into. Escaped independently according to $escape_pipe.
- $escape_pipe : bool = true
-
Whether to automatically escape the tokens of the $pipe command. Defaults to true.
Return values
Command —Returns this object containing the results of the executed command. Note: the object returned cannot be used to initiate new commands. A new Command object should be created for any additional commands.
escape_command()
Escapes a raw command string by tokenizing it (respecting quoted substrings) and applying escapeshellarg() to every token before re-joining with spaces. This prevents command injection regardless of whether the original string contained pre-quoted or unquoted arguments.
public
static escape_command(string $command) : string
Parameters
- $command : string
-
The raw command string to escape.
Return values
string —The fully escaped command string ready for exec().
get_class_fqn()
Obtains the fully qualified name of the called class.
public
static get_class_fqn() : string
Return values
string —The FQN for this object's class.
get_class_shortname()
Obtains the shortname of the called class.
public
static get_class_shortname() : string
Return values
string —The shortname for this object's class.
get_classes_in_namespace()
Obtains all classes associated with this class's current namespace.
public
get_classes_in_namespace([bool $shortnames = false ]) : array<string|int, mixed>
Parameters
- $shortnames : bool = false
Return values
array<string|int, mixed> —An array of classes currently in this object's namespace
log()
Writes a log entry to the applicable log file
public
static log(int $level, string $message[, string $logfile = 'restapi' ]) : void
Parameters
- $level : int
-
The log level to write. This should be one of the LOG_* constants defined by syslog.
- $message : string
-
The message to write to the log file.
- $logfile : string = 'restapi'
-
The log file to write to. This must be a valid logging facility defined in the package's info.xml file.
tokenize_command()
Parses a raw command string into an array of argument tokens, respecting single- and double-quoted substrings so that spaces inside quotes are not treated as delimiters. Surrounding quotes are stripped from each token so that the value can be re-escaped uniformly by escape_command().
public
static tokenize_command(string $command) : array<string|int, string>
Parameters
- $command : string
-
The raw command string to tokenize.
Return values
array<string|int, string> —An ordered list of unquoted token strings.
run_command()
Executes the assigned $command. The $output and $result_code properties will be set after running this method.
private
run_command() : void