How to Create Laravel Artisan Commands & Pass Arguments to Them

John on March 19, 2021

In this tutorial, we will learn how to create Laravel Artisan commands and configure them to require arguments.

Generating a Command

To generate a new command, use the make:artisan command. Pass the name of the class to create as the first argument.

php artisan make:command addItemsToCat

A new class with the name you used will now be in the Laravel app/Console/Commands directory. Open it.

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class addItemsToCat extends Command
{
   /**
    * The name and signature of the console command.
    *
    * @var string
    */
   protected $signature = 'command:name';

   /**
    * The console command description.
    *
    * @var string
    */
   protected $description = 'Command description';

   /**
    * Create a new command instance.
    *
    * @return void
    */
   public function __construct()
   {
       parent::__construct();
   }

   /**
    * Execute the console command.
    *
    * @return mixed
    */
   public function handle()
   {
       //
   }
}

The signature variable is the name of your command and the handle() function is the code that will execute when the command is run from the command line.

Configuring the Command

To configure your command, edit the $signature and $description values. The $signature should be an appropriate name for your command - the left-hand side of the : (colon) is the category of the command and the right is the exact function of the command.

protected $signature = 'add:itemstocat';

protected $description = 'Add items to a category by a keyword';

Adding Required Arguments

To add required arguments to the command, put them in the $signature value as a space-separated list with the name of the argument inside {} (curly braces).

protected $signature = 'add:itemstocat {keyword} {category_id}';

Adding a Confirmation to an Artisan Command

If your command is doing something critical, you may want to add a confirmation dialogue. This is done using the $this->confirm() constructor method and passing the confirmation message as the first argument. It will return true or false, so wrap the code to execute inside an if statement.

 public function handle()
 {
     if ($this->confirm('This will run the command code continue?')) {
         // Do something here.
     }
 }

Full Artisan Command Example

This is a full example of an Artisan command, which adds items to a category based on a key phrase contained in the title or description of the item. The first argument is the keyword and the second is the category ID.

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use App\Item;
use App\Category;

class addItemsToCat extends Command
{
   /**
    * The name and signature of the console command.
    *
    * @var string
    */
   protected $signature = 'add:itemstocat {keyword} {category_id}';

   /**
    * The console command description.
    *
    * @var string
    */
   protected $description = 'Add items to a category by a keyword';

   /**
    * Create a new command instance.
    *
    * @return void
    */
   public function __construct()
   {
       parent::__construct();
   }

   /**
    * Execute the console command.
    *
    * @return mixed
    */
   public function handle()
   {
       $keyword = $this->argument('keyword');
       $cat_id = $this->argument('category_id');

       $category = Category::where('id', $cat_id)->first();

       if ($this->confirm('This will add all items with the phrase "'.$keyword.'" to the category "'.$category->name.'", continue?')) {
           
           $items = Item::where('name', 'LIKE', '%'. $keyword .'%')->orWhere('content', 'LIKE', '%'. $keyword .'%')->where('status',1)->get();

           foreach ($items as $k => $i) {

               $item = Item::where('id',$i->id)->whereDoesntHave('category', function($query) use ($cat_id) {
                     $query->where('category.id', $cat_id)->where('status',1);
                   })->first();

               if (!is_null($item)) {
                   $this->info($item->id .' added.');
                   $item->category()->attach($category);
               }
           }
       }
   }
}

Running the Artisan Command

To run your artisan command, cd to the root of your application and type the following, replacing the command name with yours:

php artisan add:itemstocat