PHP Commands: Run commands for CLI programs using class packages

Recommend this page to a friend!
  Info   Documentation   View files (118)   Download .zip   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
Not yet rated by the usersTotal: 82 This week: 1All time: 9,547 This week: 255
Version License PHP version Categories
commands 1.0.0MIT/X Consortium ...7Console, PHP 7
Description Author

This package can run commands for CLI programs using class packages.

It provides a base class for classes that will be used to creating command programs to be run from the command line interface.

The command sub-classes can register the names of the parameters that the command line program may have to take the parameter values. Then the base class can be called to get the parameter values for using in the command implementation sub-class.

The package also provides helper classes to output information several ways like text blocks, progress bars, asking questions to the user, multiple option choices, create section areas on the screen and render information as tables.

Picture of Alexandre
  Performance   Level  
Name: Alexandre <contact>
Classes: 3 packages by
Country: France France
Age: ???
All time rank: 388798 in France France
Week rank: 259 13 in France France
Innovation award
Innovation award
Nominee: 2x

Details

SitPHP/Commands

Build Status

The "sitphp/commands" library can help you to create commands super easily for your application or your library. You can also use it to build your own customized command tool.

See full documentation here

command showcase

Install

Add the "sitphp/commands": "1.0.*" line in the "require" section of your composer.json file :


{
    "require": {
        "sitphp/commands": "1.0.*"
    }
}

Then just run the following composer command to install the library :

composer update

Creating a command

To build a new command, you should create a new class extending the \SitPHP\Commands\Command class in the "Commands" folder of your library or application. This class should implement the handle method. Let's create, for example, a "YourCommand" class :

namespace App\Commands;

class YourCommand extends \SitPHP\Commands\Command {

    function handle(){
        $this->write('hello');
    }

}

Running a command

To run your command, you should use the command application located in the /vendor/bin folder. To run our previously created "YourCommand" command for example, use the shorthand notation (Namespace:CommandName) :

vendor/bin/command App:YourCommand

or use the full path (Class name with slashes "/" instead of backslashes "\")

vendor/bin/command App/Commands/YourCommand

Writing text messages

To write a message in your terminal, use the write or the writeLn method. The writeLn method will write the message on a new line whereas the write method will write the message on the same line.

You can also use the lineBreak method to display line breaks. This method can receive an integer argument to specify how many line breaks you wish to write.


namespace App\Commands;

class YourCommand extends \SitPHP\Commands\Command {

    function handle(){
        $this->write('Hello,');
        
        // Single line break
        $this->lineBreak();

        $this->write('I am ');
        $this->write('Alex');
        
        // Double line break
        $this->lineBreak(2);

        $this->write('I code with PHP');
    }

}

command write

Arguments and options

In order to retrieve options and arguments passed to your command, you must first register them in the prepare method of your command class. - To register an argument, use the setArgumentInfos method with name of the argument and its position (0 if it is the first argument, 1 if it is the second argument and so on ...) - To register an option, use the setOptionInfos method with the name of the option. Here, for example, we will register "name" argument and a "color" option.


// In your command class ...

function prepare()
{
   // Register "name" argument at position "0"
   $this->setArgumentInfos('name', 0);

   // Register "color" option
   $this->setOptionInfos('color');
}

function handle()
{
   // Retrieve name argument value
   $name = $this->getArgument('name');
   if ($name === null) {
       throw new \Exception('The "name" argument is required');
   }
   $message = 'My name is ' . $name;
   
   // Retrieve color option value
   $color = $this->getOption('color');
   if ($color !== null) {
       $message .= ' and I like the ' . $color . ' color';
   }

   $this->writeLn($message);
}

To send the arguments to your command, just type their value in your terminal. Options should preceded with two hyphens (ex : --color). Options can take values like so --color=red. If no value is specified, the option value will be true.

You could run our previous command typing something like this in the terminal :

vendor/bin/command App:YourCommand Alex --color=red

This would write : "My name is Alex and I like the red color".

Styling

Anything written in the terminal can be easily styled using the <cs> tag.

  • You can change the color of your text with the `color` attribute. Available colors are : 'black','white','red','green','yellow','blue','purple','cyan','light_grey','dark_grey','light_red','light_green','light_yellow','light_blue','pink','light_cyan'.
  • You can change the background color of your text with the `background-color` attribute. Available colors are : 'black','white','red','green','yellow','blue','purple','cyan','light_grey',dark_grey','light_red','light_green','light_yellow','light_blue','pink','light_cyan'.
  • You can make your text bold with the `bold` parameter of the `style` attribute
  • You can highlight your text with `highlight` parameter of the `style` attribute
  • You can underline your text with `underline` parameter of the `style` attribute
  • You make your text blink with `blink` parameter of the `style` attribute (some terminals do not support blink)

Here are a few styling examples :


// In the "handle" method of your command class ...
$this->writeLn('This will display in <cs color="blue">blue</cs>');
$this->writeLn('This will display <cs style="bold;highlight">highlighted and bold</cs>');
$this->writeLn('This will display <cs color="white" background-color="blue">with a white text in a blue background</cs>');

command style

Tools

This package comes with some useful tools. It's also easy to build your own if you are using your own command application.

Bloc tool

The bloc tool can display content in a box. A bloc is created with the bloc method and displayed with the display method. The width of the bloc will automatically adjust to the width of the content.

// In the "handle" method of your command class ...
$this->bloc('I am a simple bloc ...')
    ->display();

Progress bar tool

To create a progress bar, use the progress method with an argument to specify the number of steps of your progress bar. Then display it with the display method. You can then move the progress line forward with the progress method. You might want to "stick" your progress bar with the placeHere method so that it does'nt show on a new line on each progress.


// In the "handle" method of your command class ...

// Create a 5 steps progress bar
$progress_bar = $this->progressBar(5)
    ->placeHere()
    ->display();

for($i = 1; $i <= 5; $i++){
    sleep(1);
    $progress_bar->progress();
}

command progress bar

The question tool

The question tool allows to ask for user input. Use the question method to create a new question. This method can take two arguments : the question prompt and an array of autocomplete values.

// In the "handle" method of your command class ...
function handle(){
    $genres = ['pop', 'rock', 'hip hop', 'classical'];
    $genre = $this->question('Which music genre do you like ?', $genres)
        ->ask();
    
    $this->lineBreak();
    $this->writeLn('Your favorite music genre is : '.$genre);
}

command question

The choice tool

The choice tool allows you to ask the user to choose within a predefined set of choices. Use the choice method to create a new choice and ask for the user choice using the ask method. You might also want to let user quit without answering with the enableQuit method. The choice question will be re-displayed until the user has given a correct choice or has quit if possible. When the user chooses to quit, the choice method will return null.

The choice method can take up to three arguments : an array of choices, the question prompt, and the title.


// In the "handle" method of your command class ...
function handle(){
    $choices = ['red', 'blue', 'green'];
    $color_index = $this->choice($choices, 'Which color do you like best ?', 'Colors')
        ->enableQuit()
        ->ask();
        
    if($color_index !== null){   
        $this->lineBreak(); 
        $this->writeLn('You like the '.$choices[$color_index].' color the best');
    }
}

command choice

Section tool

The section is used to update or move content at a predefined position on the screen. You can create a section with the section method and place it where you decide with the placeHere method. Every content in the section will written at the placed position. Here is an example to illustrate this :

// In the "handle" method of your command class ...
$this->writeLn('This goes before');
$section = $this->section()->placeHere();
$this->writeLn('This goes after');

$section->writeLn('This goes in the <cs color="blue">middle</cs>');
sleep(1);
$section->overwriteLn('This goes in the <cs color="red">middle</cs>');

command section

Table tool

You can use the table tool to display content organized in rows and columns. Use the table method to create a table. Then define every table row in an array. You can also insert a table with a line item.

// In the "handle" method of your command class ...
$this->table([
    ['<cs style="bold">Animal</cs>', '<cs style="bold">Classification</cs>'],
    'line',
    ['elephant', 'mammal'],
    ['parrot', 'bird']
])->display();

table command

  Files  
File Role Description
bin (1 file)
doc (11 files, 1 directory)
src (9 files, 4 directories)
tests (6 files, 3 directories)
.travis.yml Data Auxiliary data
composer.json Data Auxiliary data
phpunit.xml Data Auxiliary data
readme.md Doc. Documentation

  Files  /  bin  
File Role Description
   command Example Example script

  Files  /  doc  
File Role Description
img (33 files)
   0_intro.md Data Auxiliary data
   10_about.md Data Auxiliary data
   1_quick_start.md Data Auxiliary data
   2_creating_a_command.md Data Auxiliary data
   3_tools.bloc_tool.md Data Auxiliary data
   4_tools.progress_bar_tool.md Data Auxiliary data
   5_tools.question_tool.md Data Auxiliary data
   6_tools.choice_tool.md Data Auxiliary data
   7_tools.section_tool.md Data Auxiliary data
   8_tools.table_tool.md Data Auxiliary data
   9_creating_application.md Class Class source

  Files  /  doc  /  img  
File Role Description
   bloc_basic.png Data Auxiliary data
   bloc_sticky.gif Data Auxiliary data
   bloc_style.png Data Auxiliary data
   choice_basic.gif Data Auxiliary data
   choice_multiselect.gif Data Auxiliary data
   choice_sticky.gif Data Auxiliary data
   choice_style.png Data Auxiliary data
   command_params.png Data Auxiliary data
   command_showcase.gif Data Auxiliary data
   command_style.png Data Auxiliary data
   command_style_tags.png Data Auxiliary data
   command_write.png Data Auxiliary data
   progress_basic.gif Data Auxiliary data
   progress_format.png Data Auxiliary data
   progress_more.gif Data Auxiliary data
   progress_style.png Data Auxiliary data
   question_basic.gif Data Auxiliary data
   question_sticky.gif Data Auxiliary data
   question_style.gif Data Auxiliary data
   section_basic.gif Data Auxiliary data
   section_move.gif Data Auxiliary data
   table_basic.png Data Auxiliary data
   table_box.png Data Auxiliary data
   table_colspan.png Data Auxiliary data
   table_compact.png Data Auxiliary data
   table_header_footer.png Data Auxiliary data
   table_line.png Data Auxiliary data
   table_minimal.png Data Auxiliary data
   table_rowspan.png Data Auxiliary data
   table_size.png Data Auxiliary data
   table_sticky.gif Data Auxiliary data
   table_style.png Data Auxiliary data
   table_transparent.png Data Auxiliary data

  Files  /  src  
File Role Description
Commands (5 files)
Events (3 files)
Helpers (2 files)
Tools (6 directories)
   Command.php Class Class source
   CommandManager.php Class Class source
   CommandTester.php Class Class source
   ExceptionHandler.php Class Class source
   Input.php Class Class source
   Output.php Class Class source
   Request.php Class Class source
   Tool.php Class Class source
   ToolManager.php Class Class source

  Files  /  src  /  Commands  
File Role Description
   CreateCommand.php Class Class source
   ExampleCommand.php Class Class source
   ExceptionCommand.php Class Class source
   HelpCommand.php Class Class source
   ListCommand.php Class Class source

  Files  /  src  /  Events  
File Role Description
   CommandEvent.php Class Class source
   ExceptionEvent.php Class Class source
   RequestEvent.php Class Class source

  Files  /  src  /  Helpers  
File Role Description
   CharHelper.php Class Class source
   PhpHelper.php Class Class source

  Files  /  src  /  Tools  
File Role Description
Bloc (3 files)
Choice (3 files)
ProgressBar (3 files)
Question (3 files)
Section (2 files)
Table (5 files)

  Files  /  src  /  Tools  /  Bloc  
File Role Description
   BlocManager.php Class Class source
   BlocStyle.php Class Class source
   BlocTool.php Class Class source

  Files  /  src  /  Tools  /  Choice  
File Role Description
   ChoiceManager.php Class Class source
   ChoiceStyle.php Class Class source
   ChoiceTool.php Class Class source

  Files  /  src  /  Tools  /  ProgressBar  
File Role Description
   ProgressBarManager.php Class Class source
   ProgressBarStyle.php Class Class source
   ProgressBarTool.php Class Class source

  Files  /  src  /  Tools  /  Question  
File Role Description
   QuestionManager.php Class Class source
   QuestionStyle.php Class Class source
   QuestionTool.php Class Class source

  Files  /  src  /  Tools  /  Section  
File Role Description
   SectionManager.php Class Class source
   SectionTool.php Class Class source

  Files  /  src  /  Tools  /  Table  
File Role Description
   Cell.php Class Class source
   Line.php Class Class source
   TableManager.php Class Class source
   TableStyle.php Class Class source
   TableTool.php Class Class source

  Files  /  tests  
File Role Description
Commands (4 files)
Helpers (2 files)
Tools (6 directories)
   CommandManagerTest.php Class Class source
   CommandTest.php Class Class source
   ExceptionHandlerTest.php Class Class source
   InputTest.php Class Class source
   RequestTest.php Class Class source
   ToolTest.php Class Class source

  Files  /  tests  /  Commands  
File Role Description
   ExceptionCommandTest.php Class Class source
   HelpCommandTest.php Class Class source
   ListCommandTest.php Class Class source
   TestCommand.php Class Class source

  Files  /  tests  /  Helpers  
File Role Description
   CharHelperTest.php Class Class source
   PhpHelperTest.php Class Class source

  Files  /  tests  /  Tools  
File Role Description
Bloc (3 files)
Choice (3 files)
Progress (3 files)
Question (3 files)
Section (2 files)
Table (5 files)

  Files  /  tests  /  Tools  /  Bloc  
File Role Description
   BlockStyleTest.php Class Class source
   BlockToolManagerTest.php Class Class source
   BlockToolTest.php Class Class source

  Files  /  tests  /  Tools  /  Choice  
File Role Description
   ChoiceStyleTest.php Class Class source
   ChoiceToolManagerTest.php Class Class source
   ChoiceToolTest.php Class Class source

  Files  /  tests  /  Tools  /  Progress  
File Role Description
   ProgressBarManagerTest.php Class Class source
   ProgressBarStyleTest.php Class Class source
   ProgressBarToolTest.php Class Class source

  Files  /  tests  /  Tools  /  Question  
File Role Description
   QuestionStyleTest.php Class Class source
   QuestionToolManagerTest.php Class Class source
   QuestionToolTest.php Class Class source

  Files  /  tests  /  Tools  /  Section  
File Role Description
   SectionToolManagerTest.php Class Class source
   SectionToolTest.php Class Class source

  Files  /  tests  /  Tools  /  Table  
File Role Description
   TableCellTest.php Class Class source
   TableLineTest.php Class Class source
   TableStyleTest.php Class Class source
   TableToolTest.php Class Class source
   TableTooManagerTest.php Class Class source

 Version Control Unique User Downloads Download Rankings  
 100%
Total:82
This week:1
All time:9,547
This week:255

For more information send a message to info at phpclasses dot org.