pointybeard / helpers-functions-cli
A collection of functions relating to the command-line
Installs: 2 465
Dependents: 7
Suggesters: 0
Security: 0
Stars: 2
Watchers: 2
Forks: 1
Open Issues: 2
Requires
- php: >=7.2
- pointybeard/helpers-cli-colour: ~1.0
- pointybeard/helpers-cli-input: ~1.2.0
- pointybeard/helpers-exceptions-readabletrace: ~1.0.0
- pointybeard/helpers-functions-arrays: ~1.0
- pointybeard/helpers-functions-debug: ~1.0
- pointybeard/helpers-functions-flags: ~1.0
- pointybeard/helpers-functions-strings: ~1.1
Requires (Dev)
README
- Version: v1.1.10
- Date: July 29 2021
- Release notes
- GitHub repository
A collection of functions relating to the command-line
Installation
This library is installed via Composer. To install, use composer require pointybeard/helpers-functions-cli
or add "pointybeard/helpers-functions-cli": "~1.1"
to your composer.json
file.
And run composer to update your dependencies:
$ curl -s http://getcomposer.org/installer | php
$ php composer.phar update
Requirements
This library makes use of the PHP Helpers: Command-line Input and Input Type Handlers, PHP Helpers: Flag Functions (pointybeard/helpers-functions-flags
), PHP Helpers: Command-line Colour (pointybeard/helpers-cli-colours
) and PHP Helpers: String Functions packages. They are installed automatically via composer.
To include all the PHP Helpers packages on your project, use composer require pointybeard/helpers
or add "pointybeard/helpers": "~1"
to your composer file.
Usage
This library is a collection convenience function for command-line tasks. They are included by the vendor autoloader automatically. The functions have a namespace of pointybeard\Helpers\Functions\Cli
The following functions are provided:
run_command()
which()
can_invoke_bash()
is_su()
run_command()
usage()
manpage()
get_window_size()
display_error_and_exit()
Example usage:
<?php declare(strict_types=1); include __DIR__.'/vendor/autoload.php'; use pointybeard\Helpers\Cli\Input; use pointybeard\Helpers\Cli\Colour\Colour; use pointybeard\Helpers\Functions\Cli; var_dump(Cli\which("ls")); // string(11) "/usr/bin/ls" var_dump(Cli\can_invoke_bash()); // bool(true) var_dump(Cli\is_su()); // bool(false) var_dump(Cli\get_window_size()); // array(2) { // 'cols' => string(3) "103" // 'lines' => string(2) "68" // } Cli\run_command("date", $out); var_dump($out); // string(29) "Mon 6 Apr 17:20:29 AEST 2020" try{ Cli\run_command("not -a --command", $out, $err); } catch(Cli\Exceptions\RunCommandFailedException $ex) { var_dump($ex->getMessage(), $ex->getCommand(), $ex->getError()); } // string(54) "Failed to run command. Returned: sh: 1: not: not found" // string(16) "not -a --command" // string(21) "sh: 1: not: not found" echo Cli\manpage( 'test', '1.0.2', 'A simple test command with a really long description. This is an intentionally very long argument description so we can check that word wrapping is working correctly. It should wrap to the window', (new Input\InputCollection()) ->add( Input\InputTypeFactory::build('Argument') ->name('action') ->flags(Input\AbstractInputType::FLAG_REQUIRED) ->description('The name of the action to perform. This is an intentionally very long argument description so we can check that word wrapping is working correctly') ) ->add( Input\InputTypeFactory::build('IncrementingFlag') ->name('v') ->flags(Input\AbstractInputType::FLAG_OPTIONAL | Input\AbstractInputType::FLAG_TYPE_INCREMENTING) ->description('verbosity level. -v (errors only), -vv (warnings and errors), -vvv (everything).') ->validator(new Input\Validator( function (Input\AbstractInputType $input, Input\AbstractInputHandler $context) { // Make sure verbosity level never goes above 3 return min(3, (int) $context->find('v')); } )) ) ->add( Input\InputTypeFactory::build('Option') ->name('P') ->flags(Input\AbstractInputType::FLAG_OPTIONAL | Input\AbstractInputType::FLAG_VALUE_OPTIONAL) ->description('Port to use for all connections.') ->default('3306') ) ->add( Input\InputTypeFactory::build('LongOption') ->name('data') ->short('d') ->flags(Input\AbstractInputType::FLAG_OPTIONAL | Input\AbstractInputType::FLAG_VALUE_REQUIRED) ->description('Path to the input JSON data.') ), Colour::FG_GREEN, Colour::FG_WHITE, [ 'Examples' => 'php -f test.php -- import -vvv -d test.json', ] ).PHP_EOL; // test 1.0.2, A simple test command with a really long description. This is an intentionally very long argument description so we can check that word wrapping is working correctly. It should wrap to the window // Usage: test [OPTIONS]... ACTION... // // Arguments: // ACTION The name of the action to perform. This is an intentionally very // long argument description so we can check that word wrapping is // working correctly // // Options: // -v verbosity level. -v (errors only), -vv (warnings and errors), // -vvv (everything). // -P Port to use for all connections. // -d, --data=VALUE Path to the input JSON data. // // Examples: // php -f test.php -- import -vvv -d test.json Cli\display_error_and_exit('Looks like something went wrong!', 'Fatal Error'); // Fatal Error // Looks like something went wrong!
Support
If you believe you have found a bug, please report it using the GitHub issue tracker, or better yet, fork the library and submit a pull request.
Contributing
We encourage you to contribute to this project. Please check out the Contributing documentation for guidelines about how to get involved.
License
"PHP Helpers: Command-line Functions" is released under the MIT License.