Options

Before we cover the rest of the Artisan commands, let’s look at a few notable options you can pass any time you run an Artisan command:

• -q suppresses all output.

• -v, -vv, and -vvv are the three levels of output verbosity (normal, verbose, and debug).

• --no-interaction does not ask any interactive questions, so it won’t interrupt automated processes running it.

• --env allows you to define which environment the Artisan command should operate in (e.g., local, production, etc.).

• --version shows you which version of Laravel your application is running on.

You’ve probably guessed from looking at these options that Artisan commands are intended to be used much like basic shell commands: you might run them manually, but they can also function as a part of some automated process at some point.

For example, there are many automated deploy processes that might benefit from certain Artisan commands. You might want to run php artisan config:cache every time you deploy an application. Flags like -q and --no-interaction ensure that your deploy scripts, not attended by a human being, can keep running smoothly.

The Grouped Commands

The rest of the commands available out of the box are grouped by context. We won’t cover them all here, but we’ll cover each context broadly:

app

This just contains app:name, which allows you to replace every instance of the default top-level App\ namespace with a namespace of your choosing. For example: php artisan app:name MyApplication. I recommend avoiding this feature and keeping your app’s root namespace as “App”.

auth

All we have here is auth:clear-resets, which flushes all of the expired password reset tokens from the database.

cache

cache:clear clears the caches, cache:forget removes an individual item from the cache, and cache:table creates a database migration if you plan to use the database cache driver.

config

config:cache caches your configuration settings for faster lookup; to clear the cache, use config:clear.

db

db:seed seeds your database, if you have configured database seeders.

event

event:generate builds missing event and event listener files based on the definitions in EventServiceProvider. You’ll learn more about events in Chapter 16.

key

key:generate creates a random application encryption key in your .env file.

make

make:auth scaffolds out the views and corresponding routes for a landing page, a user dashboard, and login and register pages.

All the rest of the make: actions create a single item, and have parameters that vary accordingly. To learn more about any individual command’s parameters, use help to read its documentation.

For example, you could run php artisan help make:migration and learn that you can pass --create=tableNameHere to create a migration that already has the create table syntax in the file, as shown here: php artisan make:migration create_posts_table --create=posts.

migrate

You saw a migrate command earlier to run our migrations, but here we can run all the other migration-related commands. Create the migrations table (to keep track of the migrations that are executed) with migrate:install, reset your migrations and start from scratch with migrate:reset, reset your migrations and run them all again with migrate:refresh, roll back just one migration with migrate:rollback, drop all tables and re-run all the migrations with migrate:fresh, or check the status of your migrations with migrate:status.

notifications

notifications:table generates a migration that creates the table for database notifications.

package

In Laravel prior to 5.5 including a new Laravel-specific package in your app requires registering it manually in config/app.php. However, in 5.5 it’s possible for Laravel to “auto-discover” those packages so you don’t have to manually register them. package:discover rebuilds Laravel’s “discovered” manifest of the service providers from your external packages.

queue

We’ll cover Laravel’s queues in Chapter 16, but the basic idea is that you can push jobs up into remote queues to be executed one after another by a worker. This command group provides all the tools you need to interact with your queues, like queue:listen to start listening to a queue, queue:table to create a migration for database-backed queues, and queue:flush to flush all failed queue jobs. There are quite a few more, which you’ll learn about in Chapter 16.

route

If you run route:list, you’ll see the definitions of every route defined in the application, including each route’s verb(s), path, name, controller/closure action, and middleware. You can cache the route definitions for faster lookups with route:cache and clear your cache with route:clear.

schedule

We’ll cover Laravel’s cron-like scheduler in Chapter 16, but in order for it to work, you need to set the system cron to run schedule:run once a minute:

* * * * * php /home/myapp.com/artisan schedule:run >> /dev/null 2>&1

As you can see, this Artisan command is intended to be run regularly in order to power a core Laravel service.

session

session:table creates a migration for applications using database-backed sessions.

storage

storage:link creates a symbolic link from public/storage to storage/app/public. This is a common convention in Laravel apps, to make it easy to put user uploads (or other files that commonly end up in storage/app) somewhere where they’ll be accessible at a public URL.

vendor

Some Laravel-specific packages need to “publish” some of their assets, either so that they can be served from your public directory or so that you can modify them. Either way, these packages register these “publishable assets” with Laravel, and when you run vendor:publish, it publishes them to their specified locations.

view

Laravel’s view rendering engine automatically caches your views. It usually does a good job of handling its own cache invalidation, but if you ever notice it’s gotten stuck, run view:clear to clear the cache.

A Sample Command

We haven’t covered mail or Eloquent yet (see Chapter 15 for mail and Chapter 5 for Eloquent), but the sample handle() method in Example 8-2 should read pretty clearly.

...
class WelcomeNewUsers extends Command
{
    public function handle()
    {
        User::signedUpThisWeek()->each(function ($user) {
            Mail::to($user)->send(new WelcomeEmail);
        });
    }

Now every time you run php artisan email:newusers, this command will grab every user that signed up this week and send them the welcome email.

If you would prefer injecting your mail and user dependencies instead of using facades, you can typehint them in the command constructor, and Laravel’s container will inject them for you when the command is instantiated.

Take a look at Example 8-3 to see what Example 8-2 might look like using dependency injection and extracting its behavior out to a service class.

...
class WelcomeNewUsers extends Command
{
    public function __construct(UserMailer $userMailer)
    {
        parent::__construct();

        $this->userMailer = $userMailer
    }

    public function handle()
    {
        $this->userMailer->welcomeNewUsers();
    }

Arguments and Options

The $signature property of the new command looks like it might just contain the command name. But this property is also where you’ll define any arguments and options for the command. There’s a specific, simple syntax you can use to add arguments and options to your Artisan commands.

Before we dig into that syntax, take a look at an example for some context:

protected $signature = 'password:reset {userId} {--sendEmail}';

password:reset {userId}

password:reset {userId?}

password:reset {userId=1}

password:reset {userId} {--sendEmail}

password:reset {userId} {--password=}

password:reset {userId} {--queue=default}

password:reset {userIds*}

password:reset {--ids=*}

// Argument
php artisan password:reset 1 2 3

// Option
php artisan password:reset --ids=1 --ids=2 --ids=3

protected $signature = 'password:reset
                        {userId : The ID of the user}
                        {--sendEmail : Whether to send user an email}';

Using Input

Now that we’ve prompted for this input, how do we use it in our command’s handle() method? We have two sets of methods for retrieving the values of arguments and options.

// with definition "password:reset {userId}":
php artisan password:reset 5

// $this->arguments() returns this array
[
    "command": "password:reset",
    "userId": "5",
]

// $this->argument('userId') returns this string
"5"

// with definition "password:reset {--userId=}":
php artisan password:reset --userId=5

// $this->options() returns this array
[
    "userId" => "5"
    "help" => false
    "quiet" => false
    "verbose" => false
    "version" => false
    "ansi" => false
    "no-ansi" => false
    "no-interaction" => false
    "env" => null
]

// $this->option('userId') returns this string
"5"

public function handle()
{
    // All arguments, including the command name
    $arguments = $this->arguments();

    // Just the 'userId' argument
    $userid = $this->argument('userId');

    // All options, including some defaults like 'no-interaction' and 'env'
    $options = $this->options();

    // Just the 'sendEmail' option
    $sendEmail = $this->option('sendEmail');
}

Prompts

There are a few more ways to get user input from within your handle() code, and they all involve prompting the user to enter information during the execution of your command:

ask()

Prompts the user to enter freeform text:

$email = $this->ask('What is your email address?');

secret()

Prompts the user to enter freeform text, but hides the typing with asterisks:

$password = $this->secret('What is the DB password?');

confirm()

Prompts the user for a yes/no answer, and returns a boolean:

if ($this->confirm('Do you want to truncate the tables?')) {
    //
}

All answers except y or Y will be treated as a “no.”

anticipate()

Prompts the user to enter freeform text, and provides autocomplete suggestions. Still allows the user to type whatever she wants:

$album = $this->anticipate('What is the best album ever?', [
    "The Joshua Tree", "Pet Sounds", "What's Going On"
]);

choice()

Prompts the user to choose one of the provided options. The last parameter is the default if the user doesn’t choose:

$winner = $this->choice(
    'Who is the best football team?',
    ['Gators', 'Wolverines'],
    0
);

Note that the final parameter, the default, should be the array key. Since we passed a nonassociative array, the key for “Gators” is 0. You could also key your array, if you’d prefer:

$winner = $this->choice(
    'Who is the best football team?',
    ['gators' => 'Gators', 'wolverines' => 'Wolverines'],
    'gators'
);

Output

During the execution of your command, you might want to write messages to the user. The most basic way to do this is to use $this->info() to output basic green text:

$this->info('Your command has run successfully.');

You also have available the comment() (orange), question() (highlighted teal), error() (highlighted red), and line() (uncolored) methods to echo to the command line.

Please note that the exact colors may vary from machine to machine, but they try to be in line with the local machine’s standards for communicating to the end user.

$headers = ['Name', 'Email'];

$data = [
    ['Dhriti', 'dhriti@amrit.com'],
    ['Moses', 'moses@gutierez.com'],
];

// Or, you could get similar data from the database:
$data = App\User::all(['name', 'email'])->toArray();

$this->table($headers, $data);

+---------+--------------------+
| Name    | Email              |
+---------+--------------------+
| Dhriti  | dhriti@amrit.com   |
| Moses   | moses@gutierez.com |
+---------+--------------------+

$totalUnits = 10;
$this->output->progressStart($totalUnits);

for ($i = 0; $i < $totalUnits; $i++) {
    sleep(1);

    $this->output->progressAdvance();
}

$this->output->progressFinish();

Writing Closure-Based Commands

If you’d prefer to keep your command definition process simpler, you can write commands as closures instead of classes by defining them in routes/console.php. Everything we discuss in this chapter will apply the same way, but you will just define and register the commands in a single step in that file:

// routes/console.php
Artisan::command(
    'password:reset {userId} {--sendEmail}',
    function ($userId, $sendEmail) {
        $userId = $this->argument('userId');
        // do something...
    }
);