Oihana PHP Commands

FileTrait uses trait:short

The trait to manage files.

Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Properties

$commandOptions  : CommandOptions|null
The global command options.

Methods

deleteFile()  : int
Deletes a file.
exec()  : string
Executes a shell command with optional sudo/user context and silent mode and returns the output of the command.
makeFile()  : int
Creates a file at the specified path with the given contents.
proc()  : Process
Executes a shell command using proc_open, capturing stdout, stderr, and the exit status.
system()  : int
Executes a shell command with optional sudo/user context and silent mode.
initializeCommandOptions()  : static
Initialize the global command options.

Properties

Methods

deleteFile()

Deletes a file.

public deleteFile(string|null $filePath[, null|array<string|int, mixed>|CommandOptions $options = null ][, bool $verbose = false ][, bool $assertable = false ][, bool $sudo = false ][, bool $dryRun = false ]) : int
Parameters
$filePath : string|null

The absolute path to the file to create.

$options : null|array<string|int, mixed>|CommandOptions = null

Optional command options, such as sudo or user context.

$verbose : bool = false

Whether to output verbose logs.

$assertable : bool = false

If true, asserts file existence and permissions before deletion.

$sudo : bool = false

If true, the command is automatically prefixed with sudo to run with elevated privileges.

$dryRun : bool = false

If true, simulates the execution without actually running the command. Always returns 0.

Tags
throws
FileException

It the file path is not valid or the file not exist.

Return values
int

exec()

Executes a shell command with optional sudo/user context and silent mode and returns the output of the command.

public exec(null|array<string|int, mixed>|string $command[, null|array<string|int, mixed>|string $args = null ][, CommandOptions|null $options = null ][, bool $silent = false ][, bool $verbose = false ][, string|null $previous = null ][, string|null $post = null ][, bool $sudo = false ][, bool $dryRun = false ]) : string
Parameters
$command : null|array<string|int, mixed>|string

The base shell command to execute (e.g. "wp plugin install").

$args : null|array<string|int, mixed>|string = null

Optional additional arguments appended to the command, a string or an array of arguments.

$options : CommandOptions|null = null

Whether to prefix the command with sudo. Defaults to $this->sudo.

$silent : bool = false

Whether to suppress the command's output.

$verbose : bool = false

Verbose the error message.

$previous : string|null = null

The previous command to append.

$post : string|null = null

The post command to append at the end.

$sudo : bool = false

If true, the command is automatically prefixed with sudo to run with elevated privileges.

$dryRun : bool = false

If true, simulates the execution without actually running the command. Always returns 0.

Tags
throws
RuntimeException

If the command returned no output.

example 
$this->system('wp theme install hello-elementor', '--path=/var/www/site' );
$this->system('ls', '-la', new CommandOptions([ 'sudo' => true, 'user' => 'www-data');
Return values
string —

The output of the command.

makeFile()

Creates a file at the specified path with the given contents.

public makeFile(string|null $filePath[, string|null $content = '' ][, null|array<string|int, mixed>|CommandOptions $options = null ][, bool $verbose = false ][, bool $sudo = false ][, bool $dryRun = false ]) : int

If the parent directory does not exist, it is created.

Parameters
$filePath : string|null

The absolute path to the file to create.

$content : string|null = ''

The content to write; if null, an empty file is created@param null|array|CommandOptions $options Optional command options, such as sudo or user context..

$options : null|array<string|int, mixed>|CommandOptions = null

Optional command options, such as sudo or user context.

$verbose : bool = false

Whether to output verbose logs.

$sudo : bool = false

If true, the command is automatically prefixed with sudo to run with elevated privileges.

$dryRun : bool = false

If true, simulates the execution without actually running the command. Always returns 0.

Tags
throws
RuntimeException

If the directory or file cannot be created.

example 
$this->createFile
(
    '/var/www/html/robots.txt',
    'User-agent: *' . PHP_EOL . 'Disallow: /private/'
);
Return values
int —

ExitCode::SUCCESS (0) if the file creation succeeds.

proc()

Executes a shell command using proc_open, capturing stdout, stderr, and the exit status.

public proc(null|array<string|int, mixed>|string $command[, null|array<string|int, mixed>|string $args = null ][, CommandOptions|null $options = null ][, bool $verbose = false ][, string|null $previous = null ][, string|null $post = null ][, bool $sudo = false ][, bool $dryRun = false ]) : Process

This method builds a full command from the base command, optional arguments, and optional sudo/user context. It provides full control over the execution environment and captures both standard output and error output separately.

Parameters
$command : null|array<string|int, mixed>|string

The base shell command to execute (e.g. "wp plugin list").

$args : null|array<string|int, mixed>|string = null

Optional arguments to pass to the command. Can be a string or array.

$options : CommandOptions|null = null

Optional command options, such as sudo or user context.

$verbose : bool = false

Whether to display the full command before execution.

$previous : string|null = null

The previous command to append.

$post : string|null = null

The post command to append at the end.

$sudo : bool = false

If true, the command is automatically prefixed with sudo to run with elevated privileges.

$dryRun : bool = false

If true, simulates the execution without actually running the command. Always returns 0.

Tags
throws
RuntimeException

If the process could not be started.

example 
$result = $this->proc( 'wp post list' , ' --format=ids') ;
if ( $result->status === 0 )
{
    $ids = explode( PHP_EOL , $result->output ) ;
}
Return values
Process

system()

Executes a shell command with optional sudo/user context and silent mode.

public system(null|array<string|int, mixed>|string $command[, null|array<string|int, mixed>|string $args = null ][, null|array<string|int, mixed>|CommandOptions $options = null ][, bool $silent = false ][, bool $verbose = false ][, string|null $previous = null ][, string|null $post = null ][, bool $sudo = false ][, bool $dryRun = false ]) : int

This method builds and executes a shell command string, optionally prefixed with sudo -u <user>. It can suppress output using the makeSilent() method and throws an exception on failure.

Parameters
$command : null|array<string|int, mixed>|string

The base shell command to execute (e.g. "wp plugin install").

$args : null|array<string|int, mixed>|string = null

Optional additional arguments appended to the command, a string or an array of arguments.

$options : null|array<string|int, mixed>|CommandOptions = null

Whether to prefix the command with sudo. Defaults to $this->sudo.

$silent : bool = false

Whether to suppress the command's output.

$verbose : bool = false

Verbose the error message.

$previous : string|null = null

Optional command to prepend (e.g., cd /path &&).

$post : string|null = null

Optional command to append after execution (e.g., ; echo done).

$sudo : bool = false

If true, the command is automatically prefixed with sudo to run with elevated privileges.

$dryRun : bool = false

If true, simulates the execution without actually running the command. Always returns 0.

Tags
throws
RuntimeException

RuntimeException If the command fails and $dryRun is false.

example 
$this->system('wp theme install hello-elementor', '--path=/var/www/site' );
$this->system('ls', '-la', new CommandOptions([ 'sudo' => true, 'user' => 'www-data');
$this->system('rm -rf /tmp/sandbox', verbose:true, dryRun: true); // dry-run, shows command
Return values
int —

The result code of the command (0 if successful).

initializeCommandOptions()

Initialize the global command options.

protected initializeCommandOptions([array<string|int, mixed> $init = [] ]) : static
Parameters
$init : array<string|int, mixed> = []
Return values
static 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results