weew / console
Console application skeleton.
Requires
- weew/console-arguments: ^1.13
- weew/console-formatter: ^2.1
- weew/helpers-array: ^1.2
- weew/helpers-filesystem: ^1.2
- weew/helpers-string: ^1.7
- weew/json-encoder: ^1.0
Requires (Dev)
- henrikbjorn/phpspec-code-coverage: ^2.0
- phpspec/phpspec: ^2.4
- satooshi/php-coveralls: ^0.6.1
- weew/helpers-phpspec: ^1.0
README
Table of contents
Installation
composer require weew/console
Introduction
This package provides a convenient skeleton for console application. Optically, heavily inspired by the symfony console it has it similarities and differences. Describing commands, parsing console arguments, styling and colorization of output, question helpers etc., all this is included inside this package. In related projects you'll find a list of used components that you might also use separately from this package.
Note: this package has not been tested on windows. Windows contributions are highly appreciated.
Console
To start building your console app, you need to instantiated a new console first.
$console = new Console();
Commands
Commands are the pieces of logic that you might plug and play into your console application. A command can by anything. There is no interface contract that you must fulfill. This design choice was made because of the dependency injection support for the weew/console-container-aware package.
Your command must have the setup
and run
method. For further information about configuration of commands refer to the weew/console-arguments package.
class SampleCommand { public function setup(ICommand $command) { // describe command $command->setName('colors') ->setDescription('Shows a list of colors'); $command->argument(ArgumentType::SINGLE, 'favorite_color'); $command->argument(ArgumentType::SINGLE_OPTIONAL, '--only-light'); $command->argument(ArgumentType::SINGLE_OPTIONAL, '--only-dark'); } public function run(IInput $input, IOutput $output, IConsole $console) { // do your thang if ( ! $input->hasOption('--only-dark')) { $output->writeLine('<red>red</red>'); } if ( ! $input->hasOption('--only-light')) { $output->writeLine('<blue>blue</blue>'); } if ($input->hasArgument('favorite_color')) { $favoriteColor = $input->getArgument('favorite_color'); $output->writeLine("The best of all colors is <keyword>$favoriteColor</keyword>"); } } }
All the important functionality is available trough instances of IInput
and IOutput
. There are many more things you can do, just take a look at it. All you have to do now is to register your command on the console.
$console->addCommand(SampleCommand::class); // or $console->addCommand(new SampleCommand());
Running your command is as easy as pie.
$console->parseString('colors red --only-dark'); // or $console->parseArgs(['colors', 'red', '--only-dark']; // or $console->parseArgv(['./file_name', 'colors', 'red', '--only-dark']);
You can prevent a command from executing in parallel setting the appropriate flag.
$command->setParallel(false);
Input
Input contains all the information about the received arguments and offers some apis for interaction with the user.
This is how you can retrieve the current command:
$input->getCommand();
You can access arguments and options that were matched for the command:
$input->getArgument('argument'); $input->getOption('--option');
You can prompt user for input using this methods:
$input->readline(); $input->readChar();
Output
Output is used to print information to the terminal. It uses the weew/console-formatter for styling and formatting of the text.
$output->writeLine('<keyword>key: </keyword> value'); $output->write('some text);
Widgets
Widgets are small and reusable classes that serve as a kind of ui elements.
TableWidget
This widget allows you to easily print simple tables.
$table = new TableWidget($input, $output); $table ->setTitle('Table title') ->addRow('task1', 'x') ->addSection('Done tasks') ->addRow('task2', '✓'); $table->render();
Helpers
There are several helpers that you might use for interaction with the user.
PromptHelper
This helper allows you to prompt user for different kinds of input.
$prompt = new PromptHelper($input, $output); $response = $prompt->ask('Are you ready?'); $response = $prompt->prompt('What is your name');
Related projects
- Console formatter Used for styling of output
- Console arguments Used for parsing of arguments
- Container aware console Container aware version of this package