Artisan-Konsole - Knowledge of Laravel

Was ist Artisan?

Artisan ist das mit Laravel ausgelieferte Command-Line-Interface (CLI). Es existiert als artisan-Skript im Projekt-Root und stellt zahlreiche Kommandos bereit, mit denen sich Entwicklung und Betrieb effizient gestalten lassen. Um eine Liste aller verfügbaren Kommandos anzuzeigen, verwenden Sie den Befehl list.

php artisan list

Um die Nutzung eines Kommandos zu prüfen, stellen Sie help voran.

php artisan help migrate

Wenn Sie Laravel Sail nutzen, verwenden Sie statt php artisan den Befehl sail artisan. Die Kommandos werden dann im Docker-Container ausgeführt.

./vendor/bin/sail artisan list

Tinker

Laravel Tinker ist eine REPL-Umgebung, in der Sie die gesamte Anwendung — Eloquent-Modelle, Jobs, Events usw. — interaktiv über die Kommandozeile bedienen können.

php artisan tinker

Nach dem Start können Sie PHP-Code direkt ausführen.

// Nutzer laden und ansehen
>>> App\Models\User::find(1)
// Datensatz mit einer Factory anlegen
>>> App\Models\User::factory()->create()
// Service-Klasse direkt aufrufen
>>> app(App\Services\OrderService::class)->process(1)

Tinker verändert die Daten tatsächlich. Setzen Sie es in der Produktion mit größter Vorsicht ein. Für Verifikationen und Debugging in lokalen oder Staging-Umgebungen ist es hervorragend geeignet.

Eigene Kommandos erstellen

Kommando generieren

Mit make:command erzeugen Sie ein Grundgerüst für eine Kommandoklasse.

php artisan make:command ImportProducts

Dabei wird die Datei app/Console/Commands/ImportProducts.php erzeugt.

Grundstruktur eines Kommandos

Die generierte Kommandoklasse besitzt drei zentrale Elemente: $signature, $description und handle().

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class ImportProducts extends Command
{
    /**
     * Definition von Kommandoname, Argumenten und Optionen
     */
    protected $signature = 'import:products';

    /**
     * Beschreibung des Kommandos (erscheint in php artisan list)
     */
    protected $description = 'Importiert Produktdaten aus einer CSV-Datei';

    /**
     * Ausführung des Kommandos
     */
    public function handle(): void
    {
        $this->info('Import wird gestartet ...');
        // Verarbeitung
        $this->info('Fertig.');
    }
}

In Laravel 13 können Sie auch die Schreibweise mit PHP-Attributen verwenden.

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

#[Signature('import:products')]
#[Description('Importiert Produktdaten aus einer CSV-Datei')]
class ImportProducts extends Command
{
    public function handle(): void
    {
        // ...
    }
}

Argumente und Optionen definieren

In $signature definieren Sie Kommandoname, Argumente und Optionen zusammenhängend.

protected $signature = 'import:products
                        {file : Pfad zur zu importierenden CSV-Datei}
                        {--limit= : Maximale Anzahl importierter Datensätze}
                        {--dry-run : Nichts in die DB speichern (zur Verifikation)}';

Notation	Art	Beschreibung
`{file}`	Pflichtargument	Auslassen führt zu einem Fehler
`{file?}`	Optionales Argument	Bei Auslassen `null`
`{file=products.csv}`	Argument mit Standardwert	Bei Auslassen wird der Standardwert verwendet
`{--queue}`	Flag-Option	Angegeben `true`, sonst `false`
`{--limit=}`	Option mit Wert	Übergabe wie `--limit=100`
`{--limit=50}`	Option mit Standardwert	Bei Auslassen `50`
`{--Q\|queue}`	Mit Shortcut	Auch als `-Q` angebbar

Argumente und Optionen auslesen

In der Methode handle() verwenden Sie argument() und option(), um Werte auszulesen.

public function handle(): void
{
    $file    = $this->argument('file');       // Argument abrufen
    $limit   = $this->option('limit');        // Option abrufen
    $dryRun  = $this->option('dry-run');      // Flag-Option (bool)

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

    if ($dryRun) {
        $this->warn('Dry-Run-Modus: Speichern in die DB wird übersprungen');
    }
}

`input()` — typisierter Zugriff

Mit der Methode input() können Sie Kommandoargumente und -optionen mit denselben typisierten Accessorn wie bei HTTP-Requests abrufen.

use App\Enums\ReportType;

public function handle(): void
{
    // Argumente und Optionen als CommandInput-Instanz erhalten
    $from = $this->input()->date('from');
    $type = $this->input()->enum('type', ReportType::class);
    $limit = $this->input()->integer('limit');
}

Um gezielt einen bestimmten Namen abzurufen, übergeben Sie den Namen direkt (es wird sowohl unter Argumenten als auch Optionen gesucht).

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

Während argument() und option() Strings zurückgeben, konvertieren die typisierten Accessoren von input() in den passenden Typ. Praktisch, wenn Sie Datumsangaben, Zahlen oder Enums typsicher behandeln möchten.

Interaktion mit Nutzern

Nachrichten ausgeben

Für farbige Ausgaben in der Konsole stehen entsprechende Methoden bereit.

$this->info('Vorgang erfolgreich abgeschlossen');    // Grün
$this->warn('Diese Aktion kann nicht rückgängig gemacht werden');    // Gelb
$this->error('Ein Fehler ist aufgetreten');       // Rot
$this->line('Normaler Text');             // Ohne Farbe
$this->comment('Zusätzliche Info');               // Hellgrau

Nutzer abfragen

Sie können Eingaben von Nutzern interaktiv entgegennehmen.

// Texteingabe
$name = $this->ask('Bitte geben Sie den Namen des Ansprechpartners ein');

// Mit Standardwert
$env = $this->ask('Wählen Sie die Ausführungsumgebung', 'production');

// Für vertrauliche Eingaben wie Passwörter (Eingabe wird nicht angezeigt)
$password = $this->secret('Bitte geben Sie den API-Schlüssel ein');

// Ja/Nein-Bestätigung
if (! $this->confirm('In die Produktions-DB importieren?')) {
    $this->info('Abgebrochen.');
    return;
}

// Aus einer Auswahl wählen
$format = $this->choice('Wählen Sie das Ausgabeformat', ['csv', 'json', 'xml'], 0);

Fortschrittsbalken

Bei der Verarbeitung großer Datenmengen können Sie den Fortschritt übersichtlich anzeigen.

use App\Models\Product;

// Eine Collection genügt — Fortschrittsbalken wird automatisch angezeigt
$this->withProgressBar(Product::cursor(), function (Product $product) {
    $this->processProduct($product);
});

Für feinere manuelle Steuerung verwenden Sie folgende Methode:

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

Praxisorientierte Anwendungsfälle

Datenimport-Kommando

Ein praxisnahes Beispiel für ein Kommando, das Produktdaten aus einer CSV-Datei importiert.

Kommando erzeugen

php artisan make:command ImportProducts

Kommando implementieren

<?php

namespace App\Console\Commands;

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

class ImportProducts extends Command
{
    protected $signature = 'import:products
                            {file : Pfad zur CSV-Datei}
                            {--limit= : Maximale Anzahl importierter Datensätze}
                            {--dry-run : Nur Prüfung (kein Speichern in die DB)}';

    protected $description = 'Importiert Produktdaten aus einer CSV-Datei';

    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("Datei nicht gefunden: {$filePath}");
            return;
        }

        // CSV mit PHP-Standardfunktionen einlesen
        $handle = fopen($filePath, 'r');
        $headers = fgetcsv($handle); // Erste Zeile als 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} Datensätze wären betroffen (Dry-Run: Speichern übersprungen)");
        } else {
            $this->info("Import von {$count} Datensätzen abgeschlossen.");
        }
    }
}

Kommando ausführen

# Regulärer Import
php artisan import:products storage/products.csv

# Anzahl beschränken
php artisan import:products storage/products.csv --limit=100

# Als Dry-Run prüfen
php artisan import:products storage/products.csv --dry-run

Regelmäßiges Wartungskommando

Beispiel für ein regelmäßig ausgeführtes Wartungskommando, etwa zum Löschen alter Daten.

<?php

namespace App\Console\Commands;

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

class PruneOldOrders extends Command
{
    protected $signature = 'orders:prune {--days=90 : Ab wie vielen Tagen alte Daten gelöscht werden}';

    protected $description = 'Löscht abgeschlossene Bestellungen, die älter als die angegebene Anzahl Tage sind';

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

        if (! $this->confirm("Abgeschlossene Bestellungen älter als {$days} Tage löschen?")) {
            $this->info('Abgebrochen.');
            return;
        }

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

        $this->info("{$deleted} Bestellungen wurden gelöscht.");
    }
}

Kombination mit dem Scheduler

Ein erstelltes Kommando können Sie in routes/console.php geplant ausführen. Details siehe Task-Scheduling.

use Illuminate\Support\Facades\Schedule;

// Täglich um 2 Uhr nachts ausführen
Schedule::command('orders:prune --days=90')->dailyAt('2:00');

// Montags um 9 Uhr ausführen
Schedule::command('import:products storage/weekly.csv')->weeklyOn(1, '9:00');

Kommandos testen

Mit den Testfunktionen von Laravel können Sie das Verhalten von Artisan-Kommandos verifizieren.

<?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
    {
        // Abgeschlossene Bestellung, älter als 90 Tage
        Order::factory()->create([
            'status'     => 'completed',
            'created_at' => now()->subDays(100),
        ]);

        // Kürzlich abgeschlossene Bestellung (sollte nicht gelöscht werden)
        Order::factory()->create([
            'status'     => 'completed',
            'created_at' => now()->subDays(10),
        ]);

        $this->artisan('orders:prune', ['--days' => 90])
            ->expectsConfirmation('Abgeschlossene Bestellungen älter als 90 Tage löschen?', 'yes')
            ->expectsOutput('1 Bestellungen wurden gelöscht.')
            ->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('Abgeschlossene Bestellungen älter als 90 Tage löschen?', 'no')
            ->expectsOutput('Abgebrochen.')
            ->assertExitCode(0);

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

Beispiele für Assertion-Methoden, die mit artisan() verwendet werden können:

Methode	Beschreibung
`expectsOutput('...')`	Prüft, ob der angegebene Text ausgegeben wird
`expectsQuestion('?', 'Antwort')`	Simuliert die Eingabe bei `ask()`
`expectsConfirmation('?', 'yes')`	Simuliert die Antwort bei `confirm()`
`expectsChoice('?', 'Auswahl')`	Simuliert die Auswahl bei `choice()`
`assertExitCode(0)`	Prüft den Exit-Code (0 = Erfolg)
`assertFailed()`	Prüft, dass der Exit-Code ungleich 0 ist

Der `dev`-Befehl

Der Artisan-Befehl dev startet mehrere für die lokale Entwicklung notwendige Prozesse in einem einzigen Terminal-Fenster. Standardmäßig laufen parallel: der PHP-Entwicklungsserver, ein Queue-Worker, die Log-Überwachung mit Pail und die Asset-Kompilierung mit Vite.

php artisan dev

Intern verwendet Laravel das npm-Paket concurrently zur Verwaltung der Prozesse. Jeder Prozess wird beschriftet und farblich hervorgehoben, sodass Sie in der Terminalausgabe leicht erkennen, um welchen Prozess es sich handelt. Fällt einer der Prozesse aus, werden alle anderen Prozesse automatisch beendet. Standardmäßig werden folgende Prozesse ausgeführt:

Name	Befehl
`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`

Der vite-Prozess erkennt automatisch den verwendeten Node-Paketmanager (npm, pnpm, Yarn, Bun) und nutzt den passenden Ausführungsbefehl.

Anpassen der `dev`-Prozesse

Sie können die vom dev-Befehl ausgeführten Prozesse mit der Klasse DevCommands anpassen. Üblicherweise registrieren Sie sie in der Methode boot des AppServiceProvider Ihrer Anwendung. Die Methode register erwartet einen Kommandostring und optional einen Prozessnamen.

use Illuminate\Foundation\DevCommands;

/**
 * Bootstrapping der Anwendungsservices.
 */
public function boot(): void
{
    DevCommands::register('some-command --flag', 'my-process');
}

Für Artisan-Kommandos gibt es die Methode artisan, die automatisch php artisan voranstellt.

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

Analog stellt die Methode node den erkannten Paketmanager-Ausführungsbefehl (z. B. npm run) voran, während nodeExec den Exec-Befehl des Paketmanagers (z. B. npx) voranstellt.

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

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

Wenn Sie einen Prozess unter demselben Namen wie einen Standardprozess registrieren, wird dieser Standardprozess ersetzt. So können Sie beispielsweise den Server-Prozess so anpassen, dass er einen anderen Port verwendet.

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

Auch die Farbe der Prozessbeschriftung im Terminal lässt sich anpassen. Verfügbare Farbmethoden sind blue, purple, pink, orange, green und yellow. Der Methode color können Sie zudem einen benutzerdefinierten Hex-Farbwert übergeben.

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

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

Um die registrierten dev-Prozesse aufzulisten, ohne sie auszuführen, verwenden Sie den Befehl dev:list.

php artisan dev:list

Filtern der `dev`-Prozesse

Mit der Methode only legen Sie fest, welche Prozesse beim Ausführen des dev-Befehls gestartet werden sollen. Analog können Sie mit der Methode except bestimmte Prozesse ausschließen.

// Nur die Prozesse server und vite starten ...
DevCommands::only('server', 'vite');

// Alle Prozesse außer dem Queue-Worker starten ...
DevCommands::except('queue');

Wenn Sie in der lokalen Entwicklung parallel zu Horizon oder Reverb arbeiten, ist es praktisch, sie über DevCommands::artisan() zu registrieren — mit einem einzigen php artisan dev starten Sie alles zusammen.

Zusammenfassung häufig verwendeter Befehle

# Neues Kommando erzeugen
php artisan make:command CommandName

# Liste verfügbarer Kommandos
php artisan list

# Nutzung eines Kommandos anzeigen
php artisan help command:name

# Tinker starten
php artisan tinker

​Was ist Artisan?

​Tinker

​Eigene Kommandos erstellen

​Kommando generieren

​Grundstruktur eines Kommandos

​Argumente und Optionen definieren

​Argumente und Optionen auslesen

​input() — typisierter Zugriff

​Interaktion mit Nutzern

​Nachrichten ausgeben

​Nutzer abfragen

​Fortschrittsbalken

​Praxisorientierte Anwendungsfälle

​Datenimport-Kommando

​Regelmäßiges Wartungskommando

​Kombination mit dem Scheduler

​Kommandos testen

​Der dev-Befehl

​Anpassen der dev-Prozesse

​Filtern der dev-Prozesse

​Zusammenfassung häufig verwendeter Befehle

Was ist Artisan?

Tinker

Eigene Kommandos erstellen

Kommando generieren

Grundstruktur eines Kommandos

Argumente und Optionen definieren

Argumente und Optionen auslesen

`input()` — typisierter Zugriff

Interaktion mit Nutzern

Nachrichten ausgeben

Nutzer abfragen

Fortschrittsbalken

Praxisorientierte Anwendungsfälle

Datenimport-Kommando

Regelmäßiges Wartungskommando

Kombination mit dem Scheduler

Kommandos testen

Der `dev`-Befehl

Anpassen der `dev`-Prozesse

Filtern der `dev`-Prozesse

Zusammenfassung häufig verwendeter Befehle