Console

Aurora has a simple but powerful command-line interface client, the Console.

With it you'll be able to quickly scaffold you project, by creating controllers, migrations, models, etc.; but also to execute maintenance and configuration tasks through user-defined commands.

To use it you simple type:

php aurora <command> <arguments>

For example, you may want to execute the pending database migrations, you can do so by running:

php aurora migrate

Or create a controller named ApiController:

php aurora create:controller ApiController

Each command can have its own arguments, some required, some optional; they are documented in its corresponding section.

Creating commands

There are a lot of built-in commands, but you may also create your own. To do so, execute the following:

php aurora create:command <CommandName>

For example:

php aurora create:command DeleteLockedAccounts

That will create a file name DeleteLockedAccounts.php in your app/Console/Commands directory, open it up and you'll see the following:

<?php

declare(strict_types = 1);

namespace App\Console\Commands;

use Aurora\Console\AbstractCommand;

class DeleteLockedAccounts extends AbstractCommand {

    /**
     * Command signature
     * @var string
     */
    protected $signature = 'delete:locked:accounts';

    /**
     * Arguments definition
     * @var string
     */
    protected $arguments = '';

    /**
     * Handler function
     */
    public function handle() {
        # Add your command logic here
        $this->blank()->info('DeleteLockedAccounts')->blank();
    }
}

The important parts to note here are the $signature property, that defines how it will be invoked from the command line, the $arguments property that specifies which arguments are expected and the handle() method that is called whenever you run the command.

In this case the $signature is delete:locked:accounts so you can run the command by typing:

php aurora delete:locked:accounts

But if you try to invoke it now, you'll get an error. And that is because we have created the command but we forgot to register it.

To register the command just open app/Console/App.php and modify it so that it looks like the following:

<?php

declare(strict_types = 1);

namespace App\Console;

use Aurora\App\ConsoleApp;
use Aurora\Console\Console;
use App\Console\Commands\DeleteLockedAccounts;

class App extends ConsoleApp {

    function start() {
        $console = resolve(Console::class);
        $console->command(DeleteLockedAccounts::class);
    }
}

A more elegant way of doing that would be creating a Service Provider (see Registering commands) and registering the command there.

Adding Arguments

To add an argument just edit the $arguments property, for example:

protected $arguments = '{email?} {--V|verbosity=?}';

By doing that you defined two arguments:

• email - An optional parameter (denoted by the ? at the end)
• --verbosity - An optional flag (denoted by the ? at the end) with a value (denoted by the = symbol) that has a short form (-V)

Now, you basically have two kinds of arguments:

• Parameters - They are not named, you just pass a value, for the above example, you can do php aurora delete:locked:accounts foo@bar.baz where foo@bar.baz is the email parameter
• Flags or options - They are named and can be boolean or scalar and can have a shortcut. In the above example you may do php aurora delete:locked:accounts foo@bar.baz --verbosity=2 or even php aurora delete:locked:accounts foo@bar.baz -V=2. In this case, the verbosity is scalar and will have a value of 2 for this run.

If the argument is not scalar it is just a boolean toggle (on/off), for example, to add a force flag you can do the following:

protected $arguments = '{email?} {--V|verbosity=?} {--F|force?}';

That way to specify that the force option should be activated, you can run it like php aurora delete:locked:accounts foo@bar.baz --force or with its shortcut php aurora delete:locked:accounts foo@bar.baz -F.

Reading arguments

Once you have added the arguments you can process them by using the option() and argument() methods, for example:

public function handle() {
    $email = $this->argument('email');
    $verbose = $this->option('verbose');
    $force = $this->option('force');
    # Add your command logic here
    $this->blank()->info('DeleteLockedAccounts')->blank();
}

You must use the argument() method for parameters and the option() method for options.

In the case of parameters you will always get its raw value, while for options you will get the scalar value of a boolean depending on the argument.

Console output

In the sample code there is a part that just echoes the command name back to the console:

$this->blank()->info('DeleteLockedAccounts')->blank();

While it runs in a single line, in reality it is comprised of three function calls to the blank() and info() methods, which are just a part of the several available:

• blank - Displays an empty line, takes no parameters
• line - Displays an unformated text line, pass the text you want to show
• info - Displays a blue-colored text line, pass the text you want to show
• success - Displays a greeen-colored text line, pass the text you want to show
• error - Displays a red-colored text line, pass the text you want to show
• warning - Displays a yellow-colored text line, pass the text you want to show

There is another method that lets you show progress bars:

$this->progressBar($value);

As long as you don't use any other method, the progress bar will redraw and update each time you call the function with a new value.

Console input

There is also possible to get data from the user, be it a single character or a complete string. It is done through the following functions:

• getKey - Get a single key, takes an array of valid keys and an optional text prompt
• getString - Get an string, takes an optional text prompt and a boolean flag which specifies if the text should be hidden from the user (for passwords, for example).

Next up, using databases.