Versioned API resources — V1 vs V2 transformation

Advanced5 min read·lv-24-005

interview

Concept

Artisan commands are PHP classes registered with Laravel's CLI. php artisan runs them. They're used for maintenance tasks, data migrations, scheduled jobs, development tools, and anything that doesn't belong in the HTTP request cycle.

Creating: php artisan make:command SendWeeklyReport. Generates app/Console/Commands/SendWeeklyReport.php.

$signature: Defines the command name, arguments, and options. Syntax:

'report:weekly' — command name.
{user} — required argument.
{user?} — optional argument.
{user=default} — argument with default.
{--queue} — boolean option (flag).
{--queue=} — option with value.
{--Q|queue=} — option with short alias.
{user*} — variadic argument (array).

$description: One-line description shown in php artisan list.

handle(): int: The main method. Return self::SUCCESS (0), self::FAILURE (1), or self::INVALID (2).

Auto-discovery: Commands in app/Console/Commands/ are auto-discovered. No registration needed in Kernel.php (Laravel 9+).

artisan list: Shows all registered commands. artisan help command:name shows detailed usage.

Code Example

php

<?php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use App\Models\User;

class SendWeeklyReport extends Command
{
    // Signature defines name, arguments, and options
    protected $signature = 'report:weekly
                            {user? : User ID or email (optional — all users if omitted)}
                            {--queue : Run in background via queue}
                            {--format=html : Output format (html or text)}';

    protected $description = 'Send weekly activity reports to users';

    public function handle(): int
    {
        $identifier = $this->argument('user');
        $useQueue   = $this->option('queue');
        $format     = $this->option('format');

        // Get users
        $users = $identifier
            ? User::where('id', $identifier)->orWhere('email', $identifier)->get()
            : User::where('receives_weekly_report', true)->get();

        if ($users->isEmpty()) {
            $this->error('No users found.');
            return self::FAILURE;
        }

        $this->info("Sending reports to {$users->count()} user(s) in {$format} format...");

        $bar = $this->output->createProgressBar($users->count());
        $bar->start();

        foreach ($users as $user) {
            if ($useQueue) {
                \App\Jobs\SendWeeklyReportJob::dispatch($user, $format);
            } else {
                $user->notify(new \App\Notifications\WeeklyReport($format));
            }
            $bar->advance();
        }

        $bar->finish();
        $this->newLine();
        $this->info('Done!');

        return self::SUCCESS;
    }
}

// Usage
// php artisan report:weekly                    — all users
// php artisan report:weekly 42                 — specific user by ID
// php artisan report:weekly alice@example.com  — specific user by email
// php artisan report:weekly --queue            — use queue
// php artisan report:weekly --format=text      — text format
// php artisan report:weekly 42 --queue --format=html  — combined

PreviousConditional attributes — when(), unless()API Resources & Transformations NextCreating Artisan commands — make:command, $signature, $descriptionArtisan & Commands