Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/biurad/php-clite
⌨ A library that provides a lightweight version of writing code to run on terminal.
https://github.com/biurad/php-clite
biurad command-line console console-application console-lite php stub
Last synced: about 1 month ago
JSON representation
⌨ A library that provides a lightweight version of writing code to run on terminal.
- Host: GitHub
- URL: https://github.com/biurad/php-clite
- Owner: biurad
- License: mit
- Created: 2019-05-14T22:23:00.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-05-17T00:39:34.000Z (over 4 years ago)
- Last Synced: 2024-10-15T01:21:37.036Z (3 months ago)
- Topics: biurad, command-line, console, console-application, console-lite, php, stub
- Language: PHP
- Homepage:
- Size: 186 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
> This library was strongly inspired by [Symfony Console](https://symfony.com/doc/current/components/console.html)
Console Lite - BiuradPHP Toolbox
This is the light weight version of Symfony Console. @author Divine Niiquaye.
[](https://packagist.org/packages/biurad/consolelite)
[](https://travis-ci.org/biurad/Console-lite)
[](https://packagist.org/packages/biurad/consolelite)
[](https://github.styleci.io/repos/186709012)
[](https://bettercodehub.com/)
[](https://app.codacy.com/app/biustudio/Console-lite?utm_source=github.com&utm_medium=referral&utm_content=biurad/Console-lite&utm_campaign=Badge_Grade_Dashboard)
[](https://packagist.org/packages/biurad/consolelite)
The Console tool allows you to create command-line commands. Your console commands can be used for any recurring task, stub generator, phar compile, such as cronjobs, imports, or other batch jobs.
# Installation
Just run this composer command:
```bash
composer require biurad/consolelite
```
# Quickstart
## Creating a Console Application
First, you need to create a PHP script to define the console application:
```php
#!/usr/bin/env php
run();
```
Console Lite has a totally different approach in building console commands, not similar to Symfony Console but similar to Laravel Artisan. This was done in order to make it light weight.
You can register the commands using two different ways:
1. ```php
// ...
$application->register(new GenerateCommand());
```
2. ```php
// ...
$application->command('hello', 'Enter your name to start', function () {
$this->writeln('Hello World');
});
## Console Command Example
### This example is to print out a name without creating a class file
```php
#!/usr/bin/env php
command('hello {name}', 'Enter your name', function($name) {
$this->writeln("Hello {$name}");
});
// 3. Run app
$application->run();
```
### This example is to print out a name creating a class file
```php
writeln("Hello {$name}");
}
}
```
After that you create a filename without any path or file extention:
example, create a **console** `file` without file extention.
```php
#!/usr/bin/env php
register(new NameCommand);
// 3. Run app
$application->run();
```
### Show Help
You can show help by putting `--help` or `-h` for each command. For example:
```bash
php console hello --help
```
### Enable Color
You can force colors by putting `--ansi` for each command. For example:
```bash
php console hello --ansi
```
### Disable Color
You can disable color by putting `--no-ansi` for each command. For example:
```bash
php console hello --no-ansi
```
# Command Usage and Options
The command has a powerful property called signature, this contains all the commands, options and arguements.
## The basic usage is simple
- Create a `class` and extend it to `BiuradPHP\Toolbox\ConsoleLite\Command`.
- Or use the method `command` from `BiuradPHP\Toolbox\ConsoleLite\Application`.
- Implement the `properties` method and register options, arguments, commands and set help texts
- Implementing decription to command, add the following to the protected property $signature or method `command` of Application class.
```php
protected $description = 'Enter a description'; // add a general description.
```
```php
command('hello', 'This is a description'/** add a general description to the second parameter. */, function () {
$this->writeln('Hello World');
});
```
- Implementing add command, the protected proterty $signature holds the command, same applies to Application method `command`.
```php
protected $signature = 'hello'; // add a command.
```
- Implementing options, add the following to the protected property $signature.
```php
protected $signature = 'hello {--option} {--anotheroption}'; // the '--' represents an option.
```
- Implementing options has an input, add the following to the protected property $signature.
```php
protected $signature = 'hello {--option=} {--anotheroption=}'; // the '=' represents an option has an input.
```
- Implementing arguements, add the following to the protected property $signature.
```php
protected $signature = 'hello {arguement} {anotherarguement}'; // this represents an argument.
```
- Implementing description for options and arguements, add the following to the protected property $signature.
```php
protected $signature = 'hello {arguement::Description} {--option::Description} {--option=::Description}'; // the '::' represents a description.
```
- > NB: This applies to `command` method in Application class.
- Implement the `handle` method and do your business logic there.
- Open the file Command.php in folder `src` and find out the methods to use from there.
## Exceptions
By default the CLI classes registers two error or exception handlers.
- Application Exception
To use the Application Exception, use example:
```php
#!/usr/bin/env php
command('exception {--test} {--error} {--replace}', 'This is an exception test', function () {
// This throws an application exception.
if (! $this->hasOption('test')) {
throw new ConsoleLiteException('Test option not allowed');
}
// This throws a deprecated exception.
if ($this->hasOption('error')) {
throw new DeprecatedException(['--error', '--replace']);
}
$this->block('This is an Exception test');
});
$application->run();
```
## Colored output
Colored output is handled through the `Colors` class. It tries to detect if a color terminal is available and only
then uses terminal colors. You can always suppress colored output by passing ``--no-ansi`` to your scripts.
Simple colored messages can be printed by you using the convinence methods `writeln()`, `write()`, `sucessBlock()`, `style()`,
`errorBlock()`, and `block()`. Each of this methods contains three parameters, one for message, two for styles including forground color, background color, and options.
Within the second parameters of the above mentioned methods or functions for writing raw or colored text unto the output. forground color, background color or options, could be defined as string or in array. backgorund colors begins with a '**bg_**' and colors are writen as they are.
e.g. to write background color only
```php
$this->writeln('Message to output', 'bg_yellow');
```
e.g. to write forground color only
```php
$this->writeln('Message to output', 'yellow');
```
e.g. to write options only
```php
$this->writeln('Message to output', 'italic');
```
e.g. to write all styles combined
```php
$this->writeln('Message to output', ['bg_yellow', 'green', 'bold']);
```
The formatter allows coloring full columns. To use that mechanism pass an array of colors as third parameter to
its `format()` method. Please note that you can not pass colored texts in the second parameters (text length calculation
and wrapping will fail, breaking your texts).
## Formatter
The `Formatter` class allows you to align texts in multiple columns. It tries to figure out the available
terminal width on its own. It can be overwritten by setting a `COLUMNS` environment variable.
The formatter is used through the `format()` method which expects at least two arrays: The first defines the column
widths, the second contains the texts to fill into the columns. Between each column a border is printed (a single space
by default).
The formatter contains other useful methods used to format time, memory, file paths and more.
Columns width can be given in three forms:
- fixed width in characters by providing an integer (eg. ``15``)
- precentages by provifing an integer and a percent sign (eg. ``25%``)
- a single fluid "rest" column marked with an asterisk (eg. ``*``)
When mixing fixed and percentage widths, percentages refer to the remaining space after all fixed columns have been
assigned.
Space for borders is automatically calculated. It is recommended to always have some relative (percentage) or a fluid
column to adjust for different terminal widths.
The formatter is used for the automatic help screen accessible when calling your script with ``-h`` or ``--help``.
## Compiling to Phar
ConsoleLite has function were you could compile your php source-codes into a phar file.
You dont need to create a Phar class, ConsoleLite has it taken care of.
if you installed ConsoleLite as a composer dependency in your project, then hit
```bash
php vendor/bin/clite compile --config
```
This generates a sample clite.json file, looking something like the one below
```json
{
"application": "ConsoleLite Configuration",
"generated": "2019/06/17 03:41",
"version": "1.0.0",
"stuble": {
"config": {
"name": "ConsoleLite Stub Generator"
}
},
"compile": {
"config": {
"name": "clite.phar",
"index": "docs/tests/test",
"compression": 0,
"signature": null
},
"pack": {
"autoload": "vendor/autoload.php",
"bin": "docs/tests/test",
"files": [
"clite.json",
"composer.json"
],
"directory": [
"src/",
"vendor/"
],
"excludes": [
"Tests/*",
"!*.php"
]
},
"unpack": {
"extract-to": "unpack",
"files": null,
"overwrite": true
}
}
}
```
The `compile` command has options for two kinds of input, thus the **pack** and **unpack**. Given them different config settings in clite.json.
If you already know the Phar class in php. you can finish up the steps by settings them up in clite.json.
The phar packs or reads directories and files from your working directory.
The **pack** input after command `compile` generate a phar file using the clite.json or using the options below.
- --signature -> Set the signing signature of the phar. eg openssl.key.
- --index -> Set the main file were the phar will be looaded from.
- --compression -> Set the compression level for the phar. eg 0 or 4096.
- --directory -> Set the directory where the phar is generated from.
- --version -> Set the version of the project, so you stay up to date.
- --bin -> Set the bin to be added to the compiled phar file.
- --files -> Add the files that will be needed example, LICENSE file.
- --excludes -> Add the excluded files or directories from the compiled phar file.
- --type -> Set the type of phar that should be generated cli or web.
- --autoload -> Add the file which contains all the classes and namespaces for autoloading.
The **unpack** input after the command `compile` extracts exverything containing in the phar file, into a directory reading from the clite.json or
using the options.
- --files -> List the files that will be needed example, LICENSE file.(optional)
- --extract -> Set the folder where the files and directories in phar will be extracted to.
- --overwrite -> Allow the previous extracted folders to be overwritten.
## Stuble
Stuble is command line tool built with PHP to simplify working with stubs.
Stuble will collect parameters in your stub(s) file(s) and ask you those parameters.
So you don't need to write scripts to handle each stub file.
This is a class that simple let's you generate a class or php file out of a template.
This is an abstract class, so you don't need to use it like phar, but use it to create a stub.
For usuage, extends the your stuble class to `StubleGenerator`.
The StubleGenerator has a similarity to Laravel `GeneratorCommand`, cause part of the class is from Laravel, but made simple. Check the class to find out.
When working with ConsoleLite Stuble, you don't need to input a destination path. Path deternation are generated from your namespaces and then the class in inserted into the the namespaces folders, starting from your working directory.
This code below is an example of how to implement a stuble.
```php
*/
namespace BiuradPHP\Toolbox\ConsoleLite\Commands;
use BiuradPHP\Toolbox\ConsoleLite\Stuble\StubGenerator;
class CommandStub extends StubGenerator
{
/**
* The console command name.
*
* @var string
*/
protected $signature = 'stuble
{--command=::Enter a command name of your choice in "coomand:name" pattern.}
{--force::Forces the class to be overwritten}';
/**
* The console command description.
*
* @var string
*/
protected $description = 'Create a new Php File out of a stub';
/**
* The type of class being generated.
*
* @var string
*/
protected $type = 'Example command';
/**
* Set the namespace.
*
* @var string
*/
protected $namespace = 'App\\Console\\';
/**
* Set the class.
*
* @var string
*/
protected $class = 'WorldClass';
/**
* Get the stub file for the generator.
*
* @return string
*/
protected function getStub()
{
return __DIR__.'/../resources/stubs/example.stub';
}
/**
* Replace the class name for the given stub.
*
* @param string $stub
* @param string $name
*
* @return string
*/
protected function replaceClass($stub, $name)
{
$stub = parent::replaceClass($stub, $name);
return str_replace('generate:command', $this->hasOption('command') ?: 'command:name', $stub);
}
}
```
and the template file which was saved in `.stub` file extention, looks like the one below
```php