Writing Custom Laravel Artisan Commands: An Introduction

It is often very useful to create custom Artisan commands specifically for your application or package. Custom commands are, by default, stored in the app/Console/Commands directory (commands can be stored at any path that can be autoloaded based on the applications composer.json settings).

The app/Console/Commands directory contains an Inspire command by default (stored in the app/Console/Commands/Inspire.php file). This command is extremely simple and just displays one of the following messages at random:

1When there is no desire, all things are at peace. - Laozi
2Simplicity is the ultimate sophistication. - Leonardo da Vinci
3Simplicity is the essence of happiness. - Cedric Bledsoe
4Smile, breathe, and go slowly. - Thich Nhat Hanh
5Simplicity is an acquired taste. - Katharine Gerould
6Well begun is half done. - Aristotle
7He who is contented is rich. - Laozi
8Very little is needed to make a happy life. - Marcus Antoninus

These quotes are stored in the vendor/laravel/framework/src/Illuminate/Foundation/Inspiring.php class. The Inspire example commands ships as part of the Laravel framework and its definition can be found in the routes/console.php file.

The Inspire command is very short and readable (as it is defined in the routes/console.php file):

1<?php
2 
3Artisan::command('inspire', function () {
4    $this->comment(Inspiring::quote());
5});

Re-implementing this command as a class, as opposed to using the console.php file approach, might look something like this (stored within the app/Console/Commands/ directory):

 1<?php
 2 
 3namespace App\Console\Commands;
 4 
 5use Illuminate\Console\Command;
 6use Illuminate\Foundation\Inspiring;
 7 
 8class Inspire extends Command
 9{
10    /**
11     * The name and signature of the console command.
12     *
13     * @var string
14     */
15    protected $signature = 'inspire';
16 
17    /**
18     * The console command description.
19     *
20     * @var string
21     */
22    protected $description = 'Display an inspiring quote';
23 
24    /**
25     * Execute the console command.
26     *
27     * @return mixed
28     */
29    public function handle()
30    {
31        $this->comment(PHP_EOL.Inspiring::quote().PHP_EOL);
32    }
33}

It is this class-based implementation of the Inspiring command that will be used throughout the remainder of this section.

Commands, at their most basic, contain a $signature, $description and a handle() method. A commands signature is similar to a method or function signature in that it defines the name, parameters and options of the command. The description is simply a helpful description of what the command does. The handle() method implementation is the code that actually performs the action described in the commands description. The Inspire command can be executed like so:

1php artisan inspire

After the command has executed it would display one of the random quotes listed above.

It is entirely possible that when attempting to execute the inspire command the following error will be displayed instead of a random quote:

1[Symfony\Component\Console\Exception\CommandNotFoundException]
2  Command "inspire" is not defined.

This error is caused when the application cannot locate a command. The most common cause of this is that the command has not been included in the applications console commands. Another article, The Laravel Application Console Kernel, discusses this in further detail.

∎