README

Installation
Introduction
Console
Input
Output
Widgets
- TableWidget
Helpers
- PromptHelper
Related projects

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

weew / console

Maintainers

Details