{"id":21577454,"url":"https://github.com/sitphp/commands","last_synced_at":"2026-05-07T10:37:24.467Z","repository":{"id":57052090,"uuid":"190146606","full_name":"sitphp/commands","owner":"sitphp","description":"A simple yet powerful library to run console commands from the CLI or build a command application.","archived":false,"fork":false,"pushed_at":"2019-07-10T07:55:00.000Z","size":4686,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-18T07:26:41.914Z","etag":null,"topics":["cli","command","command-line","console","php","shell","terminal"],"latest_commit_sha":null,"homepage":"https://sitphp.com/commands/doc/intro/latest","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sitphp.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-04T06:55:54.000Z","updated_at":"2019-07-10T07:55:02.000Z","dependencies_parsed_at":"2022-08-24T03:41:05.835Z","dependency_job_id":null,"html_url":"https://github.com/sitphp/commands","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/sitphp/commands","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitphp%2Fcommands","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitphp%2Fcommands/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitphp%2Fcommands/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitphp%2Fcommands/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sitphp","download_url":"https://codeload.github.com/sitphp/commands/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitphp%2Fcommands/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268385863,"owners_count":24242105,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command","command-line","console","php","shell","terminal"],"created_at":"2024-11-24T13:07:07.684Z","updated_at":"2026-05-07T10:37:24.426Z","avatar_url":"https://github.com/sitphp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SitPHP/Commands\n\n![Build Status](https://travis-ci.org/sitphp/commands.svg?branch=master)\n\n\nThe \"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.\n\nSee full documentation [here](https://sitphp.com/commands/doc/intro/latest)\n\n![command showcase](doc/img/command_showcase.gif)\n\n## Install\n\nAdd the `\"sitphp/commands\": \"1.0.*\"` line in the `\"require\"` section of your composer.json file :\n    \n```json\n{\n    \"require\": {\n        \"sitphp/commands\": \"1.0.*\"\n    }\n}\n```\n\nThen just run the following composer command to install the library :\n\n```bash\ncomposer update\n```\n\n## Creating a command\n\nTo 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 :\n\n```php\nnamespace App\\Commands;\n\nclass YourCommand extends \\SitPHP\\Commands\\Command {\n\n    function handle(){\n        $this-\u003ewrite('hello');\n    }\n\n}\n```\n\n## Running a command \n\nTo 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) : \n\n```bash\nvendor/bin/command App:YourCommand\n```\n\nor use the full path (Class name with slashes \"/\" instead of backslashes \"\\\")\n\n```bash\nvendor/bin/command App/Commands/YourCommand\n```\n    \n## Writing text messages\n\nTo 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.\n \nYou 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.\n    \n```php\nnamespace App\\Commands;\n\nclass YourCommand extends \\SitPHP\\Commands\\Command {\n\n    function handle(){\n        $this-\u003ewrite('Hello,');\n        \n        // Single line break\n        $this-\u003elineBreak();\n\n        $this-\u003ewrite('I am ');\n        $this-\u003ewrite('Alex');\n        \n        // Double line break\n        $this-\u003elineBreak(2);\n\n        $this-\u003ewrite('I code with PHP');\n    }\n\n}\n```\n    \n![command write](doc/img/command_write.png)\n\n\n## Arguments and options\n\nIn order to retrieve options and arguments passed to your command, you must first register them in the `prepare` method of your command class. \n- 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 ...)\n- To register an option, use the `setOptionInfos`  method with the name of the option.\nHere, for example, we will register \"name\" argument and a \"color\" option.\n\n  \n    \n```php\n// In your command class ...\n\nfunction prepare()\n{\n   // Register \"name\" argument at position \"0\"\n   $this-\u003esetArgumentInfos('name', 0);\n\n   // Register \"color\" option\n   $this-\u003esetOptionInfos('color');\n}\n\nfunction handle()\n{\n   // Retrieve name argument value\n   $name = $this-\u003egetArgument('name');\n   if ($name === null) {\n       throw new \\Exception('The \"name\" argument is required');\n   }\n   $message = 'My name is ' . $name;\n   \n   // Retrieve color option value\n   $color = $this-\u003egetOption('color');\n   if ($color !== null) {\n       $message .= ' and I like the ' . $color . ' color';\n   }\n\n   $this-\u003ewriteLn($message);\n}\n```\n\nTo 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`.\n\nYou could run our previous command typing something like this in the terminal :\n\n```bash\nvendor/bin/command App:YourCommand Alex --color=red\n```\n    \nThis would write : \"My name is Alex and I like the red color\".\n\n## Styling\n\nAnything written in the terminal can be easily styled using the `\u003ccs\u003e` tag.\n\n- 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'.\n- 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'.\n- You can make your text bold with the `bold` parameter of the `style` attribute\n- You can highlight your text with `highlight` parameter of the `style` attribute\n- You can underline your text with `underline` parameter of the `style` attribute\n- You make your text blink with `blink` parameter of the `style` attribute (some terminals do not support blink)\n\nHere are a few styling examples :\n    \n```php\n// In the \"handle\" method of your command class ...\n$this-\u003ewriteLn('This will display in \u003ccs color=\"blue\"\u003eblue\u003c/cs\u003e');\n$this-\u003ewriteLn('This will display \u003ccs style=\"bold;highlight\"\u003ehighlighted and bold\u003c/cs\u003e');\n$this-\u003ewriteLn('This will display \u003ccs color=\"white\" background-color=\"blue\"\u003ewith a white text in a blue background\u003c/cs\u003e');\n```\n![command style](doc/img/command_style.png)\n\n\n## Tools\n\nThis package comes with some useful tools. It's also easy to build your own if you are using your own command application.\n\n### Bloc tool\n\nThe 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.\n\n```php\n// In the \"handle\" method of your command class ...\n$this-\u003ebloc('I am a simple bloc ...')\n    -\u003edisplay();\n```   \n\n### Progress bar tool\n\nTo 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. \nYou might want to \"stick\" your progress bar with the `placeHere` method so that it does'nt show on a new line on each progress.\n    \n```php\n// In the \"handle\" method of your command class ...\n\n// Create a 5 steps progress bar\n$progress_bar = $this-\u003eprogressBar(5)\n    -\u003eplaceHere()\n    -\u003edisplay();\n\nfor($i = 1; $i \u003c= 5; $i++){\n    sleep(1);\n    $progress_bar-\u003eprogress();\n}\n```\n\n![command progress bar](doc/img/progress_basic.gif)\n\n### The question tool\n\nThe 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.\n\n```php\n// In the \"handle\" method of your command class ...\nfunction handle(){\n    $genres = ['pop', 'rock', 'hip hop', 'classical'];\n    $genre = $this-\u003equestion('Which music genre do you like ?', $genres)\n        -\u003eask();\n    \n    $this-\u003elineBreak();\n    $this-\u003ewriteLn('Your favorite music genre is : '.$genre);\n}\n```\n    \n![command question](doc/img/question_basic.gif)\n\n\n### The choice tool\n\nThe 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.\nWhen the user chooses to quit, the choice method will return `null`.\n\nThe `choice` method can take up to three arguments : an array of choices, the question prompt, and the title. \n    \n```php\n// In the \"handle\" method of your command class ...\nfunction handle(){\n    $choices = ['red', 'blue', 'green'];\n    $color_index = $this-\u003echoice($choices, 'Which color do you like best ?', 'Colors')\n        -\u003eenableQuit()\n        -\u003eask();\n        \n    if($color_index !== null){   \n        $this-\u003elineBreak(); \n        $this-\u003ewriteLn('You like the '.$choices[$color_index].' color the best');\n    }\n}\n```\n\n![command choice](doc/img/choice_basic.gif)\n\n### Section tool\n\nThe 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 :\n\n```php\n// In the \"handle\" method of your command class ...\n$this-\u003ewriteLn('This goes before');\n$section = $this-\u003esection()-\u003eplaceHere();\n$this-\u003ewriteLn('This goes after');\n\n$section-\u003ewriteLn('This goes in the \u003ccs color=\"blue\"\u003emiddle\u003c/cs\u003e');\nsleep(1);\n$section-\u003eoverwriteLn('This goes in the \u003ccs color=\"red\"\u003emiddle\u003c/cs\u003e');\n```\n\n![command section](doc/img/section_basic.gif)\n\n### Table tool\n\nYou 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.\n\n```php\n// In the \"handle\" method of your command class ...\n$this-\u003etable([\n    ['\u003ccs style=\"bold\"\u003eAnimal\u003c/cs\u003e', '\u003ccs style=\"bold\"\u003eClassification\u003c/cs\u003e'],\n    'line',\n    ['elephant', 'mammal'],\n    ['parrot', 'bird']\n])-\u003edisplay();\n```\n\n![table command](doc/img/table_basic.png)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsitphp%2Fcommands","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsitphp%2Fcommands","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsitphp%2Fcommands/lists"}