Description

This library abstracts the access to a console via adapters. Out of the box there is a local and a ssh adapter. These adapters enable you to execute commands localy and remotely without having to do if checks and stuff.

Getting started

composer require mrcrankhank/console-access

Documentation

Examples

These examples assume, that you include the composer autoloader somewhere and that you pulled in the necessary classes via use at the top.

Local

// create a new adapter
$adapter = new LocalAdapter;

// create a new console
$console = new ConsoleAccess($adapter);

// execute the command
$console->bin('pwd')->exec();

// fetch output
echo $console->getOutput();

// fetch exit status
echo $console->getExitStatus();

SSH with password

/*
 * create a new adapter
 * provide host, user and (for security reasons) the public
 * key of the host (in debian: "/etc/ssh/ssh_host_rsa_key.pub")
 */
$adapter = new SshAdapter('127.0.0.1', 'user', 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDZCcmN09Wa62slAy2ASo+/TVlYIb4GufKAV02hjrYhzxCkOdxJOqLmfjkenr+hKAtBf4bHvVFZGI3jd12rLSgMTG7h53Zumv5r4oIl+SBxB/+U2PEk8X5XEDRvR1eP5+3fdAB8w/Ds4KI7HGMG0IkSvP8Gqlsq6AE/t6rQI8ac52bWHkmBHa7Ebt3JIKbi6E0HdCq0Qy35GadVCaBJRW49oqxYL1hVrcifB4DscqarU35+zDO6UYPdiFgfgfIFTIcB9nPAwiOmHkg+4uJbonZyjGSr+phYj0BIQ4JIeuSjxOjkfZteC6ePuqjwZNUZVA+SMlm3+ahGSDq3sDwOhhK7');

// login to the remote server
$adapter->loginPassword('password');

// create a new console
$console = new ConsoleAccess($adapter);

// execute the command
$console->bin('pwd')->exec();

// fetch output
echo $console->getOutput();

// fetch exit status
echo $console->getExitStatus();

SSH with public key authentication

/*
 * create a new adapter
 * provide host, user and (for security reasons) the public
 * key of the host (in debian: "/etc/ssh/ssh_host_rsa_key.pub")
 */
$adapter = new SshAdapter('127.0.0.1', 'user', 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDZCcmN09Wa62slAy2ASo+/TVlYIb4GufKAV02hjrYhzxCkOdxJOqLmfjkenr+hKAtBf4bHvVFZGI3jd12rLSgMTG7h53Zumv5r4oIl+SBxB/+U2PEk8X5XEDRvR1eP5+3fdAB8w/Ds4KI7HGMG0IkSvP8Gqlsq6AE/t6rQI8ac52bWHkmBHa7Ebt3JIKbi6E0HdCq0Qy35GadVCaBJRW49oqxYL1hVrcifB4DscqarU35+zDO6UYPdiFgfgfIFTIcB9nPAwiOmHkg+4uJbonZyjGSr+phYj0BIQ4JIeuSjxOjkfZteC6ePuqjwZNUZVA+SMlm3+ahGSDq3sDwOhhK7');

/*
 * login to the remote server
 * You can provide a path or the
 * the content of the key.
 *
 * If your key is encrypted,
 * you can provide a password
 * after the key path/content
 */
$adapter->loginKey(file_get_contents('~/.ssh/id_rsa');

// create a new console
$console = new ConsoleAccess($adapter);

// execute the command
$console->bin('pwd')->exec();

// fetch output
echo $console->getOutput();

// fetch exit status
echo $console->getExitStatus();

Using sudo

// create a new adapter
$adapter = new LocalAdapter;

// create a new console
$console = new ConsoleAccess($adapter);

// execute the command
// you can pass the path to the
// sudo binary as parameter e.g.
// sudo('/non/standard/sudo/path')
$console->sudo()->bin('pwd')->exec();

// fetch output
echo $console->getOutput();

// fetch exit status
echo $console->getExitStatus();

Fetching live output

// create a new adapter
$adapter = new LocalAdapter;

// create a new console
$console = new ConsoleAccess($adapter);

// execute the command
// you can pass a closure to the
// exec function which receives every
// line of the live output
$console->bin('pwd')->exec(function($line) {
        echo $line . PHP_EOL;
});

// fetch exit status
echo $console->getExitStatus();

Writing own adapters

Extending this library is easy. Just create a class which implements the AdapterInterface. Add the necessary methods and you are good to go. Quick note: If you add a telnet adapter, i will find you :-).

Parameter

You may pass parameters using the chainable param() function.

// create a new adapter
$adapter = new LocalAdapter;

// create a new console
$console = new ConsoleAccess($adapter);

// execute command with parameter
$console->bin('pwd')->param('-L')->param('--some-other-parameter')->exec();

// fetch output
echo $console->getOutput();

// fetch exit status
echo $console->getExitStatus();

Hidden parameters

If you want to pass a password or other secrets to a command, you should set the second parameter to true. Otherwise the getCommand() function will output the data.

// create a new adapter
$adapter = new LocalAdapter;

// create a new console
$console = new ConsoleAccess($adapter);

// execute an command
// with hidden parameter
$console->bin('command')->hiddenParam('secret-parameter')->exec();

// fetch output
echo $console->getOutput();

// fetch exit status
echo $console->getExitStatus();

Escaping

Commands are escaped by default using escapeshellcmd() and parameters by using escapeshellarg(). If you want to pass a command without escaping you may pass false as second or third (depending on the function bin()/param()) parameter.

// create a new adapter
$adapter = new LocalAdapter;

// create a new console
$console = new ConsoleAccess($adapter);

// execute the command an
// unescaped command
$console->bin('pwd', false)->exec();

// execute an escaped command
// with unescaped parameter
$console->bin('pwd')->param('-l', false, false)->exec();

// fetch output
echo $console->getOutput();

// fetch exit status
echo $console->getExitStatus();

Pre/Post functions

If you want to execute some code before and after the command is run, you can so by using setPreExec() and setPostExec()

// create a new adapter
$adapter = new LocalAdapter;

// create a new console
$console = new ConsoleAccess($adapter);

$console->setPreExec(function($command) {
        // log something to somewhere
        log('Command is about to be executed: ' . $command);
});

$console->setPostExec(function($command, $exitStatus, $start, $end, $duration) {
        // log something to somewhere
        log('Command was executed: ' . $command);
        log('The status was: ' . $exitStatus);
        log('It was started at: ' . $start);
        log('It finished at: ' . $end);
        log('It took ' . $duration . ' seconds');
});

// execute the command
$console->bin('pwd')->exec();

// fetch output
echo $console->getOutput();

// fetch exit status
echo $console->getExitStatus();

Duration

// create a new adapter
$adapter = new LocalAdapter;

// create a new console
$console = new ConsoleAccess($adapter);

// execute the command
$console->bin('pwd')->exec();

// get start timestamp
echo $console->getStart();

// get end timestamp
echo $console->getEnd();

// get duration
// might return 0 for short running commands
echo $console->getDuration();

Support

If you have any problems, please open an issue on github.