yiisoft/app-console

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:

• Classic web application template
• API application template

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>

Remove line "/composer.lock" from /.gitignore file to keep composer.lock in your repository.

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.

Support the project

Follow updates