Task arguments

When creating a function that will be used as a task, all the parameters of the function will be used as arguments or options:

use Castor\Attribute\AsTask;

use function Castor\io;

#[AsTask()]
function simple(string $firstArg, string $secondArg): void
{
    io()->writeln($firstArg . ' ' . $secondArg);
}

Which can be called like that:

$ castor simple foo bar
foo bar

Optional arguments

You can make an argument optional by giving it a default value:

use Castor\Attribute\AsTask;

use function Castor\io;

#[AsTask()]
function optional(string $firstArg, string $secondArg = 'default'): void
{
    io()->writeln($firstArg . ' ' . $secondArg);
}

$ castor optional foo
foo default
$ castor optional foo --second-arg=bar
foo bar

Arguments without configuration nor validation

By default, Castor will validate the arguments and options provided to a task. Thus it will emit an error if an unknown argument or option is provided or if an required argument is missing:

$ castor simple foo --unknown-option value

  The "--unknown-option" option does not exist.  

If you want to disable this validation for a specific task, you can use the ignoreValidationErrors flag:

use Castor\Attribute\AsTask;

#[AsTask(ignoreValidationErrors: true)]
function no_validation(): void
{
}

Castor will not emit validation errors for unknown arguments or options when running this task:

castor no-validation --unknown-option value

But instead of simply disabling validation, you may also want to capture the raw arguments provided to the task and pass them to a sub process. You can do so by using the #[AsRawTokens]() attribute instead:

use Castor\Attribute\AsRawTokens;
use Castor\Attribute\AsTask;

use function Castor\run;

#[AsTask()]
function phpunit(#[AsRawTokens] array $rawTokens): void
{
    run(['vendor/bin/simple-phpunit', ...$rawTokens]);
}

Then, you can use it like that:

castor phpunit --filter=testName --debug --verbose

Overriding the argument name and description

You can override the name and description of an argument by using the #[Castor\Attribute\AsArgument()] attribute:

use Castor\Attribute\AsArgument;
use Castor\Attribute\AsTask;

use function Castor\io;

#[AsTask()]
function override_argument(
    #[AsArgument(name: 'foo', description: 'This is the foo argument')]
    string $arg = 'bar',
): void {
    io()->writeln($arg);
}

$ castor override-argument --help
Usage:
  arguments:override-argument [<foo>]

Arguments:
  foo                         This is the foo argument [default: "bar"]

Overriding the option name and description

If you prefer, you can force an argument to be an option by using the #[Castor\Attribute\AsOption()] attribute:

use Castor\Attribute\AsOption;
use Castor\Attribute\AsTask;

use function Castor\io;

#[AsTask()]
function override_option(
    #[AsOption(name: 'foo', description: 'This is the foo option')]
    string $arg = 'bar',
): void {
    io()->writeln($arg);
}

$ castor override-option --help
Usage:
  arguments:override-option [options]

Options:
      --foo[=FOO]           This is the foo option [default: "bar"]

$ castor override-option --foo=foo
foo

You can also configure the mode of the option. The mode determines how the option will be registered (no value expected, required, optional, negatable, etc):

use Castor\Attribute\AsOption;
use Castor\Attribute\AsTask;
use Symfony\Component\Console\Input\InputOption;

use function Castor\io;

#[AsTask()]
function option_mode(
    #[AsOption(description: 'This is the foo option', mode: InputOption::VALUE_NONE)]
    bool $force,
): void {
    if ($force) {
        io()->writeln('Command has been forced.');
    }
}

$ castor option-mode --force
Command has been forced.

Please refer to the Symfony documentation for more information about option modes.

Path arguments and options

In some cases, you may want the user to provide a path in an argument or an option. In order to ease the use of paths for users, Castor provides the #[AsPathArgument()] and #[AsPathOption()] attributes alternatives to #[AsArgument()] and #[AsOption]().

When using #[AsPathArgument()] or #[AsPathOption()], the argument or option will be autocompleted with suggestions of paths.

use Castor\Attribute\AsPathArgument;
use Castor\Attribute\AsTask;

#[AsTask()]
function path_argument(#[AsPathArgument()] string $argument): void
{
}

$ castor path-argument /var/www/[TAB]
/var/www/foo  /var/www/bar  /var/www/baz

See the autocompletion documentation for more information about completion.