:purple_heart: Support me

Visit my blog on https://bitbench.dev or follow me on Social Media Twitter @bitbench Instagram @bitbench.dev

:package: Installation

You can install the package via composer:

composer require thettler/laravel-console-toolkit

:wrench: Usage

:right_anger_bubble: Before you use this package you should already have an understanding of Artisan Commands. You can read about them here.

A Basic Command

To use the Toolkit you simply need to add the UsesConsoleToolkit trait inside your command.

Then add the Thettler\LaravelConsoleToolkit\Attributes\ArtisanCommand to the class to specify the name and other things like description, help, and so on.

The ArtisanCommand requires the name parameter to be set. This will be the name of the Command which you can use to call it from the commandline.

<?php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Thettler\LaravelConsoleToolkit\Concerns\UsesConsoleToolkit;

#[ArtisanCommand(
    name: 'basic',
)]
class BasicCommand extends Command
{
    use UsesConsoleToolkit;
    
    public function handle()
    {
    }
}

And call it like:

php artisan basic

    
<?php
namespace App\Console\Commands;

use Illuminate\Console\Command;

class BasicCommand extends Command
{
    protected $signature = 'basic';

    public function handle()
    {
    }
}

Descriptions, Help and Hidden Commands

If you want to add a description, a help comment or mark the command as hidden, you can specify this on the ArtisanCommand Attribute like this:

#[ArtisanCommand(
    name: 'basic',
    description: 'Some useful description.',
    help: 'Some helpful text.',
    hidden: true
)]
class BasicCommand extends Command
{
    use UsesConsoleToolkit;

    ...
}

I like to use named arguments for a more readable look.

...
class BasicCommand extends Command
{
    protected $signature = 'basic';

    protected $description = 'Some useful description.';

    protected $help = 'Some helpful text.';
    
    protected $hidden = true;
    ...
}

Defining Input Expectations

The basic workflow to add an argument or option is always to add a property and decorate it with an Attribute. #[Option] if you want an option and #[Argument] if you want an argument. The property will be hydrated with the value from the command line, so you can use it like any normal property inside your handle() method.

More about that in the following sections. :arrow_down:

:exclamation: The property will only be hydrated inside the handle() method. Keep that in mind.

Arguments

To define Arguments you create a property and add the Argument attribute to it. The property will be hydrated with the value from the command line, so you can use it like any normal property inside your handle() method.

...
use \Thettler\LaravelConsoleToolkit\Attributes\Argument;

#[ArtisanCommand(
    name: 'basic',
)]
class BasicCommand extends Command
{
    use UsesConsoleToolkit;

    #[Argument]
    protected string $myArgument;
    
    public function handle() {
        $this->line($this->myArgument);
    }
}

call it like:

php artisan basic myValue
# Output:
# myValue

class BasicCommand extends Command
{
    protected $signature = 'basic {myArgument}';
    
    public function handle() {
        $this->line($this->argument('myArgument'));
    }
}

Array Arguments

You can also use arrays in arguments, simply typehint the property as array.

#[ArtisanCommand(
    name: 'basic',
)]
class BasicCommand extends Command
{
    use UsesConsoleToolkit;

    #[Argument]
    protected array $myArray;
    
    public function handle() {
        $this->line(implode(', ', $this->myArray));
    }
}

Call it like:

php artisan basic Item1 Item2 Item3 
# Output
# Item1, Item2, Item3 

class BasicCommand extends Command
{
    protected $signature = 'basic {myArgument*}';
    
    public function handle() {
        $this->line($this->argument('myArgument'));
    }
}

Optional Arguments

Of course, you can use optional arguments as well. To achieve this you simply make the property nullable.

:information_source: This works with array as well but the property won't be null but an empty array instead

#[ArtisanCommand(
    name: 'basic',
)]
class BasicCommand extends Command
{
    use UsesConsoleToolkit;

    #[Argument]
    protected ?string $myArgument;
    
    ...
}

class BasicCommand extends Command
{
    protected $signature = 'basic {myArgument?}';
    
    ...
}

If your argument should have a default value, you can assign a value to the property which will be used as default value.

#[ArtisanCommand(
    name: 'basic',
)]
class BasicCommand extends Command
{
    use UsesConsoleToolkit;

    #[Argument]
    protected string $myArgument = 'default';
    
    ...
}

class BasicCommand extends Command
{
    protected $signature = 'basic {myArgument=default}';
    
    ...
}

Argument Description

You can set a description for arguments as parameter on the Argument Attribute.

#[ArtisanCommand(
    name: 'basic',
)]
class BasicCommand extends Command
{
    use UsesConsoleToolkit;

    #[Argument(
        description: 'Argument Description'
    )]
    protected string $myArgument;
    
    ...
}

...
class BasicCommand extends Command
{
    protected $signature = 'basic {myArgument: Argument Description}';
    
    ...
}

:exclamation: :exclamation: If you have more than one argument the order inside the class will also be the order on the commandline

Options

To use options in your commands you use the Options Attribute. If you have set a typehint of boolean it will be false if the option was not set and true if it was set.

use \Thettler\LaravelConsoleToolkit\Attributes\Option;

#[ArtisanCommand(
    name: 'basic',
)]
class BasicCommand extends Command
{
    use UsesConsoleToolkit;

    #[Option]
    protected bool $myOption;
    
    public function handle() {
        dump($this->myOption);
    }
}

Call it like:

php artisan basic --myOption
# Output
# true

php artisan basic
# Output
# false

class BasicCommand extends Command
{
    protected $signature = 'basic {--myOption}';
    
    public function handle() {
        dump($this->option('myOption'));
    }
}

Value Options

You can add a value to an option if you type hint the property with something different as bool. This will automatically make it to an option with a value. If your typehint is not nullable the option will have a required value. This means the option can only be used with a value.

:x: Wont work --myoption :white_check_mark: works --myoption=myvalue

If you want to make the value optional simply make the type nullable or assign a value to the property

#[ArtisanCommand(
    name: 'basic',
)]
class BasicCommand extends Command
{
    use UsesConsoleToolkit;

    #[Option]
    protected string $requiredValue; // if the option is used the User must specify a value  
    
    #[Option]
    protected ?string $optionalValue; // The value is optional

    #[Option]
    protected string $defaultValue = 'default'; // The option has a default value

    #[Option]
    protected array $array; // an Array Option 

    #[Option]
    protected array $defaultArray = ['default1', 'default2']; // an Array Option with default
    ...
}

Call it like:

php artisan basic --requiredValue=someValue --optionalValue --array=Item1 --array=Item2

class BasicCommand extends Command
{
    // requiredValue is not possible
    // defaultArray is not possible
    protected $signature = 'basic {--optionalValue=} {--defaultValue=default} {--array=*}';
   
   ...
}

Option Description

You can set a description for an option on the Option Attribute.

#[ArtisanCommand(
    name: 'basic',
)]
class BasicCommand extends Command
{
    use UsesConsoleToolkit;

    #[Option(
        description: 'Option Description'
    )]
    protected bool $option;
    ..