railt/console

This package is abandoned and no longer maintained. No replacement package was suggested.

The Railt Console Component

dev-master 2018-09-14 14:16 UTC

Requires

• php: ^7.1.3
• railt/io: 1.2.*|dev-master
• railt/lexer: 1.2.*|dev-master
• symfony/console: ~3.3|~4.0

Requires (Dev)

• phpunit/phpunit: ^6.5

MIT

• Kirill Nesmeyanov

• cli
• console

README

Installation

• Install package using composer.

composer require railt/console

• Add discovering event into your composer.json.

{
    "scripts": {
         "post-autoload-dump": [
             "Railt\\Console\\Manifest::discover"
         ]
     }
}

Usage

Just run vendor/bin/railt (or vendor/bin/railt.bat for Windows OS) command.

For more convenient use, you can make a compilation into a local directory:

ln -s ./vendor/railt/console/railt ./railt

Commands

Let's create our first command.

use Railt\Console\Command;

class ExampleCommand extends Command
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'command:name';
    
     /**
      * The console command description.
      *
      * @var string
      */
    protected $description = 'Console command description';
    
     /**
      * Create a new command instance.
      *
      * @return void
      */
    public function handle()
    {
        // Command execution code
    }
}

Arguments

All user supplied arguments and options are wrapped in curly braces. In the following example, the command defines one required argument: user:

protected $signature = 'example:command {user}';

You may also make arguments optional and define default values for arguments:

// Optional argument...
protected $signature = 'example:command {user?}';

// Optional argument with default value...
protected $signature = 'example:command {user=foo}';

Options

Options, like arguments, are another form of user input. Options are prefixed by two hyphens (--) when they are specified on the command line.

There are two types of options: those that receive a value and those that don't. Options that don't receive a value serve as a boolean "switch". Let's take a look at an example of this type of option:

protected $signature = 'example:command {user} {--force}';

In this example, the --force switch may be specified when calling the Artisan command. If the --force switch is passed, the value of the option will be true. Otherwise, the value will be false:

php railt example:command 42 --force

Options With Values

Next, let's take a look at an option that expects a value. If the user must specify a value for an option, suffix the option name with a = sign:

protected $signature = 'example:command {user} {--dir=}';

In this example, the user may pass a value for the option like so:

php railt example:command 42 --dir=./example/path

You may assign default values to options by specifying the default value after the option name. If no option value is passed by the user, the default value will be used:

protected $signature = 'example:command {user} {--dir=./some/any}';

Option Shortcuts

To assign a shortcut when defining an option, you may specify it before the option name and use a | delimiter to separate the shortcut from the full option name:

protected $signature = 'example:command {user} {--F|force}';

Input Arrays

If you would like to define arguments or options to expect array inputs, you may use the * character. First, let's take a look at an example that specifies an array argument:

protected $signature = 'example:command {user*}';

When calling this method, the user arguments may be passed in order to the command line. For example, the following command will set the value of user to ['foo', 'bar']:

php railt example:command foo bar

When defining an option that expects an array input, each option value passed to the command should be prefixed with the option name:

protected $signature = 'example:command {--id=*}';

php railt example:command --id=1 --id=2

Input Descriptions

You may assign descriptions to input arguments and options by separating the parameter from the description using a colon. If you need a little extra room to define your command, feel free to spread the definition across multiple lines:

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'example:command
                        {user : The ID of the user}
                        {--force : Force a command execution}';

Discovering

The "discovering" system provides the ability to configure the framework using a composer.

Commands

Simply add a link to the command class. In this case, the command will be automatically added to the console railt executable file.

Console command class should be instance of Symfony or Railt Command.

{
    "extra": {
        "railt": {
            "commands": [
                "Path\\To\\ConsoleCommand",
                "..."
            ]
        }
    }
}

Exceptions

All console commands running over railt binary has a better console exceptions handling.

You can use this API manually:

use Railt\Console\Highlighter;
use Railt\Console\ExceptionRenderer;
use Railt\Console\Language\PHPLanguage;

/**
 * Code Highlighter
 */
$highlight = new Highlighter();
$highlight->add(new PHPLanguage()); // Add support of PHP code highlight

/**
 * Renderer
 */
$renderer = new ExceptionRenderer($highlight);
$result = $renderer->render(new \Exception('example'));

// $output should be instance of Symfony OuputInterface
$output->write($result);