Console Artisan - Knowledge of Laravel

Che cos’è Artisan

Artisan è lo strumento a riga di comando (CLI) incluso in Laravel. Esiste come script artisan nella radice del progetto e fornisce numerosi comandi che rendono più efficienti sviluppo e operatività. Per vedere l’elenco dei comandi disponibili usa il comando list.

php artisan list

Per vedere come usare un comando, aggiungi help davanti.

php artisan help migrate

Se usi Laravel Sail, al posto di php artisan usa sail artisan. I comandi vengono eseguiti dentro il container Docker.

./vendor/bin/sail artisan list

Tinker

Laravel Tinker è un ambiente REPL che ti permette di interagire da riga di comando con l’intera applicazione: modelli Eloquent, job, eventi ecc.

php artisan tinker

Una volta avviato puoi eseguire direttamente codice PHP.

// recupera un utente e ispezionalo
>>> App\Models\User::find(1)
// crea un record tramite factory
>>> App\Models\User::factory()->create()
// invoca direttamente una classe di servizio
>>> app(App\Services\OrderService::class)->process(1)

Tinker modifica realmente i dati. Fai molta attenzione se lo esegui in produzione. È adatto a verifica del comportamento e debugging in ambienti locali o di staging.

Creare comandi personalizzati

Generare un comando

Con make:command generi lo scheletro di una classe comando.

php artisan make:command ImportProducts

Viene generato app/Console/Commands/ImportProducts.php.

Struttura di base del comando

La classe comando generata ha tre elementi principali: $signature, $description e handle().

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class ImportProducts extends Command
{
    /**
     * Definizione del nome del comando, degli argomenti e delle opzioni
     */
    protected $signature = 'import:products';

    /**
     * Descrizione del comando (mostrata in php artisan list)
     */
    protected $description = 'Importa dati prodotto da CSV';

    /**
     * Logica di esecuzione del comando
     */
    public function handle(): void
    {
        $this->info('Avvio dell\'importazione...');
        // scrivi qui la logica
        $this->info('Completato.');
    }
}

In Laravel 13 è disponibile anche la sintassi con attributi PHP.

use Illuminate\Console\Attributes\Description;
use Illuminate\Console\Attributes\Signature;

#[Signature('import:products')]
#[Description('Importa dati prodotto da CSV')]
class ImportProducts extends Command
{
    public function handle(): void
    {
        // ...
    }
}

Definire argomenti e opzioni

In $signature definisci in un solo posto nome del comando, argomenti e opzioni.

protected $signature = 'import:products
                        {file : path del file CSV da importare}
                        {--limit= : numero massimo di record da importare}
                        {--dry-run : non salva realmente sul DB (verifica)}';

Sintassi	Tipo	Descrizione
`{file}`	Argomento obbligatorio	Se omesso genera errore
`{file?}`	Argomento opzionale	Se omesso vale `null`
`{file=products.csv}`	Argomento con default	Se omesso usa il valore di default
`{--queue}`	Opzione flag	Se presente `true`, altrimenti `false`
`{--limit=}`	Opzione con valore	Passi il valore come `--limit=100`
`{--limit=50}`	Opzione con default	Se omessa vale `50`
`{--Q\|queue}`	Con scorciatoia	Può essere indicata anche come `-Q`

Ottenere argomenti e opzioni

Dentro handle() recupera i valori con argument() e option().

public function handle(): void
{
    $file    = $this->argument('file');       // legge l'argomento
    $limit   = $this->option('limit');        // legge l'opzione
    $dryRun  = $this->option('dry-run');      // opzione flag (bool)

    $this->info("File: {$file}");

    if ($dryRun) {
        $this->warn('Modalità dry-run: il salvataggio sul DB verrà saltato');
    }
}

`input()` — accessor tipizzati

Con il metodo input() puoi accedere ad argomenti e opzioni del comando tramite accessor tipizzati come quelli delle richieste HTTP.

use App\Enums\ReportType;

public function handle(): void
{
    // argomenti e opzioni disponibili come istanza CommandInput
    $from = $this->input()->date('from');
    $type = $this->input()->enum('type', ReportType::class);
    $limit = $this->input()->integer('limit');
}

Se vuoi ottenere solo un nome specifico, passalo direttamente (viene cercato sia tra gli argomenti sia tra le opzioni).

$queue = $this->input('queue', 'default');

Mentre argument() e option() restituiscono stringhe, gli accessor tipizzati di input() convertono al tipo appropriato. Molto comodi quando vuoi gestire in modo type-safe date, numeri, enum ecc.

Interazione con l’utente

Stampare messaggi

Ci sono metodi dedicati per stampare messaggi colorati sulla console.

$this->info('Operazione completata correttamente');    // verde
$this->warn('Questa operazione non è annullabile');    // giallo
$this->error('Si è verificato un errore');             // rosso
$this->line('Testo normale');                          // senza colore
$this->comment('Informazione aggiuntiva');             // grigio chiaro

Chiedere all’utente

Puoi accettare input interattivo dall’utente.

// input testuale
$name = $this->ask('Inserisci il nome del responsabile');

// con valore di default
$env = $this->ask('Seleziona l\'ambiente di esecuzione', 'production');

// informazioni riservate come password (l'input non appare a schermo)
$password = $this->secret('Inserisci la API key');

// conferma sì/no
if (! $this->confirm('Vuoi importare nel DB di produzione?')) {
    $this->info('Annullato.');
    return;
}

// scelta tra opzioni
$format = $this->choice('Scegli il formato di output', ['csv', 'json', 'xml'], 0);

Barra di avanzamento

Puoi mostrare in modo chiaro l’avanzamento durante l’elaborazione di grandi quantità di dati.

use App\Models\Product;

// passando semplicemente una collection viene mostrata automaticamente la progress bar
$this->withProgressBar(Product::cursor(), function (Product $product) {
    $this->processProduct($product);
});

Per un controllo manuale più fine:

$total = Product::count();
$bar = $this->output->createProgressBar($total);
$bar->start();

Product::cursor()->each(function (Product $product) use ($bar) {
    $this->processProduct($product);
    $bar->advance();
});

$bar->finish();
$this->newLine();

Casi d’uso pratici

Comando di importazione dati

Esempio pratico di un comando che importa dati prodotto da un file CSV.

Genera il comando

php artisan make:command ImportProducts

Implementa il comando

<?php

namespace App\Console\Commands;

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

class ImportProducts extends Command
{
    protected $signature = 'import:products
                            {file : path del file CSV}
                            {--limit= : numero massimo di record da importare}
                            {--dry-run : solo verifica (non salva sul DB)}';

    protected $description = 'Importa dati prodotto da un file CSV';

    public function handle(): void
    {
        $filePath = $this->argument('file');
        $limit    = $this->option('limit') ? (int) $this->option('limit') : null;
        $dryRun   = $this->option('dry-run');

        if (! file_exists($filePath)) {
            $this->error("File non trovato: {$filePath}");
            return;
        }

        // carica il CSV con le funzioni PHP built-in
        $handle = fopen($filePath, 'r');
        $headers = fgetcsv($handle); // prima riga come header
        $rows = [];
        while (($row = fgetcsv($handle)) !== false) {
            $rows[] = array_combine($headers, $row);
            if ($limit !== null && count($rows) >= $limit) {
                break;
            }
        }
        fclose($handle);

        $count = 0;

        $this->withProgressBar($rows, function (array $row) use ($dryRun, &$count) {
            if (! $dryRun) {
                Product::updateOrCreate(
                    ['sku' => $row['sku']],
                    [
                        'name'  => $row['name'],
                        'price' => $row['price'],
                    ]
                );
            }
            $count++;
        });

        $this->newLine();

        if ($dryRun) {
            $this->warn("{$count} record interessati (dry-run: salvataggio saltato)");
        } else {
            $this->info("Importazione completata: {$count} record.");
        }
    }
}

Esegui il comando

# importazione normale
php artisan import:products storage/products.csv

# limita il numero di record
php artisan import:products storage/products.csv --limit=100

# verifica in dry-run
php artisan import:products storage/products.csv --dry-run

Comando di manutenzione periodica

Esempio di un comando di manutenzione periodica, come la cancellazione di dati vecchi.

<?php

namespace App\Console\Commands;

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

class PruneOldOrders extends Command
{
    protected $signature = 'orders:prune {--days=90 : elimina i dati più vecchi di N giorni}';

    protected $description = 'Elimina gli ordini completati più vecchi del numero di giorni indicato';

    public function handle(): void
    {
        $days = (int) $this->option('days');

        if (! $this->confirm("Vuoi eliminare gli ordini completati più vecchi di {$days} giorni?")) {
            $this->info('Annullato.');
            return;
        }

        $deleted = Order::where('status', 'completed')
            ->where('created_at', '<', now()->subDays($days))
            ->delete();

        $this->info("Eliminati {$deleted} ordini.");
    }
}

Combinazione con lo scheduler

Il comando creato può essere schedulato in routes/console.php. Per i dettagli vedi Task scheduling.

use Illuminate\Support\Facades\Schedule;

// esegue ogni giorno alle 2:00 di notte
Schedule::command('orders:prune --days=90')->dailyAt('2:00');

// esegue ogni lunedì alle 9:00
Schedule::command('import:products storage/weekly.csv')->weeklyOn(1, '9:00');

Test dei comandi

Con le funzionalità di test di Laravel puoi verificare il comportamento dei comandi Artisan.

<?php

namespace Tests\Feature\Commands;

use App\Models\Order;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class PruneOldOrdersTest extends TestCase
{
    use RefreshDatabase;

    public function test_it_deletes_old_completed_orders(): void
    {
        // ordine completato più vecchio di 90 giorni
        Order::factory()->create([
            'status'     => 'completed',
            'created_at' => now()->subDays(100),
        ]);

        // ordine completato recente (non dovrebbe essere eliminato)
        Order::factory()->create([
            'status'     => 'completed',
            'created_at' => now()->subDays(10),
        ]);

        $this->artisan('orders:prune', ['--days' => 90])
            ->expectsConfirmation('Vuoi eliminare gli ordini completati più vecchi di 90 giorni?', 'yes')
            ->expectsOutput('Eliminati 1 ordini.')
            ->assertExitCode(0);

        $this->assertDatabaseCount('orders', 1);
    }

    public function test_it_cancels_when_user_declines(): void
    {
        Order::factory()->create(['status' => 'completed', 'created_at' => now()->subDays(100)]);

        $this->artisan('orders:prune', ['--days' => 90])
            ->expectsConfirmation('Vuoi eliminare gli ordini completati più vecchi di 90 giorni?', 'no')
            ->expectsOutput('Annullato.')
            ->assertExitCode(0);

        $this->assertDatabaseCount('orders', 1);
    }
}

Esempi di asserzioni utilizzabili con il metodo artisan():

Metodo	Descrizione
`expectsOutput('...')`	Verifica che venga stampato il testo indicato
`expectsQuestion('?', 'risposta')`	Simula l’input di `ask()`
`expectsConfirmation('?', 'yes')`	Simula la risposta di `confirm()`
`expectsChoice('?', 'opzione')`	Simula la scelta di `choice()`
`assertExitCode(0)`	Verifica il codice di uscita (0 = successo)
`assertFailed()`	Verifica che il codice di uscita sia diverso da 0

Il comando `dev`

Il comando Artisan dev avvia in un’unica finestra del terminale i vari processi necessari per lo sviluppo locale. Per default esegue in parallelo server di sviluppo PHP, queue worker, monitoraggio dei log con Pail e compilazione degli asset di Vite.

php artisan dev

Internamente usa il pacchetto npm concurrently per gestire i processi. Ogni processo è etichettato e colorato, così puoi distinguerlo facilmente nell’output del terminale. Se un processo fallisce, tutti gli altri vengono fermati automaticamente. I processi eseguiti per default sono i seguenti.

Nome	Comando
`server`	`php artisan serve --host=localhost`
`queue`	`php artisan queue:listen --tries=1 --timeout=0`
`logs`	`php artisan pail --timeout=0`
`vite`	`npm run dev`

Il processo vite rileva automaticamente il package manager Node in uso (npm, pnpm, Yarn, Bun) e usa il comando appropriato.

Personalizzare i processi di `dev`

Puoi personalizzare i processi eseguiti dal comando dev con la classe DevCommands. Di solito la registrazione avviene nel metodo boot dell’AppServiceProvider dell’applicazione. Il metodo register accetta la stringa del comando e un nome di processo opzionale.

use Illuminate\Foundation\DevCommands;

/**
 * Bootstrap dei servizi applicativi
 */
public function boot(): void
{
    DevCommands::register('some-command --flag', 'my-process');
}

Per registrare un comando Artisan puoi usare il metodo artisan, che antepone automaticamente php artisan.

DevCommands::artisan('horizon', 'horizon');

Analogamente, il metodo node antepone il comando di esecuzione del package manager rilevato (es. npm run), mentre nodeExec antepone il comando exec (es. npx).

DevCommands::node('storybook', 'storybook');

DevCommands::nodeExec('tailwindcss -i resources/css/app.css -o public/css/app.css --watch', 'tailwind');

Registrando un processo con lo stesso nome di uno di default, lo sostituisci. Ad esempio, puoi far girare il server su una porta diversa.

DevCommands::artisan('serve --host=localhost --port=9000', 'server');

Puoi personalizzare anche il colore dell’etichetta del processo. I metodi colore disponibili sono blue, purple, pink, orange, green e yellow. Puoi anche passare un colore hex personalizzato al metodo color.

DevCommands::register('my-command', 'my-process')->green();

DevCommands::register('my-command', 'my-process')->color('#ff6347');

Per elencare i processi dev registrati senza avviarli, usa il comando dev:list.

php artisan dev:list

Filtrare i processi di `dev`

Con il metodo only puoi indicare di avviare solo determinati processi quando esegui dev. Analogamente, con except puoi escludere processi specifici.

// avvia solo server e vite...
DevCommands::only('server', 'vite');

// avvia tutti i processi tranne il queue worker...
DevCommands::except('queue');

Se in sviluppo locale usi anche Horizon o Reverb, registrandoli con DevCommands::artisan() puoi avviare tutto con un solo php artisan dev.

Riepilogo dei comandi più usati

# crea un nuovo comando
php artisan make:command CommandName

# elenco dei comandi disponibili
php artisan list

# aiuto su un comando
php artisan help command:name

# avvia Tinker
php artisan tinker

​Che cos’è Artisan

​Tinker

​Creare comandi personalizzati

​Generare un comando

​Struttura di base del comando

​Definire argomenti e opzioni

​Ottenere argomenti e opzioni

​input() — accessor tipizzati

​Interazione con l’utente

​Stampare messaggi

​Chiedere all’utente

​Barra di avanzamento

​Casi d’uso pratici

​Comando di importazione dati

​Comando di manutenzione periodica

​Combinazione con lo scheduler

​Test dei comandi

​Il comando dev

​Personalizzare i processi di dev

​Filtrare i processi di dev

​Riepilogo dei comandi più usati

Che cos’è Artisan

Tinker

Creare comandi personalizzati

Generare un comando

Struttura di base del comando

Definire argomenti e opzioni

Ottenere argomenti e opzioni

`input()` — accessor tipizzati

Interazione con l’utente

Stampare messaggi

Chiedere all’utente

Barra di avanzamento

Casi d’uso pratici

Comando di importazione dati

Comando di manutenzione periodica

Combinazione con lo scheduler

Test dei comandi

Il comando `dev`

Personalizzare i processi di `dev`

Filtrare i processi di `dev`

Riepilogo dei comandi più usati