Console Commands

Console commands for managing Ecotone message consumers and projections

Ecotone provides support for creating Console Commands. Just like the other parts of Ecotone's modules, we register Command in decoupled way using Attributes. This way creating new Console Commands become effortless and clean from extending or implementing framework specific classes and can be placed in code wherever it feels best in given context.

Commands with Arguments

We register new Console Command using ConsoleCommand attribute:

class EmailSender
{
    #[ConsoleCommand('sendEmail')]
    public function execute(string $email, string $type): void
    {
    }
}

Ecotone will register given under "sendEmail" name with two arguments "email" and "type".

Executing Command

Symfony

bin/console sendEmail "[e-mail]" "welcome"

Laravel

php artisan sendEmail "[e-mail]" "welcome"

Lite

$messagingSystem->runConsoleCommand(
   'sendEmail',
   [
      "email" => "[e-mail]",
       "type" => "welcome"
   ]
)

Ecotone will register method parameters as Command arguments.

Command Description

We may provide description for our Console Command, which will be visible in the Command listing of given framework (bin/console list, php artisan list):

class EmailSender
{
    #[ConsoleCommand('sendEmail', 'Sends email of given type to provided address')]
    public function execute(string $email, string $type): void
    {
    }
}

Commands with Options

We register new Console Command using ConsoleCommand attribute:

class EmailSender
{
    #[ConsoleCommand('sendEmail')]
    public function execute(string $email, #[ConsoleParameterOption] string $type): void
    {
    }
}

Ecotone will register given under "sendEmail" name with two arguments "email" and "type".

Executing Command

Symfony

bin/console sendEmail "[e-mail]" --type="welcome"

Laravel

php artisan sendEmail "[e-mail]" --type="welcome"

Lite

$messagingSystem->runConsoleCommand(
   'sendEmail',
   [
      "email" => "[e-mail]",
       "type" => "welcome"
   ]
)

Ecotone will register any method paramter with attribute ConsoleParameterOption as parameter and all boolean and array type hinted paramters too.

Providing default values

You may provide default value for your parameters, so there will be no need to pass them if not needed:

We register new Console Command using ConsoleCommand attribute:

class EmailSender
{
    #[ConsoleCommand('sendEmail')]
    public function execute(string $email, string $type = 'normal'): void
    {
    }
}

Executing Command

Symfony

bin/console sendEmail "[e-mail]"

Laravel

php artisan sendEmail "[e-mail]"

Lite

$messagingSystem->runConsoleCommand(
   'sendEmail',
   [
      "email" => "[e-mail]"
   ]
)

Array of Options

When needed we can expect array of Options to be passed:

class EmailSender
{
    #[ConsoleCommand('sendEmail')]
    public function execute(string $email, array $type): void
    {
    }
}

Executing Command

Symfony

bin/console sendEmail "[e-mail]" --type=normal --type=test

Laravel

php artisan sendEmail "[e-mail]" --type=normal --type=test

Lite

$messagingSystem->runConsoleCommand(
   'sendEmail',
   [
      "email" => "[e-mail]",
      "type" => ["normal", "test"],
   ]
)

Passing Services

When given Service is only needed for execution of specific Console Command, there is no need to pass it via constructor. We can scope the injection and inject it directly to our Console Command:

class EmailSender
{
    #[ConsoleCommand('sendEmail')]
    public function execute(
        string $email, 
        string $type, 
        #[Reference] EmailSender $emailSender
    ): void
    {
    }
}

Using Reference attribute, we can inject any Service available in Dependency Container, to our Console Command method.

Passing Message Headers

When running Console Commands we may pass additional Message Headers. This way we can provide context, which may be needed in order to handle given Console Command or for later sub-flows (Message Headers are automatically propagated).

class EmailSender
{
    #[ConsoleCommand('sendEmail')]
    public function execute(
        string $email, 
        string $type, 
        #[Header('token')] string $token
    ): void
    {
    }
}

Executing Command

We pass Message Headers in follow format --header={name}:{value}. We may passs as many Message Headers as we want.

Symfony

bin/console sendEmail "[e-mail]" --type=normal --header="token:123"

Laravel

php artisan sendEmail "[e-mail]" --type=normal --header="token:123"

Lite

$messagingSystem->runConsoleCommand(
   'sendEmail',
   [
      "email" => "[e-mail]",
      "type" => "normal",
      "header" => ["token:123"],
   ]
)

Headers passed this way are propagated for the whole execution, so they also reach infrastructure that resolves context from Message Headers - for example the Multi-Tenant connection, which picks the active tenant from the configured tenant header. This makes it possible to run tenant-aware Console Commands, e.g. --header="tenant:tenant_a". See Tenant-Aware Console Commands for a full example.

Writing to the Console

To write output from our Console Command, we type hint for ConsoleWriter. Ecotone will inject writer connected to the console of given framework - Symfony Console, Laravel Artisan or Tempest Console. This way our Command stays decoupled from framework specific classes, yet output lands in the actual console with native formatting:

use Ecotone\Messaging\Console\ConsoleWriter;

class EmailSender
{
    #[ConsoleCommand('sendEmail')]
    public function execute(string $email, ConsoleWriter $writer): void
    {
        $writer->info("Sending email to {$email}");
        
        $writer->success('Email was sent');
        $writer->warning('Email provider is close to rate limit');
        $writer->error('Email could not be sent');
    }
}

info, success, warning and error write colored messages (cyan, green, yellow, red), while write and writeln write plain text.

In Ecotone Lite output is written directly to the standard output as plain text.

Tables

We may render table using column headers and rows:

#[ConsoleCommand('listEmails')]
public function execute(ConsoleWriter $writer): void
{
    $writer->table(
        ['Email', 'Status'],
        [
            ['[e-mail]', 'sent'],
            ['[e-mail]', 'pending'],
        ]
    );
}

Progress Bars

For long running Commands we may show the progress:

#[ConsoleCommand('sendNewsletter')]
public function execute(ConsoleWriter $writer): void
{
    $subscribers = $this->subscribers();

    $progressBar = $writer->progressBar(count($subscribers));
    foreach ($subscribers as $subscriber) {
        $this->send($subscriber);
        $progressBar->advance();
    }
    $progressBar->finish();
}

Testing Console Output

During flow testing output is collected in memory, so we can simply assert against it:

$ecotoneLite = EcotoneLite::bootstrapFlowTesting([EmailSender::class], [new EmailSender()]);

$ecotoneLite->runConsoleCommand('sendEmail', ['email' => '[e-mail]']);

$this->assertSame(
    ['Email was sent'],
    $ecotoneLite->getInMemoryConsoleWriter()->getSuccessLines()
);

Database Transaction

When Dbal Module is enabled it will automatically wrap your Command in Database Transaction. When you want to trigger CommandBus which is wrapped in it's own transaction, it may have sense to turn transactions for Console Commands off:

final readonly class EcotoneConfiguration
{
    #[ServiceContext]
    public function dbalConfiguration()
    {
        return [
            DbalConfiguration::createWithDefaults()
                ->withTransactionOnConsoleCommands(false);
        ];
    }
}