La console Artisan - Knowledge of Laravel

Qu’est-ce qu’Artisan ?

Artisan est l’outil en ligne de commande (CLI) livré avec Laravel. Présent à la racine du projet sous forme d’un script artisan, il fournit de nombreuses commandes qui facilitent le développement et l’exploitation. Pour lister toutes les commandes disponibles, utilisez list.

php artisan list

Pour afficher l’usage d’une commande, préfixez-la par help.

php artisan help migrate

Avec Laravel Sail, utilisez sail artisan à la place de php artisan. Les commandes s’exécutent alors dans le conteneur Docker.

./vendor/bin/sail artisan list

Tinker

Laravel Tinker est un environnement REPL qui vous permet d’interagir depuis la ligne de commande avec toute votre application : modèles Eloquent, jobs, événements, etc.

php artisan tinker

Une fois lancé, vous pouvez exécuter du code PHP directement.

// Récupérer et inspecter un utilisateur
>>> App\Models\User::find(1)
// Créer un enregistrement via une factory
>>> App\Models\User::factory()->create()
// Appeler directement une classe de service
>>> app(App\Services\OrderService::class)->process(1)

Tinker modifie réellement les données. Soyez très prudent en production. Il est particulièrement adapté aux vérifications et au débogage en local ou en staging.

Créer une commande personnalisée

Générer une commande

Générez le squelette d’une classe de commande avec make:command.

php artisan make:command ImportProducts

Le fichier app/Console/Commands/ImportProducts.php est créé.

Structure de base d’une commande

Une commande générée comprend trois éléments principaux : $signature, $description et handle().

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class ImportProducts extends Command
{
    /**
     * Nom de la commande, arguments et options.
     */
    protected $signature = 'import:products';

    /**
     * Description de la commande (visible dans php artisan list).
     */
    protected $description = 'Importer les produits depuis un fichier CSV';

    /**
     * Traitement de la commande.
     */
    public function handle(): void
    {
        $this->info('Démarrage de l\'import...');
        // Décrivez ici votre traitement
        $this->info('Terminé.');
    }
}

Laravel 13 permet aussi d’utiliser des attributs PHP.

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

#[Signature('import:products')]
#[Description('Importer les produits depuis un fichier CSV')]
class ImportProducts extends Command
{
    public function handle(): void
    {
        // ...
    }
}

Déclarer les arguments et les options

$signature regroupe la définition du nom de la commande, des arguments et des options.

protected $signature = 'import:products
                        {file : Chemin du fichier CSV à importer}
                        {--limit= : Nombre maximum d\'éléments à importer}
                        {--dry-run : N\'enregistre pas réellement en base (vérification)}';

Syntaxe	Type	Description
`{file}`	Argument obligatoire	Une erreur est levée s’il est omis
`{file?}`	Argument facultatif	Vaut `null` s’il est omis
`{file=products.csv}`	Argument avec valeur par défaut	Utilise la valeur par défaut s’il est omis
`{--queue}`	Option (flag)	`true` si présente, `false` sinon
`{--limit=}`	Option avec valeur	S’utilise comme `--limit=100`
`{--limit=50}`	Option avec valeur par défaut	Vaut `50` si non fournie
`{--Q\|queue}`	Option avec raccourci	Peut également s’utiliser via `-Q`

Récupérer les arguments et les options

Dans la méthode handle(), utilisez argument() et option() pour lire les valeurs.

public function handle(): void
{
    $file    = $this->argument('file');       // Récupération de l'argument
    $limit   = $this->option('limit');        // Récupération de l'option
    $dryRun  = $this->option('dry-run');      // Option flag (bool)

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

    if ($dryRun) {
        $this->warn('Mode dry-run : aucune écriture en base');
    }
}

`input()` — accesseurs typés

La méthode input() fournit des accesseurs typés pour les arguments et options, semblables à ceux d’une requête HTTP.

use App\Enums\ReportType;

public function handle(): void
{
    // Accès à l'instance CommandInput
    $from = $this->input()->date('from');
    $type = $this->input()->enum('type', ReportType::class);
    $limit = $this->input()->integer('limit');
}

Pour récupérer directement une valeur par son nom (recherche à la fois dans les arguments et les options) :

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

Alors que argument() et option() retournent des chaînes, les accesseurs typés de input() renvoient une valeur du bon type. C’est pratique pour manipuler des dates, des nombres ou des Enums en toute sécurité.

Interaction avec l’utilisateur

Affichage de messages

Plusieurs méthodes permettent d’afficher des messages colorés dans la console.

$this->info('Traitement terminé avec succès');    // vert
$this->warn('Cette opération est irréversible');   // jaune
$this->error('Une erreur est survenue');           // rouge
$this->line('Texte standard');                     // sans couleur
$this->comment('Information complémentaire');      // gris clair

Demander une saisie à l’utilisateur

Vous pouvez interagir avec l’utilisateur de manière interactive.

// Saisie texte
$name = $this->ask('Nom du responsable ?');

// Avec valeur par défaut
$env = $this->ask('Environnement d\'exécution', 'production');

// Saisie masquée (mot de passe, etc.)
$password = $this->secret('Clé API ?');

// Confirmation Oui/Non
if (! $this->confirm('Importer sur la base de production ?')) {
    $this->info('Opération annulée.');
    return;
}

// Choix parmi une liste
$format = $this->choice('Choisissez le format de sortie', ['csv', 'json', 'xml'], 0);

Barre de progression

Affichez clairement l’avancement d’un traitement volumineux.

use App\Models\Product;

// Passer une collection suffit à afficher automatiquement la barre
$this->withProgressBar(Product::cursor(), function (Product $product) {
    $this->processProduct($product);
});

Pour un contrôle plus fin, procédez manuellement.

$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();

Cas d’usage concrets

Commande d’import de données

Exemple pratique d’une commande d’import de produits depuis un fichier CSV.

Générer la commande

php artisan make:command ImportProducts

Implémenter la commande

<?php

namespace App\Console\Commands;

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

class ImportProducts extends Command
{
    protected $signature = 'import:products
                            {file : Chemin du fichier CSV}
                            {--limit= : Nombre maximum d\'éléments à importer}
                            {--dry-run : Vérification uniquement (aucune écriture)}';

    protected $description = 'Importer les produits depuis un fichier 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("Fichier introuvable : {$filePath}");
            return;
        }

        // Lecture du CSV via les fonctions natives PHP
        $handle = fopen($filePath, 'r');
        $headers = fgetcsv($handle); // La 1re ligne sert d'en-tête
        $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} éléments concernés (dry-run : aucune écriture).");
        } else {
            $this->info("{$count} éléments importés avec succès.");
        }
    }
}

Exécuter la commande

# Import standard
php artisan import:products storage/products.csv

# En limitant le nombre
php artisan import:products storage/products.csv --limit=100

# Vérification en dry-run
php artisan import:products storage/products.csv --dry-run

Commande de maintenance périodique

Exemple d’une commande de maintenance récurrente, comme la suppression de données anciennes.

<?php

namespace App\Console\Commands;

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

class PruneOldOrders extends Command
{
    protected $signature = 'orders:prune {--days=90 : Ancienneté (en jours) à partir de laquelle supprimer}';

    protected $description = 'Supprimer les commandes terminées plus anciennes qu\'un nombre de jours donné';

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

        if (! $this->confirm("Supprimer les commandes terminées de plus de {$days} jours ?")) {
            $this->info('Opération annulée.');
            return;
        }

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

        $this->info("{$deleted} commandes supprimées.");
    }
}

Combinaison avec la planification

Les commandes que vous créez peuvent être planifiées dans routes/console.php. Consultez Planification de tâches pour plus de détails.

use Illuminate\Support\Facades\Schedule;

// Tous les jours à 2h00
Schedule::command('orders:prune --days=90')->dailyAt('2:00');

// Tous les lundis à 9h00
Schedule::command('import:products storage/weekly.csv')->weeklyOn(1, '9:00');

Tester une commande

Grâce aux outils de test de Laravel, vous pouvez vérifier le comportement de vos commandes 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
    {
        // Commande terminée datée de plus de 90 jours
        Order::factory()->create([
            'status'     => 'completed',
            'created_at' => now()->subDays(100),
        ]);

        // Commande récente terminée (ne doit pas être supprimée)
        Order::factory()->create([
            'status'     => 'completed',
            'created_at' => now()->subDays(10),
        ]);

        $this->artisan('orders:prune', ['--days' => 90])
            ->expectsConfirmation('Supprimer les commandes terminées de plus de 90 jours ?', 'yes')
            ->expectsOutput('1 commandes supprimées.')
            ->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('Supprimer les commandes terminées de plus de 90 jours ?', 'no')
            ->expectsOutput('Opération annulée.')
            ->assertExitCode(0);

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

Quelques assertions utiles avec la méthode artisan() :

Méthode	Description
`expectsOutput('...')`	Vérifie qu’un texte donné est affiché
`expectsQuestion('?', 'réponse')`	Simule une saisie pour `ask()`
`expectsConfirmation('?', 'yes')`	Simule une réponse pour `confirm()`
`expectsChoice('?', 'choix')`	Simule un choix pour `choice()`
`assertExitCode(0)`	Vérifie le code de sortie (0 = succès)
`assertFailed()`	Vérifie que le code de sortie est différent de 0

La commande `dev`

La commande Artisan dev lance dans une seule fenêtre de terminal l’ensemble des processus nécessaires au développement local. Par défaut, le serveur de développement PHP, le worker de queue, la surveillance des logs via Pail et la compilation d’assets Vite s’exécutent en parallèle.

php artisan dev

En interne, elle s’appuie sur le package npm concurrently pour gérer les processus. Chacun est étiqueté et coloré, ce qui permet de les distinguer facilement dans la sortie du terminal. Si l’un d’eux échoue, tous les autres sont arrêtés automatiquement. Voici les processus lancés par défaut :

Nom	Commande
`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`

Le processus vite détecte automatiquement votre gestionnaire de paquets Node (npm, pnpm, Yarn, Bun) et utilise la commande d’exécution appropriée.

Personnaliser les processus `dev`

Les processus lancés par dev peuvent être personnalisés via la classe DevCommands. Vous l’enregistrez typiquement dans la méthode boot de l’AppServiceProvider. La méthode register prend une commande sous forme de chaîne et un nom de processus facultatif.

use Illuminate\Foundation\DevCommands;

/**
 * Amorce les services de l'application.
 */
public function boot(): void
{
    DevCommands::register('some-command --flag', 'my-process');
}

Pour enregistrer une commande Artisan, utilisez artisan, qui préfixe automatiquement par php artisan.

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

De même, la méthode node préfixe par la commande d’exécution du gestionnaire de paquets détecté (par ex. npm run), tandis que nodeExec préfixe par sa commande exec (par ex. npx).

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

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

Enregistrer un processus avec le même nom qu’un processus par défaut remplace ce dernier. Vous pouvez par exemple lancer le serveur sur un autre port.

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

La couleur du label affichée dans le terminal peut aussi être personnalisée. Les couleurs disponibles sont blue, purple, pink, orange, green et yellow. La méthode color accepte également une valeur hex personnalisée.

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

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

Pour lister les processus dev enregistrés sans les démarrer, utilisez dev:list.

php artisan dev:list

Filtrer les processus `dev`

La méthode only permet de démarrer uniquement certains processus. Inversement, except en exclut certains.

// Ne lance que les processus server et vite...
DevCommands::only('server', 'vite');

// Lance tous les processus sauf le worker de queue...
DevCommands::except('queue');

Si vous utilisez Horizon ou Reverb en local, enregistrez-les avec DevCommands::artisan() afin de tout lancer via un seul php artisan dev.

Commandes couramment utilisées

# Créer une nouvelle commande
php artisan make:command CommandName

# Lister les commandes disponibles
php artisan list

# Afficher l'usage d'une commande
php artisan help command:name

# Lancer Tinker
php artisan tinker

​Qu’est-ce qu’Artisan ?

​Tinker

​Créer une commande personnalisée

​Générer une commande

​Structure de base d’une commande

​Déclarer les arguments et les options

​Récupérer les arguments et les options

​input() — accesseurs typés

​Interaction avec l’utilisateur

​Affichage de messages

​Demander une saisie à l’utilisateur

​Barre de progression

​Cas d’usage concrets

​Commande d’import de données

​Commande de maintenance périodique

​Combinaison avec la planification

​Tester une commande

​La commande dev

​Personnaliser les processus dev

​Filtrer les processus dev

​Commandes couramment utilisées

Qu’est-ce qu’Artisan ?

Tinker

Créer une commande personnalisée

Générer une commande

Structure de base d’une commande

Déclarer les arguments et les options

Récupérer les arguments et les options

`input()` — accesseurs typés

Interaction avec l’utilisateur

Affichage de messages

Demander une saisie à l’utilisateur

Barre de progression

Cas d’usage concrets

Commande d’import de données

Commande de maintenance périodique

Combinaison avec la planification

Tester une commande

La commande `dev`

Personnaliser les processus `dev`

Filtrer les processus `dev`

Commandes couramment utilisées