Yii Console Application

The package is a console only application template that can be used to perform common tasks in a Yii application. If you need classic web or API please start with corresponding templates:

It is based on Yii console runner that is used in the entry command script, ./yii. You are free to adjust any part of this template including the entry command script to suit your needs.

Requirements

PHP 8.1 or higher.

Creating a project

Use Composer to create new project from this template:

composer create-project yiisoft/app-console <your project>

General usage

Console is available as ./yii from the root directory of the application:

$ ./yii

Yii Console 1.0

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
      --config=CONFIG   Set alternative configuration name
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  completion  Dump the shell completion script
  echo        An example command that echoes exactly what it is told to.
  help        Display help for a command
  list        List commands
  serve       Runs PHP built-in web server

Help for specific command could be displayed by adding --help to the command itself:

$ ./yii echo --help

Description:
  An example command that echoes exactly what it is told to.

Usage:
  echo [<sentence>]

Arguments:
  sentence              Sentence to say. [default: "Hello!"]

Options:
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
      --config=CONFIG   Set alternative configuration name
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Using the command is like the following:

$ ./yii echo
You said: Hello!

$ ./yii echo 'Code something'
You said: Code something

Environments

Out of the box, three environments are available:

dev — for development.
prod — for production.
test — for running tests.

Config files for these are in config/environments.

Environment could be chosen by setting YII_ENV:

YII_ENV=prod ./yii

Extra debugging

To enable validation of container and events, set YII_DEBUG environment variable:

YII_DEBUG=1 ./yii

Creating your own command

Commands are placed into src/Command. Let's see how hello command is implemented in src/Command/HelloCommand.php:

namespace App\Command;

use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputDefinition;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Yiisoft\Yii\Console\ExitCode;

#[AsCommand(
    name: 'echo',
    description: 'An example command that echoes exactly what it is told to.'
)]
final class EchoCommand extends Command
{
    private string $sentence = 'sentence';

    protected function configure(): void
    {
        $this->setDefinition(
            new InputDefinition([
                new InputArgument($this->sentence, InputArgument::OPTIONAL, 'Sentence to say.', 'Hello!'),
            ])
        );
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $output->writeln("You said: {$input->getArgument('sentence')}");

        return ExitCode::OK;
    }
}

To register the command, add it to config/commands.php:

use App\Command\EchoCommand;

return [
    'echo' => EchoCommand::class,
];

Info: Yii console is based on Symfony console so for additional usage documentation, please follow Yii console and Symfony console guide.

Events

The application raises ApplicationStartup before and ApplicationShutdown after running a command.

Tests

The template comes with ready to use Codeception configuration. In order to execute tests run:

composer run serve > ./runtime/yii.log 2>&1 &
vendor/bin/codecept run

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

License

The Yii Console Application is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

yiisoft / app-console

readme