Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lotfio/conso
:anger: PHP console applications for cool kids :anger:
https://github.com/lotfio/conso
aven cli composer conso console console-app console-application console-component php php-console symphony-console
Last synced: 21 days ago
JSON representation
:anger: PHP console applications for cool kids :anger:
- Host: GitHub
- URL: https://github.com/lotfio/conso
- Owner: lotfio
- License: mit
- Created: 2019-01-15T10:36:41.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2021-01-23T15:04:07.000Z (almost 4 years ago)
- Last Synced: 2024-08-17T22:32:29.698Z (3 months ago)
- Topics: aven, cli, composer, conso, console, console-app, console-application, console-component, php, php-console, symphony-console
- Language: PHP
- Homepage:
- Size: 878 KB
- Stars: 45
- Watchers: 8
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
Conso (PHP console applications for cool kids).
## 🔥 Introduction :
Conso is a simple, lightweight PHP package that helps you create (executable, `.phar`, shareable) command line applications easily.
## :collision: Is it really lightweight ?
## 📌 Requirements :
- PHP >= 7.2 or newer versions
- PHPUnit >= 8 (for testing purpose)
## 🚀 Installation :
* ***Via composer :***
```php
composer require lotfio/conso
```
* ***for testing***
```php
composer test
```
## 🎉 Write your first command
- create a `commands.php` file.
- create a `conso` file (you can change the name as you like).
- include your `commands.php` file into `conso` executable file.
- it should look something like this.
```php
#!/usr/bin/env php
run();
```
### :star: Available config methods :
```php
setSignature(); // set application signature (top logo)
$conso->setName(); // set application name
$conso->setVersion(); // set application version
$conso->setAuthor(); // set application author
$conso->disableBuiltInCommands(); // disable builtin commands
```
- now define a new `test` command in your `commands.php` :
```php
command("test", function($input, $output){
$output->writeLn("\n hello from test \n", 'red');
});
```
- now your command has been registered.
- run `php conso --commands` or `./conso --commands` in your terminal and you should see your command.
- command test is registered now ***(no description is shown you can add this later on)***.
- run your command `php conso test` or `./conso test`.
### :star: Add description
- `->description(string $description)`;
```php
command("test", function($input, $output){
$output->writeLn("\n hello from test \n", 'red');
})->description("This is test command description :) ^^");
```
### :star: Define sub commands
- `->sub(string|array $subCommand)`;
```php
command("test", function($input, $output){
if($input->subCommand() == 'one')
exit($output->writeLn("\n hello from one \n", 'yellow'));
if($input->subCommand() == 'two')
$output->writeLn("\n hello from two \n", 'green');
})->description("This is test command description :) ^^")->sub('one', 'two');
```
### :star: Define command flags
- you can define flags using the flag method `->flags(string|array $flag)`
- this is a list of reserved flags `['-h', '--help', '-v', '--version', '-c', '--commands', '-q', '--quiet', '--ansi', '--no-ansi']`
- for debug you can use `-vv or --verbose` flags to get more details about the error
- you can also pass values to flags `--flag=value` or `-f=value`
```php
command("test", function($input, $output){
if($input->flag('-t') !== false)
$output->writeLn("\n flag -t is defined for this command.\n", 'red');
// you can get flag values
// $output->writeLn($input->flag('-t'));
})->description("This is test command description :) ^^")->flags('-t');
```
### :star: Add command alias
- you can add an alias to a command with the alias method `->alias(string $alias)`
```php
command("test", function($input, $output){
$output->writeLn("\n test called by alias \n", 'red');
})->description("This is test command description :) ^^")->alias('alias');
```
### :star: Define command help
- you can add help instructions to a command using the help method `->help(array $help)`
- command help can be displayed using the `-h` or `--help` flags
- help array must be an array of sub commands, options and flags with their descriptions
```php
command("test", function($input, $output){
$output->writeLn("\n test called by alias \n", 'red');
})->description("This is test command description :) ^^")->sub('one')->flags('-t')
->help([
"sub commands" => [
"one" => " help text for sub command goes here"
],
"flags" => [
"-t" => "help text for flag goes here"
]
]);
```
### :star: Group commands
- you can group commands using the `group()` method
```php
group('my group of commands:', function($conso){
$conso->command("command", function(){})->description('This is command description');
$conso->command("test", function(){})->description('This is command description');
$conso->command("make", function(){})->description('This is command description');
});
```
### :star: Class commands
- class commands are very helpful for big commands
- first you need to create an `app/Commands` folder.
- you can also move your commands definitions file `commands.php` to `app` folder to clean up things.
- don't forget to autoload your commands with composer `psr-4{ "App\\" : "app" }`
- now you need add commands paths and namespaces to conso to allow the build in command (command) to automatically create commands for you.
```php
// add this to your conso file before run method
$conso->setCommandsPath('app/Commands');
$conso->setCommandsNamespace('App\\Commands');
```
- to create a class command run `php conso command:make {command name}`
- for example lets create a test class command `php conso command:make test`
- this will generate a `Test` command class like this:
```php
app->invokedCommand, $output);
}
}
```
- now you need to register this command in your `commands.php` file:
```php
$conso->command('test', Your\NameSpace\Test::class);
```
- by default `test` command will run the `execute` method if no sub command is provided
- each sub command is a separate method
## :star: Accessing app from commands :
- from a callback command
```php
command("test", function($input, $output){
// get app config
$this->getName();
$this->getVersion();
$this->getAuthor();
$this->getCommandsPath();
$this->getCommandsNamespace();
// calling another command
$this->call('command:subcommand -f --flags');
});
```
- from a class command
```php
app->getName();
$this->app->getVersion();
$this->app->getAuthor();
$this->app->getCommandsPath();
$this->app->getCommandsNamespace();
// calling another command
$this->app->call('command:subcommand -f --flags');
}
```
### :star: Commands namespace
- you can wrap commands in the same namespace with `namespace()` method which makes things cleaner
```php
namespace('Conso\\Commands', function($conso){
// all commands withing Conso\Commands namespace
$conso->command("command", Command::class);
$conso->command("test", Test::class);
$conso->command("make", Make::class);
});
```
### :star: Http support
- you can invoke conso from the browser or any http client just by passing commands to the input instance
```php
run();
```
### :star: Compile your app to an executable shareable single `.phar` file :
- you can use this feature from version `2.0` and above.
- to compile your application and create a shareable `.phar` file use the built in `compile` command.
- run `php conso compile:init` to create a `conso.json` build file.
- this will generate a json file like follow:
```js
{
"src": [ /* your pacakge directories to compile should be added here */
"src\/Conso",
"vendor" /* package dependencies if any */
],
"build": "build", /* build location */
"stub": "conso", /* stub file (the entry point of your phar) */
"phar": "conso.phar" /* output (your phar file name) */
}
```
- your stub file should look something like this:
```php
setName("app name");
$conso->setVersion("2.0.0");
$conso->setSignature(" app signature ");
$conso->disableBuiltInCommands(); // disable conso built in commands
// include your commands
// require 'app/commands.php';
$conso->run();
```
- now you can run `php conso compile` and you will get your package compiled to a `phar` file.
- 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`)
### :star: Testing helpers:
- you can use `Conso\Testing\TestCase` test helper class for testing which helps you to :
- turn on testing mode for you (return results instead of outputing to STDOUT).
- disable ansi colors which is not needed when testing.
## ✨ Todo
- improve code quality.
## ✨ Contributing
Thank you for considering to contribute to Conso. All the contribution guidelines are mentioned **[Here](CONTRIBUTE.md)**.
## 💖 Support
If this project helped you reduce time to develop, you can give me a cup of coffee :) : **[Paypal](https://www.paypal.me/lotfio)**.
## ✨ License
Conso is an open-source software licensed under the **[MIT license](LICENCE)**.