railt / console
The Railt Console Component
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
This package is not auto-updated.
Last update: 2018-10-23 19:14:16 UTC
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);