Console Commands

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// src/Command/CreateUserCommand.php
namespace App\Command;

use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;

// the name of the command is what users type after "php bin/console"
#[AsCommand(name: 'app:create-user')]
class CreateUserCommand
{
    public function __invoke(): int
    {
        // ... put here the code to create the user

        // this method must return an integer number with the "exit status code"
        // of the command. You can also use these constants to make code more readable

        // return this if there was no problem running the command
        // (it's equivalent to returning int(0))
        return Command::SUCCESS;

        // or return this if some error happened during the execution
        // (it's equivalent to returning int(1))
        // return Command::FAILURE;

        // or return this to indicate incorrect command usage; e.g. invalid options
        // or missing arguments (it's equivalent to returning int(2))
        // return Command::INVALID
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

#[AsCommand(
    name: 'app:create-user',
    // this short description is shown when running "php bin/console list"
    description: 'Creates a new user.',
    // this is shown when running the command with the "--help" option
    help: 'This command allows you to create a user...',
    // this allows you to show one or more usage examples (no need to add the command name)
    usages: ['bob', 'alice --as-admin'],
)]
class CreateUserCommand
{
    public function __invoke(): int
    {
        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

#[AsCommand(name: 'app:create-user')]
class CreateUserCommand extends Command
{
    public function initialize(InputInterface $input, OutputInterface $output): void
    {
        // ...
    }

    public function interact(InputInterface $input, OutputInterface $output): void
    {
        // ...
    }

    public function __invoke(): int
    {
        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// ...
public function __invoke(OutputInterface $output): int
{
    // outputs multiple lines to the console (adding "\n" at the end of each line)
    $output->writeln([
        'User Creator',
        '============',
        '',
    ]);

    // the value returned by someMethod() can be an iterator (https://php.net/iterator)
    // that generates and returns the messages with the 'yield' PHP keyword
    $output->writeln($this->someMethod());

    // outputs a message followed by a "\n"
    $output->writeln('Whoa!');

    // outputs a message without adding a "\n" at the end of the line
    $output->write('You are about to ');
    $output->write('create a user.');

    return Command::SUCCESS;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

use Symfony\Component\Console\Attribute\Argument;

// The #[Argument] attribute configures $username as a
// required input argument and its value is automatically
// passed to this parameter
public function __invoke(#[Argument('The username of the user.')] string $username, OutputInterface $output): int
{
    $output->writeln([
        'User Creator',
        '============',
        '',
    ]);

    $output->writeln('Username: '.$username);

    return Command::SUCCESS;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// ...
use App\Service\UserManager;
use Symfony\Component\Console\Attribute\Argument;
use Symfony\Component\Console\Attribute\AsCommand;

#[AsCommand(name: 'app:create-user')]
class CreateUserCommand
{
    public function __construct(
        private UserManager $userManager
    ) {
    }

    public function __invoke(#[Argument] string $username, OutputInterface $output): int
    {
        // ...

        $this->userManager->create($username);

        $output->writeln('User successfully generated!');

        return Command::SUCCESS;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

// tests/Command/CreateUserCommandTest.php
namespace App\Tests\Command;

use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;

class CreateUserCommandTest extends KernelTestCase
{
    public function testExecute(): void
    {
        $result = static::runCommand('app:create-user', [
            // pass arguments to the helper
            'username' => 'Wouter',

            // prefix the key with two dashes when passing options,
            // e.g: '--some-option' => 'option_value',
            // use brackets for testing array value,
            // e.g: '--some-option' => ['option_value'],
            // use true for options that accept no value (InputOption::VALUE_NONE),
            // e.g: '--some-option' => true,
        ]);

        $this->assertCommandIsSuccessful($result);

        // you can also check for a failed or invalid command:
        // $this->assertCommandFailed($result);
        // $this->assertCommandIsInvalid($result);

        // the output of the command in the console
        $output = $result->getOutput();
        $this->assertStringContainsString('Username: Wouter', $output);

        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11

// stdout only
$result->getOutput();

// stderr only
$result->getErrorOutput();

// the combined output (stdout + stderr interleaved)
$result->getDisplay();

// the exit code
$result->statusCode;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

namespace App\Service;

use Psr\Log\LoggerInterface;

class DataImporter
{
    public function __construct(
        private LoggerInterface $logger,
    ) {
    }

    public function import(string $file): void
    {
        $this->logger->info('Importing data from '.$file);

        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

namespace App\Command;

use App\Service\DataImporter;
use Symfony\Component\Console\Attribute\Argument;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Logger\ConsoleLogger;
use Symfony\Component\Console\Output\OutputInterface;

#[AsCommand(
    name: 'app:import-data',
    description: 'Imports data from the given file'
)]
class ImportDataCommand
{
    public function __invoke(#[Argument] string $file, OutputInterface $output): int
    {
        $logger = new ConsoleLogger($output);

        $importer = new DataImporter($logger);
        $importer->import($file);

        return Command::SUCCESS;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// src/Command/MyCommand.php
namespace App\Command;

use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\SignalableCommandInterface;

#[AsCommand(name: 'app:my-command')]
class MyCommand implements SignalableCommandInterface
{
    // ...

    public function getSubscribedSignals(): array
    {
        // return here any of the constants defined by PCNTL extension
        return [\SIGINT, \SIGTERM];
    }

    public function handleSignal(int $signal, int|false $previousExitCode = 0): int|false
    {
        if (\SIGINT === $signal) {
            // ...
        }

        // ...

        // return an integer to set the exit code, or
        // false to continue normal execution
        return 0;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// src/Command/LongRunningCommand.php
namespace App\Command;

use Symfony\Component\Console\Application;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Command\SignalableCommandInterface;

#[AsCommand(name: 'app:long-running')]
class LongRunningCommand implements SignalableCommandInterface
{
    public function __invoke(Application $application): int
    {
        // trigger an alarm every 10 seconds
        $application->setAlarmInterval(10);

        // long-running processing...

        return Command::SUCCESS;
    }

    public function getSubscribedSignals(): array
    {
        return [\SIGALRM];
    }

    public function handleSignal(int $signal, int|false $previousExitCode = 0): int|false
    {
        // e.g. ping the database to keep the connection alive

        return false;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// src/EventListener/ConsoleAlarmListener.php
namespace App\EventListener;

use Symfony\Component\Console\Event\ConsoleAlarmEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener]
class ConsoleAlarmListener
{
    public function __invoke(ConsoleAlarmEvent $event): void
    {
        // e.g. ping the database to keep the connection alive

        // keep the command running after handling the alarm
        $event->abortExit();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

#!/usr/bin/env php
<?php
require __DIR__.'/vendor/autoload.php';

use Symfony\Component\Console\Attribute\Argument;
use Symfony\Component\Console\Attribute\Option;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\SingleCommandApplication;

new SingleCommandApplication()
    ->setName('My Super Command') // optional
    ->setVersion('1.0.0') // optional
    ->setCode(function (OutputInterface $output, #[Argument] string $directory = '.', #[Option] string $format = 'txt'): int {
        // output arguments and options

        return Command::SUCCESS;
    })
    ->run();

1
2
3
4
5
6
7
8
9
10
11
12
13
14

#!/usr/bin/env php
<?php

use Symfony\Component\Console\Application;
use Symfony\Component\DependencyInjection\ContainerBuilder;

require __DIR__.'/vendor/autoload.php';

$container = new ContainerBuilder();
// ... register your services, commands, etc.
$container->compile();

$application = new Application('my-cli', '1.0', $container);
$application->run();

1
2
3
4
5
6
7
8
9
10

// src/Kernel.php
namespace App;

use Symfony\Component\DependencyInjection\Kernel\AbstractKernel;
use Symfony\Component\DependencyInjection\Kernel\KernelTrait;

class Kernel extends AbstractKernel
{
    use KernelTrait;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

#!/usr/bin/env php
<?php

use App\Kernel;
use Symfony\Component\Console\Application;

require __DIR__.'/vendor/autoload_runtime.php';

return function (array $context) {
    $kernel = new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
    $kernel->boot();

    return new Application('my-cli', '1.0', $kernel->getContainer());
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// src/Command/CreateUserCommand.php
namespace App\Command;

use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

// the name of the command is what users type after "php bin/console"
#[AsCommand(name: 'app:create-user')]
class CreateUserCommand extends Command
{
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // ... put here the code to create the user
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// src/Command/CreateUserCommand.php

// ...
class CreateUserCommand extends Command
{
    // ...
    protected function configure(): void
    {
        $this
            // the command description shown when running "php bin/console list"
            ->setDescription('Creates a new user.')
            // the command help shown when running the command with the "--help" option
            ->setHelp('This command allows you to create a user...')
            // add an argument required to your command
            ->addArgument('username', InputArgument::REQUIRED, 'How the user should be named?')
        ;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// src/Command/CreateUserCommand.php

// ...
class CreateUserCommand extends Command
{
    // ...

    public function __construct(bool $requirePassword = false)
    {
        // best practices recommend to call the parent constructor first and
        // then set your own properties. That wouldn't work in this case
        // because configure() needs the properties set in this constructor
        $this->requirePassword = $requirePassword;

        parent::__construct();
    }

    protected function configure(): void
    {
        $this
            // ...
            ->addArgument('password', $this->requirePassword ? InputArgument::REQUIRED : InputArgument::OPTIONAL, 'User password')
        ;
    }
}