COMMAND.md

Command provides a declarative way to create console commands by extending it from Symfony Console:

// src/Commands/GreetCommand.php

namespace Acme\Commands;

use Rougin\Blueprint\Command;

class GreetCommand extends Command
{
    protected $name = 'greet';

    protected $description = 'Greets the user';

    public function run()
    {
        $this->showText('Hello, World!');

        return self::RETURN_SUCCESS;
    }
}

$ vendor/bin/blueprint test

Hello, World!

Basic structure

Its structure is defined by the following properties and methods:

/**
 * The name of the command.
 *
 * @var string
 */
protected $name;

/**
 * A short description of what the command does.
 *
 * @var string|null
 */
protected $description = null;

/**
 * Configures the current command with arguments and options.
 *
 * @return void
 */
public function init()

/**
 * Executes the command.
 *
 * @return integer
 */
public function run()

Using arguments

Arguments can be defined in the init method. Its values are retrieved in run method using getArgument:

// src/Commands/GreetCommand.php

namespace Acme\Commands;

use Rougin\Blueprint\Command;

class GreetCommand extends Command
{
    protected $name = 'greet';

    // ...

    public function init()
    {
        $this->addArgument('name', 'Name of user');
    }

    public function run()
    {
        $name = $this->getArgument('name');

        $this->showText('Hello, ' . $name '!');

        // ...
    }
}

$ vendor/bin/blueprint greet "Bluey"

Hello, Bluey!

Below are the available methods related to arguments:

/**
 * Adds an argument.
 *
 * @param string     $name
 * @param string     $description
 * @param mixed|null $default
 * @param integer    $mode
 *
 * @return self
 */
protected function addArgument($name, $description, $default = null, $mode = self::INPUT_REQUIRED)

/**
 * Adds an optional argument.
 *
 * @param string     $name
 * @param string     $description
 * @param mixed|null $default
 *
 * @return self
 */
protected function addOptionalArgument($name, $description, $default = null)

/**
 * Adds a required argument as an array.
 *
 * @param string     $name
 * @param string     $description
 * @param mixed|null $default
 *
 * @return self
 */
protected function addArrayArgument($name, $description, $default = null)

/**
 * Adds an optional argument as an array.
 *
 * @param string     $name
 * @param string     $description
 * @param mixed|null $default
 *
 * @return self
 */
protected function addOptionalArrayArgument($name, $description, $default = null)
{
    return $this->addArgument($name, $description, $default, self::INPUT_OPTIONAL | self::INPUT_IS_ARRAY);
}

Using options

Options (flags) can also be defined in the init method and can be retrieved with getOption:

// src/Commands/GreetCommand.php

namespace Acme\Commands;

use Rougin\Blueprint\Command;

class GreetCommand extends Command
{
    protected $name = 'greet';

    // ...

    public function init()
    {
        // ...

        $this->addValueOption('age', 'Age of user', 23);
    }

    public function run()
    {
        // ...

        $age = $this->getOption('age');

        $this->showText('Your age is ' . $age);

        // ...
    }
}

$ vendor/bin/blueprint greet "Bluey" --age=30

Hello, Bluey!
Your age is 30

Below are the available methods for adding options:

/**
 * Adds an option.
 *
 * @param string      $name
 * @param string      $description
 * @param mixed|null  $default
 * @param string|null $shortcut
 * @param integer     $mode
 *
 * @return self
 */
protected function addOption($name, $description, $default = null, $shortcut = null, $mode = self::VALUE_NONE)

/**
 * Adds an option with a value (e.g., --yell or --yell=loud).
 *
 * @param string      $name
 * @param string      $description
 * @param mixed|null  $default
 * @param string|null $shortcut
 *
 * @return self
 */
protected function addValueOption($name, $description, $default = null, $shortcut = null)

/**
 * Adds a required option with a value (e.g., --yell or --yell=loud).
 *
 * @param string      $name
 * @param string      $description
 * @param mixed|null  $default
 * @param string|null $shortcut
 *
 * @return self
 */
protected function addRequiredOption($name, $description, $default = null, $shortcut = null)

/**
 * Adds an option with a value as an array.
 *
 * @param string      $name
 * @param string      $description
 * @param mixed|null  $default
 * @param string|null $shortcut
 *
 * @return self
 */
protected function addValueArrayOption($name, $description, $default = null, $shortcut = null)

/**
 * Adds a negatable option (e.g., --yell and --no-yell).
 *
 * @param string      $name
 * @param string      $description
 * @param string|null $shortcut
 *
 * @return self
 */
protected function addNegatableOption($name, $description, $shortcut = null)

Handling input, output

Argument and option values can be accessed in run method using getArgument and getOption:

/**
 * Returns the value for the specified argument.
 *
 * @param string $name
 *
 * @return mixed
 */
protected function getArgument($name)

/**
 * Returns the value for the specified option.
 *
 * @param string $name
 *
 * @return mixed
 */
protected function getOption($name)

While styled output is written using the following methods:

/**
 * Writes a text to the console.
 *
 * @param string       $text
 * @param integer|null $type
 *
 * @return mixed
 */
protected function showText($text, $type = null)

/**
 * Shows a text with "[PASS]" prefix.
 *
 * @param string $text
 *
 * @return mixed
 */
protected function showPass($text)

/**
 * Shows a text with "[FAIL]" prefix.
 *
 * @param string $text
 *
 * @return mixed
 */
protected function showFail($text)

/**
 * Shows a text with "[INFO]" prefix.
 *
 * @param string $text
 *
 * @return mixed
 */
protected function showInfo($text)

/**
 * Shows a text with "[WARN]" prefix.
 *
 * @param string $text
 *
 * @return mixed
 */
protected function showWarn($text)

Running commands

Other commands can be ran using runCommand method:

$config = array('arg' => 'value', '--option' => true);

$this->runCommand('other:command', $config);

Dependency injection

If a PSR-11 container is used, dependencies are automatically injected into the command's __construct method:

// src/Commands/GreetCommand.php

namespace Acme\Commands;

use Acme\Services\MyService;
use Rougin\Blueprint\Command;

class GreetCommand extends Command
{
    // ...

    public function __construct(MyService $service)
    {
        $this->service = $service;
    }

    public function run()
    {
        // ...
    }
}