{"id":17333794,"url":"https://github.com/lotfio/conso","last_synced_at":"2025-04-14T16:33:34.562Z","repository":{"id":54871516,"uuid":"165832668","full_name":"lotfio/conso","owner":"lotfio","description":":anger: PHP console applications for cool kids :anger:","archived":false,"fork":false,"pushed_at":"2021-01-23T15:04:07.000Z","size":899,"stargazers_count":45,"open_issues_count":1,"forks_count":3,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-08-17T22:32:29.698Z","etag":null,"topics":["aven","cli","composer","conso","console","console-app","console-application","console-component","php","php-console","symphony-console"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lotfio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-01-15T10:36:41.000Z","updated_at":"2023-02-15T18:51:05.000Z","dependencies_parsed_at":"2022-08-14T05:20:22.438Z","dependency_job_id":null,"html_url":"https://github.com/lotfio/conso","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lotfio%2Fconso","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lotfio%2Fconso/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lotfio%2Fconso/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lotfio%2Fconso/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lotfio","download_url":"https://codeload.github.com/lotfio/conso/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219843518,"owners_count":16556504,"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","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":["aven","cli","composer","conso","console","console-app","console-application","console-component","php","php-console","symphony-console"],"created_at":"2024-10-15T15:03:03.174Z","updated_at":"2024-10-15T15:03:20.632Z","avatar_url":"https://github.com/lotfio.png","language":"PHP","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/18489496/51750637-f351c280-20b2-11e9-97e3-f1e0232bb04a.png\"  alt=\"Conso Preview\"\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-f1c40f\"          alt=\"License\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/PHP-7.2-3498db.svg\"          alt=\"PHP version\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/version-2.0.0-2c3e50.svg\"    alt=\"Version\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/coverage-40%25-27ae60.svg\"   alt=\"Coverage\"\u003e\n    \u003cimg src=\"https://travis-ci.org/lotfio/conso.svg?branch=master\"     alt=\"Build Status\"\u003e\n    \u003cimg src=\"https://github.styleci.io/repos/165832668/shield?branch=master\" alt=\"StyleCi\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/downloads-1k-e74c3c.svg\"     alt=\"Downloads\"\u003e\n    \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cstrong\u003eConso (PHP console applications for cool kids).\u003c/strong\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n## 🔥 Introduction :\nConso is a simple, lightweight PHP package that helps you create (executable, `.phar`, shareable) command line applications easily.\n\n![conso](https://user-images.githubusercontent.com/18489496/91354364-8a798180-e7e4-11ea-8f47-2b67580aee02.gif)\n\n## :collision: Is it really lightweight ?\n\u003cimg width=\"825\" alt=\"Screen Shot 2020-07-27 at 6 12 41 PM\" src=\"https://user-images.githubusercontent.com/18489496/88639724-616ab180-d0bd-11ea-873a-2e25ea1fa113.png\"\u003e\n\n## 📌 Requirements :\n- PHP     \u003e= 7.2 or newer versions\n- PHPUnit \u003e= 8 (for testing purpose)\n\n## 🚀 Installation :\n* ***Via composer :***\n\n```php\ncomposer require lotfio/conso\n```\n\n* ***for testing***\n```php\ncomposer test\n```\n\n## 🎉 Write your first command\n- create a `commands.php` file.\n- create a `conso` file (you can change the name as you like).\n- include your `commands.php` file into `conso` executable file.\n- it should look something like this.\n\n```php\n#!/usr/bin/env php\n\u003c?php declare(strict_types=1);\n\nuse Conso\\{\n    Conso,Input,Output\n};\n\nrequire 'vendor/autoload.php';\n\n$conso = new Conso(new Input, new Output);\n\n// include your commands\nrequire_once 'commands.php';\n\n$conso-\u003erun();\n```\n\n### :star: Available config methods :\n\n```php\n\u003c?php\n\n$conso-\u003esetSignature(); // set application signature (top logo)\n$conso-\u003esetName();     // set application name\n$conso-\u003esetVersion(); // set application version\n$conso-\u003esetAuthor(); // set application author\n$conso-\u003edisableBuiltInCommands(); // disable builtin commands\n\n```\n\n- now define a new `test` command in your `commands.php` :\n\n```php\n\u003c?php\n// this is your commands file\n\n// test command\n$conso-\u003ecommand(\"test\", function($input, $output){\n    $output-\u003ewriteLn(\"\\n hello from test \\n\", 'red');\n});\n\n```\n\n- now your command has been registered.\n- run `php conso --commands` or `./conso --commands` in your terminal and you should see your command.\n\n![test-command](https://user-images.githubusercontent.com/18489496/87862304-c18b8600-c94e-11ea-9237-56895f15245a.png)\n\n- command test is registered now ***(no description is shown you can add this later on)***.\n- run your command `php conso test` or `./conso test`.\n\n![run-test](https://user-images.githubusercontent.com/18489496/87862317-ec75da00-c94e-11ea-9690-894c35911d81.png)\n\n\n### :star: Add description\n- `-\u003edescription(string $description)`;\n\n```php\n\u003c?php\n// test command\n$conso-\u003ecommand(\"test\", function($input, $output){\n    $output-\u003ewriteLn(\"\\n hello from test \\n\", 'red');\n\n})-\u003edescription(\"This is test command description :) ^^\");\n```\n![description](https://user-images.githubusercontent.com/18489496/87862367-89387780-c94f-11ea-8166-6fc9bc598fdd.png)\n\n\n### :star: Define sub commands\n- `-\u003esub(string|array $subCommand)`;\n\n```php\n\u003c?php\n// test command\n$conso-\u003ecommand(\"test\", function($input, $output){\n\n    if($input-\u003esubCommand() == 'one')\n        exit($output-\u003ewriteLn(\"\\n hello from one \\n\", 'yellow'));\n\n    if($input-\u003esubCommand() == 'two')\n        $output-\u003ewriteLn(\"\\n hello from two \\n\", 'green');\n\n})-\u003edescription(\"This is test command description :) ^^\")-\u003esub('one', 'two');\n```\n![image](https://user-images.githubusercontent.com/18489496/87862387-abca9080-c94f-11ea-90da-cf65a0a5fbba.png)\n\n![image](https://user-images.githubusercontent.com/18489496/87862391-bedd6080-c94f-11ea-808e-bba3738b0a4b.png)\n\n\n### :star: Define command flags\n- you can define flags using the flag method `-\u003eflags(string|array $flag)`\n- this is a list of reserved flags `['-h', '--help', '-v', '--version', '-c', '--commands', '-q', '--quiet', '--ansi', '--no-ansi']`\n- for debug you can use `-vv or --verbose` flags to get more details about the error\n- you can also pass values to flags `--flag=value` or `-f=value`\n\n```php\n\u003c?php\n// test command\n$conso-\u003ecommand(\"test\", function($input, $output){\n\n    if($input-\u003eflag('-t') !== false)\n        $output-\u003ewriteLn(\"\\n flag -t is defined for this command.\\n\", 'red');\n\n    // you can get flag values\n    // $output-\u003ewriteLn($input-\u003eflag('-t'));\n\n})-\u003edescription(\"This is test command description :) ^^\")-\u003eflags('-t');\n```\n\n![image](https://user-images.githubusercontent.com/18489496/87862405-095edd00-c950-11ea-9cd7-f26b2823981f.png)\n\n\n### :star: Add command alias\n- you can add an alias to a command with the alias method  `-\u003ealias(string $alias)`\n\n```php\n\u003c?php\n// test command\n$conso-\u003ecommand(\"test\", function($input, $output){\n\n    $output-\u003ewriteLn(\"\\n test called by alias \\n\", 'red');\n\n})-\u003edescription(\"This is test command description :) ^^\")-\u003ealias('alias');\n```\n\n![image](https://user-images.githubusercontent.com/18489496/87862421-21cef780-c950-11ea-8a08-adf0efcab72e.png)\n\n\n### :star: Define command help\n- you can add help instructions to a command using the help method `-\u003ehelp(array $help)`\n- command help can be displayed using the `-h` or `--help` flags\n- help array must be an array of sub commands, options and flags with their descriptions\n```php\n\u003c?php\n// test command\n$conso-\u003ecommand(\"test\", function($input, $output){\n\n    $output-\u003ewriteLn(\"\\n test called by alias \\n\", 'red');\n\n})-\u003edescription(\"This is test command description :) ^^\")-\u003esub('one')-\u003eflags('-t')\n\n  -\u003ehelp([\n      \"sub commands\" =\u003e [\n          \"one\" =\u003e \" help text for sub command goes here\"\n        ],\n      \"flags\" =\u003e [\n          \"-t\" =\u003e \"help text for flag goes here\"\n        ]\n  ]);\n```\n![image](https://user-images.githubusercontent.com/18489496/88392798-e94e7400-cdbc-11ea-8de6-5fab02cdfb01.png)\n\n\n### :star: Group commands\n - you can group commands using the `group()` method\n```php\n\u003c?php\n\n$conso-\u003egroup('my group of commands:', function($conso){\n\n    $conso-\u003ecommand(\"command\", function(){})-\u003edescription('This is command description');\n    $conso-\u003ecommand(\"test\",    function(){})-\u003edescription('This is command description');\n    $conso-\u003ecommand(\"make\",    function(){})-\u003edescription('This is command description');\n\n});\n\n```\n![image](https://user-images.githubusercontent.com/18489496/88970755-3fd31b00-d2b3-11ea-9860-2ff024a6a2dc.png)\n\n### :star: Class commands\n- class commands are very helpful for big commands\n- first you need to create an `app/Commands` folder.\n- you can also move your commands definitions file `commands.php` to `app` folder to clean up things.\n- don't forget to autoload your commands with composer `psr-4{ \"App\\\\\" : \"app\" }`\n- now you need add commands paths and namespaces to conso to allow the build in command (command) to automatically create commands for you.\n\n```php\n    // add this to your conso file before run method\n    $conso-\u003esetCommandsPath('app/Commands');\n    $conso-\u003esetCommandsNamespace('App\\\\Commands');\n```\n- to create a class command run `php conso command:make {command name}`\n- for example lets create a test class command `php conso command:make test`\n- this will generate a `Test` command class like this:\n\n```php\n\u003c?php\n\nnamespace App\\Commands;\n\nuse Conso\\{Conso, Command};\nuse Conso\\Contracts\\{CommandInterface,InputInterface,OutputInterface};\n\nclass Test extends Command implements CommandInterface\n{\n    /**\n     * sub commands\n     *\n     * @var array\n     */\n    protected $sub  = [\n\n    ];\n\n    /**\n     * flags\n     *\n     * @var array\n     */\n    protected $flags = [\n\n    ];\n\n    /**\n     * command help\n     *\n     * @var array\n     */\n    protected $help  = [\n\n    ];\n\n    /**\n     * command description\n     *\n     * @var string\n     */\n    protected $description = 'This is Test command description.';\n\n    /**\n     * execute method\n     *\n     * @param  InputInterface  $input\n     * @param  OutputInterface $output\n     * @return void\n     */\n    public function execute(InputInterface $input, OutputInterface $output) : void\n    {\n        commandHelp($this-\u003eapp-\u003einvokedCommand, $output);\n    }\n}\n```\n- now you need to register this command in your `commands.php` file:\n```php\n\n$conso-\u003ecommand('test', Your\\NameSpace\\Test::class);\n\n```\n- by default `test` command will run the `execute` method if no sub command is provided\n- each sub command is a separate method\n\n## :star: Accessing app from commands :\n - from a callback command\n\n```php\n\u003c?php\n\n// test command\n$conso-\u003ecommand(\"test\", function($input, $output){\n\n    // get app config\n    $this-\u003egetName();\n    $this-\u003egetVersion();\n    $this-\u003egetAuthor();\n    $this-\u003egetCommandsPath();\n    $this-\u003egetCommandsNamespace();\n\n    // calling another command\n    $this-\u003ecall('command:subcommand -f --flags');\n});\n\n```\n - from a class command\n\n```php\n\u003c?php\n\n    /**\n     * execute method\n     *\n     * @param  InputInterface  $input\n     * @param  OutputInterface $output\n     * @return void\n     */\n    public function execute(InputInterface $input, OutputInterface $output) : void\n    {\n        // get app config\n        $this-\u003eapp-\u003egetName();\n        $this-\u003eapp-\u003egetVersion();\n        $this-\u003eapp-\u003egetAuthor();\n        $this-\u003eapp-\u003egetCommandsPath();\n        $this-\u003eapp-\u003egetCommandsNamespace();\n\n        // calling another command\n        $this-\u003eapp-\u003ecall('command:subcommand -f --flags');\n    }\n\n```\n### :star: Commands namespace\n - you can wrap commands in the same namespace with `namespace()` method which makes things cleaner\n\n```php\n\u003c?php\n\n$conso-\u003enamespace('Conso\\\\Commands', function($conso){\n\n    // all commands withing Conso\\Commands namespace\n    $conso-\u003ecommand(\"command\", Command::class);\n    $conso-\u003ecommand(\"test\",    Test::class);\n    $conso-\u003ecommand(\"make\",    Make::class);\n\n});\n\n```\n\n### :star: Http support\n- you can invoke conso from the browser or any http client just by passing commands to the input instance\n```php\n\u003c?php declare(strict_types=1);\n\nuse Conso\\{\n    Conso,Input,Output\n};\n\nrequire 'vendor/autoload.php';\n\n// you can sanitize and pass your command her\n$command = 'command:make HttpCommand';\n\n$input   = new Input($command);\n\n$conso   = new Conso($input, new Output);\n\nrequire 'commands.php';\n\n$conso-\u003erun();\n\n```\n### :star: Compile your app to an executable shareable single `.phar` file :\n- you can use this feature from version `2.0` and above.\n- to compile your application and create a shareable `.phar` file use the built in `compile` command.\n- run `php conso compile:init` to create a `conso.json` build file.\n\n![compile:init](https://user-images.githubusercontent.com/18489496/91350990-68313500-e7df-11ea-8fe2-e0ed1db373af.png)\n\n- this will generate a json file like follow:\n```js\n{\n    \"src\": [ /* your pacakge directories to compile should be added here */\n        \"src\\/Conso\", \n        \"vendor\" /* package dependencies if any */\n    ],\n    \"build\": \"build\", /* build location */\n    \"stub\": \"conso\",  /* stub file (the entry point of your phar) */\n    \"phar\": \"conso.phar\" /* output (your phar file name) */\n}\n\n```\n- your stub file should look something like this:\n\n```php\n\u003c?php // no need for shebang it will be added automatically \n\ndeclare(strict_types=1);\n\nuse Conso\\{\n    Conso,Input,Output\n};\n\nrequire 'vendor/autoload.php';\n\n$conso = new Conso(new Input, new Output);\n\n$conso-\u003esetName(\"app name\");\n$conso-\u003esetVersion(\"2.0.0\");\n\n$conso-\u003esetSignature(\" app signature \");\n\n$conso-\u003edisableBuiltInCommands(); // disable conso built in commands\n\n// include your commands\n// require 'app/commands.php';\n\n$conso-\u003erun();\n```\n- now you can run `php conso compile` and you will get your package compiled to a `phar` file.\n\n![compiled](https://user-images.githubusercontent.com/18489496/91352004-1ab5c780-e7e1-11ea-8535-5d1260656720.png)\n\n- you can use `--no-shebang` flag to avoid adding shebang to your `phar` file (this is useful if you want to invoke your `phar` file from `http`)\n\n\n### :star: Testing helpers:\n- you can use `Conso\\Testing\\TestCase` test helper class for testing which helps you to :\n    - turn on testing mode for you (return results instead of outputing to STDOUT).\n    - disable ansi colors which is not needed when testing.\n\n## ✨ Todo\n- improve code quality.\n\n## ✨ Contributing\n\nThank you for considering to contribute to Conso. All the contribution guidelines are mentioned **[Here](CONTRIBUTE.md)**.\n\n## 💖 Support\n\nIf this project helped you reduce time to develop, you can give me a cup of coffee :) : **[Paypal](https://www.paypal.me/lotfio)**.\n\n## ✨ License\n\nConso is an open-source software licensed under the **[MIT license](LICENCE)**.\n","funding_links":["https://www.paypal.me/lotfio)*"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flotfio%2Fconso","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flotfio%2Fconso","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flotfio%2Fconso/lists"}