PHP Classes

PHP Commands: Run commands for CLI programs using class packages

Recommend this page to a friend!
  Info   View files Documentation   View files View files (118)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
Not yet rated by the usersTotal: 92 This week: 1All time: 9,894 This week: 560Up
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: 6 packages by
Country: France France
Age: ???
All time rank: 354792 in France France
Week rank: 411 Up15 in France France Up
Innovation award
Innovation award
Nominee: 2x

Documentation

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 folder image Files  
File Role Description
Files folder imagebin (1 file)
Files folder imagedoc (11 files, 1 directory)
Files folder imagesrc (9 files, 4 directories)
Files folder imagetests (6 files, 3 directories)
Accessible without login Plain text file .travis.yml Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file phpunit.xml Data Auxiliary data
Accessible without login Plain text file readme.md Doc. Documentation

  Files folder image Files  /  bin  
File Role Description
  Accessible without login Plain text file command Example Example script

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

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

  Files folder image Files  /  src  
File Role Description
Files folder imageCommands (5 files)
Files folder imageEvents (3 files)
Files folder imageHelpers (2 files)
Files folder imageTools (6 directories)
  Plain text file Command.php Class Class source
  Plain text file CommandManager.php Class Class source
  Plain text file CommandTester.php Class Class source
  Plain text file ExceptionHandler.php Class Class source
  Plain text file Input.php Class Class source
  Plain text file Output.php Class Class source
  Plain text file Request.php Class Class source
  Plain text file Tool.php Class Class source
  Plain text file ToolManager.php Class Class source

  Files folder image Files  /  src  /  Commands  
File Role Description
  Plain text file CreateCommand.php Class Class source
  Plain text file ExampleCommand.php Class Class source
  Plain text file ExceptionCommand.php Class Class source
  Plain text file HelpCommand.php Class Class source
  Plain text file ListCommand.php Class Class source

  Files folder image Files  /  src  /  Events  
File Role Description
  Plain text file CommandEvent.php Class Class source
  Plain text file ExceptionEvent.php Class Class source
  Plain text file RequestEvent.php Class Class source

  Files folder image Files  /  src  /  Helpers  
File Role Description
  Plain text file CharHelper.php Class Class source
  Plain text file PhpHelper.php Class Class source

  Files folder image Files  /  src  /  Tools  
File Role Description
Files folder imageBloc (3 files)
Files folder imageChoice (3 files)
Files folder imageProgressBar (3 files)
Files folder imageQuestion (3 files)
Files folder imageSection (2 files)
Files folder imageTable (5 files)

  Files folder image Files  /  src  /  Tools  /  Bloc  
File Role Description
  Plain text file BlocManager.php Class Class source
  Plain text file BlocStyle.php Class Class source
  Plain text file BlocTool.php Class Class source

  Files folder image Files  /  src  /  Tools  /  Choice  
File Role Description
  Plain text file ChoiceManager.php Class Class source
  Plain text file ChoiceStyle.php Class Class source
  Plain text file ChoiceTool.php Class Class source

  Files folder image Files  /  src  /  Tools  /  ProgressBar  
File Role Description
  Plain text file ProgressBarManager.php Class Class source
  Plain text file ProgressBarStyle.php Class Class source
  Plain text file ProgressBarTool.php Class Class source

  Files folder image Files  /  src  /  Tools  /  Question  
File Role Description
  Plain text file QuestionManager.php Class Class source
  Plain text file QuestionStyle.php Class Class source
  Plain text file QuestionTool.php Class Class source

  Files folder image Files  /  src  /  Tools  /  Section  
File Role Description
  Plain text file SectionManager.php Class Class source
  Plain text file SectionTool.php Class Class source

  Files folder image Files  /  src  /  Tools  /  Table  
File Role Description
  Plain text file Cell.php Class Class source
  Plain text file Line.php Class Class source
  Plain text file TableManager.php Class Class source
  Plain text file TableStyle.php Class Class source
  Plain text file TableTool.php Class Class source

  Files folder image Files  /  tests  
File Role Description
Files folder imageCommands (4 files)
Files folder imageHelpers (2 files)
Files folder imageTools (6 directories)
  Plain text file CommandManagerTest.php Class Class source
  Plain text file CommandTest.php Class Class source
  Plain text file ExceptionHandlerTest.php Class Class source
  Plain text file InputTest.php Class Class source
  Plain text file RequestTest.php Class Class source
  Plain text file ToolTest.php Class Class source

  Files folder image Files  /  tests  /  Commands  
File Role Description
  Plain text file ExceptionCommandTest.php Class Class source
  Plain text file HelpCommandTest.php Class Class source
  Plain text file ListCommandTest.php Class Class source
  Plain text file TestCommand.php Class Class source

  Files folder image Files  /  tests  /  Helpers  
File Role Description
  Plain text file CharHelperTest.php Class Class source
  Plain text file PhpHelperTest.php Class Class source

  Files folder image Files  /  tests  /  Tools  
File Role Description
Files folder imageBloc (3 files)
Files folder imageChoice (3 files)
Files folder imageProgress (3 files)
Files folder imageQuestion (3 files)
Files folder imageSection (2 files)
Files folder imageTable (5 files)

  Files folder image Files  /  tests  /  Tools  /  Bloc  
File Role Description
  Plain text file BlockStyleTest.php Class Class source
  Plain text file BlockToolManagerTest.php Class Class source
  Plain text file BlockToolTest.php Class Class source

  Files folder image Files  /  tests  /  Tools  /  Choice  
File Role Description
  Plain text file ChoiceStyleTest.php Class Class source
  Plain text file ChoiceToolManagerTest.php Class Class source
  Plain text file ChoiceToolTest.php Class Class source

  Files folder image Files  /  tests  /  Tools  /  Progress  
File Role Description
  Plain text file ProgressBarManagerTest.php Class Class source
  Plain text file ProgressBarStyleTest.php Class Class source
  Plain text file ProgressBarToolTest.php Class Class source

  Files folder image Files  /  tests  /  Tools  /  Question  
File Role Description
  Plain text file QuestionStyleTest.php Class Class source
  Plain text file QuestionToolManagerTest.php Class Class source
  Plain text file QuestionToolTest.php Class Class source

  Files folder image Files  /  tests  /  Tools  /  Section  
File Role Description
  Plain text file SectionToolManagerTest.php Class Class source
  Plain text file SectionToolTest.php Class Class source

  Files folder image Files  /  tests  /  Tools  /  Table  
File Role Description
  Plain text file TableCellTest.php Class Class source
  Plain text file TableLineTest.php Class Class source
  Plain text file TableStyleTest.php Class Class source
  Plain text file TableToolTest.php Class Class source
  Plain text file TableTooManagerTest.php Class Class source

 Version Control Unique User Downloads Download Rankings  
 100%
Total:92
This week:1
All time:9,894
This week:560Up