Oihana PHP Commands

helpers

Table of Contents

Functions

assertDomain()  : bool
Validates a domain name according to RFC rules and common DNS restrictions.
clearConsole()  : false|string
Clears the terminal console screen, depending on the operating system.
domainExists()  : bool
Checks whether the given domain has valid DNS records (A, AAAA, or CNAME).
makeCommand()  : string
Generates a complete shell command string, optionally including a pipeline.
silent()  : string|null
Appends a redirection string to suppress output from a shell command.

Functions

assertDomain()

Validates a domain name according to RFC rules and common DNS restrictions.

assertDomain(string $domain[, bool $throw = true ][, bool $requireTld = true ]) : bool
Parameters
$domain : string

The domain name to validate (e.g. "example.com").

$throw : bool = true

Whether to throw an exception on invalid domain.

$requireTld : bool = true

Whether to require a TLD (default true).

Tags
throws
InvalidArgumentException

If the domain is invalid and $throw is true.

author

Marc Alcaraz (ekameleon)

since
1.0.0
example 
use function oihana\commands\helpers\assertDomain;

try
{
   assertDomain("example.com");         // returns true
   assertDomain("sub.domain.org");      // returns true
   assertDomain("invalid_domain");      // throws InvalidArgumentException
}
catch (InvalidArgumentException $e)
{
   echo "Invalid domain: " . $e->getMessage();
}

// Without exception throwing
$isValid = assertDomain("invalid_domain", false);  // returns false
Return values
bool —

True if valid (or silent if $throw = true and valid).

clearConsole()

Clears the terminal console screen, depending on the operating system.

clearConsole([bool $clearable = true ]) : false|string

On Windows systems, it runs cls; on Unix-based systems (Linux/macOS), it runs clear. If $clearable is set to false, the function does nothing and returns false.

Note: The command relies on the system's availability of cls or clear. Use with caution in restricted or sandboxed environments.

Parameters
$clearable : bool = true

Whether or not to perform the console clear.

Tags
example 
clearConsole(); // Clears the screen
clearConsole(false); // Does nothing
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
false|string —

Returns the last line from the shell output, or false on failure or if $clearable is false.

domainExists()

Checks whether the given domain has valid DNS records (A, AAAA, or CNAME).

domainExists(string $domain) : bool
Parameters
$domain : string

The domain to check (e.g. "example.com").

Tags
example 
$domain = 'example.com';

if ( domainExists( $domain ) )
{
    echo "$domain exists.\n";
}
else
{
   echo "$domain does NOT exist.\n";
}
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
bool —

True if DNS records exist for the domain, false otherwise.

makeCommand()

Generates a complete shell command string, optionally including a pipeline.

makeCommand(array<string|int, string>|string|null $command[, array<string|int, string>|string|null $args = null ][, CommandOptions|null $options = null ][, string|null $previous = null ][, string|null $post = null ]) : string

This function builds a shell command from a central main command, optional arguments/options, and optional commands to prepend ($previous) or append ($post) in a pipeline (|).

The main command can be provided as a string or an array (which will be joined by spaces). Arguments and options can also be strings or arrays of strings.

The $options parameter allows adding global prefixes such as sudo or running the command as another user.

If the main command is null, only the pipeline between $previous and $post is generated, and arguments or options are ignored.

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

The main command to run, either as a string (e.g. 'ls') or an array of parts (e.g. ['wp', 'post', 'list']).

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

Arguments and options for the main command (e.g. '-la' or ['--format=ids']).

$options : CommandOptions|null = null

Global command options such as sudo or user context.

$previous : string|null = null

Command to prepend before the main command, for pipelines (e.g. 'cat file.txt').

$post : string|null = null

Command to append after the main command, for pipelines (e.g. 'grep "error"').

Tags
example
  1. Simple command with arguments
$cmd = $this->makeCommand( 'ls' , '-la' ) ;
// Outputs: "ls -la"
  1. Command as an array (safer against shell injection)
$cmd2 = $this->makeCommand(['wp', 'post', 'list'], '--format=ids');
// Outputs: "wp post list --format=ids"
``

3. Command with options (sudo/user)
```php
$options = new CommandOptions(['sudo' => true, 'user' => 'www-data']);
$cmd     = $this->makeCommand('wp cache flush', options: $options );
// Outputs: "sudo -u www-data wp cache flush"
  1. Full pipeline: read a file, filter it, then count lines
$cmd = $this->makeCommand( 'grep "error"', previous: 'cat /var/log/syslog', post: 'wc -l');
// Outputs: "cat /var/log/syslog | grep "error" | wc -l"
  1. Pipeline without a central command (use case for $command = null)
$cmd = $this->makeCommand( previous: 'ls -1 /var/www', post: 'wc -l');
// Outputs: "ls -1 /var/www | wc -l"
  1. Arguments and options are logically ignored if the command is null
$cmd = $this->makeCommand(null, '--force', previous: 'echo "start"');
// Outputs: "echo "start"" (options and arguments are not added)
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
string —

The final full command string to execute, including any pipelines.

silent()

Appends a redirection string to suppress output from a shell command.

silent(string|null &$command[, bool $silent = false ]) : string|null

This helper function modifies the given command string in-place by appending a platform-appropriate silence directive:

  • On Unix/Linux/macOS: > /dev/null 2>&1
  • On Windows: > NUL 2>&1

This is typically used to hide output when executing shell commands.

Parameters
$command : string|null

The command string to modify by reference.

$silent : bool = false

Whether to append the silence directive to the command.

Tags
example 
$cmd = 'wp plugin install hello-dolly';
silent($cmd, true);
echo $cmd;
// Output (Unix)    : wp plugin install hello-dolly > /dev/null 2>&1
// Output (Windows) : wp plugin install hello-dolly > NUL 2>&1
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
string|null —

The updated command string (or null if input was null).


        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results