How to create a custom artisan command in Laravel

Laravel is a full-stack framework that offers a lot of artisan commands to automate various actions, like creating a controller, seeding the database, and starting the server. However, when you build custom solutions, you have your own special needs, which could include a new command. Laravel doesn’t limit you to only its commands; you can create your own in a few steps.

Here are the steps for how to create a new artisan command.

Step 1: Create a new Laravel application

laravel new custom

Step 2: Create a command

Use the make:command command to create a new command. Simply pass in the command name, like so:

php artisan make:command CheckUsers

In this example, we’re creating a command called CheckUsers.

The command creates a file named CheckUsers.php, named after the command name, in a newly created Commands directory in the Console folder.

The generated file contains the configurations of the newly created command that are easy to understand and edit.

Step 3: Customize command

First, set the command signature. This is what would be put after php artisan to run the command. In this example, we will use check:users, so the command will be accessible by running:

php artisan check:users

To do this, update the ＄signature property of the command, like this:

protected $signature = 'check:users';

Next, set up a suitable description that would show up when php artisan list displays the command with other commands.

To do this, update the ＄description property to match this:

protected $description = 'Get count of users on the platform';

Finally, in the handle() method, perform whatever action you intend it to perform. In this example, the number of users on the platform is echoed.

public function handle()
{
    echo User::count() . "\n";
}

Step 4: Test command

In the terminal, run the command to see the number of users in your database.

php artisan check:users

Passing arguments to the command

You could have a command that needs an argument to the function. For example, a command to clear all of a specific user’s posts from the database would require the user’s id.

To add an argument, update the ＄signature string and add the argument in curly braces.

protected $signature = 'remove:posts {userId}';

This command would then be called where the id of a user is 5:

php artisan remove:posts 5

At other times, you want to be able to pass in an argument, but not always, so you can make the argument optional by appending a question mark at the end, as follows:

protected $signature = 'remove:posts {userId?}';

You may also set a default value for an argument like so:

protected $signature = 'remove:posts {userId=6}';

You may also pass in multiple arguments and make them optional or with default values as you wish.

protected $signature = 'remove:posts{userId} {$userAge?} {$userStatus=alive}'

These arguments can be accessed using:

$this->arguments()

This returns an associative array with arguments as key and their values as values. So to access the userId argument, you can get it like this:

$user_id = $this->arguments()['userId'];

However, there’s another way to get only one argument:

$user_id = $this->argument('userId');

Passing options to the command

The command may also receive options. Options are like arguments, and they are used to add more information to the command. They can be used with no arguments.

For example, to get the count of only users with verified emails, you may pass in a --verified option to the command. To create an option, pass it into the ＄signature property like the argument, but prefix it with --.

protected $signature = 'check:users {--verified}';

Now, the command may be used with an option like this:

php artisan check:users --verified

You may set a default value for an option or set it to require a value.

protected $signature = 'check:users {--verified} {--add=} {--delete=5}';

In this example, add requires a value to be used and delete has a default value of 5. verified is assigned a Boolean value depending on whether it is passed in.

The value of these options can be accessed easily using ＄this->option('verified') for the single ones and ＄this->options() to get all options as an associative array.

Describing input parameters

So far, we’ve learned how to accept arguments and even options, but when the command is used with php artisan help, these inputs have no description. To set these, simply add a colon, :, after the argument or option name.

protected $signature = '
        check:users
        {userId: Id of user to be fetched}
        {--verified: Gets count of verified users}
    ';

Now, when php artisan --help check:users is run, you should see something like this: