Oihana PHP Commands

ChownTrait uses trait:short

Adds support for executing the `chown` command with customizable options, either via direct arguments or an injected {@see ChownOptions} object.

This trait is intended to be used within a command-handling context, and requires a working implementation of system() (from CommandTrait).

Features:

  • Owner and group can be passed directly or via ChownOptions
  • Supports sudo execution
  • Optional strict mode to control validation behavior
  • Graceful no-op execution when strict=false and conditions aren't met

Example:

$this->chown('/var/www/html', 'www-data', null);
$this->chown('/var/www/example.com/www/htdocs', 'www-data', 'www-data' );
Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Constants

CHOWN_COMMAND  = 'chown'
Key used in configuration arrays to refer to the `chown` section.

Properties

$chownOptions  : ChownOptions|null
Holds the `ChownOptions` instance if initialized or injected.
$commandOptions  : CommandOptions|null
The global command options.

Methods

chown()  : int
Executes a `chown` operation on a given path.
exec()  : string
Executes a shell command with optional sudo/user context and silent mode and returns the output of the command.
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.
initializeChownOptions()  : static
Initializes the `$chownOptions` property from an input array.
initializeCommandOptions()  : static
Initialize the global command options.

Constants

CHOWN_COMMAND

Key used in configuration arrays to refer to the `chown` section.

public mixed CHOWN_COMMAND = 'chown'

Properties

$chownOptions

Holds the `ChownOptions` instance if initialized or injected.

public ChownOptions|null $chownOptions

Methods

chown()

Executes a `chown` operation on a given path.

public chown([string|null $path = null ][, string|null $owner = null ][, string|null $group = null ][, null|array<string|int, mixed>|ChownOptions $options = null ][, bool $silent = false ][, bool $verbose = false ][, bool $strict = true ][, bool|null $sudo = null ]) : int

The owner and group may be specified directly or inferred from the given ChownOptions instance or the trait's $chownOptions property.

If strict is true, a RuntimeException is thrown when required values (owner/group or path) are missing. Otherwise, the method returns ExitCode::SUCCESS silently or with a warning if verbose is true.

Parameters
$path : string|null = null

Path to apply the ownership change to.

$owner : string|null = null

Owner user (e.g., www-data). Optional.

$group : string|null = null

Group name (e.g., www-data). Optional.

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

Optional options instance. If null, uses $this->chownOptions.

$silent : bool = false

If true, suppresses system command output.

$verbose : bool = false

If true, displays warnings when skipping.

$strict : bool = true

If true (default), throws on missing values.

$sudo : bool|null = null

Enforce to use sudo if true.

Tags
throws
RuntimeException

If required values are missing and strict is true.

Return values
int —

ExitCode::SUCCESS (0) if the command runs or is skipped successfully.

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.

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).

initializeChownOptions()

Initializes the `$chownOptions` property from an input array.

protected initializeChownOptions([array<string, mixed> $init = [] ]) : static
Parameters
$init : array<string, mixed> = []

Array of options, or an array containing the 'chown' key.

Return values
static —

For method chaining.

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