michaelschiemer/docs/console-dialog-mode.md

Console Dialog Mode

Übersicht

Der Console Dialog Mode bietet eine einfache, textbasierte interaktive Schnittstelle für die Console, ähnlich einem AI-Assistenten. Im Gegensatz zur grafischen TUI (Text User Interface) verwendet der Dialog-Modus eine klassische Prompt-Eingabe mit Command-Vorschlägen und History-Support.

Features

✅ Hauptfunktionen

• Prompt-basierte Eingabe: Einfache Text-Eingabe wie bei einem AI-Assistenten
• Readline-Support: Tab-Completion und History-Navigation (falls php-readline installiert)
• Command-Vorschläge: Automatische Vorschläge bei Tippfehlern
• Kontextuelle Hilfe: Hilfe während der Eingabe
• Command-History: Nachverfolgung und Anzeige von verwendeten Commands
• Einfache Ausgabe: Keine komplexe Terminal-Manipulation

🎯 Optional Features

• Tab-Completion: Automatische Vervollständigung von Commands
• History-Navigation: ↑/↓ Tasten für Command-History (mit Readline)
• Command-Suggestions: Intelligente Vorschläge bei Tippfehlern (Levenshtein-Similarity)
• Kontextuelle Hilfe: Detaillierte Hilfe während der Eingabe
• Quoted Arguments: Unterstützung für Argumente in Anführungszeichen

Verwendung

Dialog-Modus starten

# Dialog-Modus explizit starten
php console.php --dialog

# Alternative (Alias)
php console.php --chat

Vergleich: TUI vs. Dialog-Modus

Feature	TUI (Standard)	Dialog-Modus
Start	php console.php	php console.php --dialog
Interface	Grafische Navigation	Prompt-Eingabe
Navigation	Maus + Tastatur	Nur Tastatur
Completion	Limited	Tab-Completion
History	✅	✅ (mit Readline)
Suggestions	✅	✅ (intelligent)
Terminal-Anforderungen	Kompatibles Terminal	Funktioniert überall

Standard-Verhalten

Ohne Argumente startet die Console standardmäßig die TUI:

php console.php              # Startet TUI
php console.php --interactive # Startet TUI explizit
php console.php --tui         # Startet TUI explizit
php console.php -i            # Startet TUI explizit

Built-in Commands

Der Dialog-Modus bietet mehrere Built-in Commands:

help - Hilfe anzeigen

Zeigt alle verfügbaren Commands gruppiert nach Kategorien:

console> help
console> ?
console> :help
console> h

help <command> - Detaillierte Hilfe

Zeigt detaillierte Hilfe für einen spezifischen Command:

console> help db:migrate
console> help user:create

history - Command-History

Zeigt die letzten verwendeten Commands:

console> history
console> :history

clear - Bildschirm löschen

Löscht den Bildschirm:

console> clear
console> :clear

exit / quit - Beenden

Beendet den Dialog-Modus:

console> exit
console> quit
console> q
console> :q

Command-Ausführung

Basis-Commands

Commands werden direkt eingegeben:

console> db:migrate
console> user:list
console> cache:clear

Commands mit Argumenten

Argumente werden nach dem Command angegeben:

console> user:create alice@example.com 25
console> db:migrate --force

Quoted Arguments

Argumente mit Leerzeichen können in Anführungszeichen gesetzt werden:

console> user:create "John Doe" "john@example.com"
console> deploy "production environment"

Readline-Support

Installation

Für optimale Erfahrung sollte die php-readline Extension installiert sein:

# Ubuntu/Debian
sudo apt-get install php-readline

# macOS (Homebrew)
brew install php-readline

# Alpine
apk add php-readline

Features mit Readline

Wenn Readline verfügbar ist, werden folgende Features aktiviert:

• Tab-Completion: Automatische Vervollständigung von Commands
• History-Navigation: ↑/↓ Tasten für Command-History
• History-Persistenz: History wird zwischen Sessions gespeichert

Ohne Readline

Wenn Readline nicht verfügbar ist, funktioniert der Dialog-Modus weiterhin, aber ohne Tab-Completion und History-Navigation. Die History wird trotzdem gespeichert.

Command-Vorschläge

Automatische Vorschläge

Bei Tippfehlern werden automatisch ähnliche Commands vorgeschlagen:

console> db:migrat
Command 'db:migrat' not found.

Did you mean one of these?
  • db:migrate (95% match - prefix match)
  • db:migration:status (45% match - fuzzy match)

Vorschlags-Algorithmus

Die Vorschläge basieren auf:

1. Exact Match: 100% Ähnlichkeit
2. Prefix Match: Command beginnt mit Eingabe (90% Ähnlichkeit)
3. Contains Match: Command enthält Eingabe (70% Ähnlichkeit)
4. Levenshtein Distance: Edit-Distanz-basierte Ähnlichkeit
5. Word Similarity: Wort-basierte Ähnlichkeit für Commands mit Doppelpunkt

History-basierte Vorschläge

Commands aus der History haben Priorität:

• Favorites: Commands, die als Favoriten markiert sind
• Recent: Kürzlich verwendete Commands
• Frequency: Häufig verwendete Commands

Kontextuelle Hilfe

Während der Eingabe

Nach fehlgeschlagenen Commands wird kontextuelle Hilfe angezeigt:

console> db:migrate
Executing: db:migrate
────────────────────────────────────────────────────────────
✗ Command failed with exit code: 1
────────────────────────────────────────────────────────────

💡 Tip: Use "help db:migrate" for detailed help.
Description: Run database migrations

Detaillierte Hilfe

Die detaillierte Hilfe zeigt:

• Command-Name und Beschreibung
• Usage-Beispiele
• Parameter-Dokumentation
• Optionen und Flags
• Beispiele

console> help db:migrate

📖 Command Help: db:migrate
════════════════════════════════════════════════════════════

Command: db:migrate
Description: Run database migrations

Usage:
  php console.php db:migrate [options]

Options:
  --force      Force migration execution
  --pretend    Show SQL without executing

Examples:
  php console.php db:migrate
  php console.php db:migrate --force
  php console.php db:migrate --pretend

Command-History

History-Verwaltung

Die History wird automatisch verwaltet:

• Automatische Speicherung: Jeder ausgeführte Command wird gespeichert
• Persistenz: History wird zwischen Sessions gespeichert
• Deduplizierung: Doppelte Commands werden aktualisiert, nicht dupliziert
• Limit: Standardmäßig werden 100 Commands gespeichert

History anzeigen

console> history

📜 Command History
════════════════════════════════════════════════════════════

  1. db:migrate (used 5 times, last: 2024-01-15 10:30:45)
  2. user:create (used 3 times, last: 2024-01-15 09:15:22)
  3. cache:clear (used 2 times, last: 2024-01-14 16:45:10)

History-Navigation (mit Readline)

Mit Readline können Sie durch die History navigieren:

• ↑: Vorheriger Command
• ↓: Nächster Command
• Tab: Command-Vervollständigung

Workflow-Beispiel

$ php console.php --dialog

🤖 Console Dialog Mode
════════════════════════════════════════════════════════════

Available commands: 42
✓ Readline support enabled (Tab completion, ↑/↓ history)

Type "help" for available commands or "exit" to quit.

console> help
📚 Available Commands
════════════════════════════════════════════════════════════

Database:
  db:migrate
    Run database migrations
  db:seed
    Seed database with test data

User:
  user:create
    Create a new user
  user:list
    List all users

console> user:create alice@example.com 25
Executing: user:create
Arguments: alice@example.com 25
────────────────────────────────────────────────────────────
✓ Command completed successfully
────────────────────────────────────────────────────────────

console> help user:create
📖 Command Help: user:create
════════════════════════════════════════════════════════════

Command: user:create
Description: Create a new user

Usage:
  php console.php user:create <email> [age] [--admin]

Parameters:
  email (string, required) - User email address
  age (int, optional, default: 18) - User age
  --admin (bool, optional) - Create as admin user

console> history
📜 Command History
════════════════════════════════════════════════════════════

  1. user:create (used 1 times, last: 2024-01-15 10:30:45)
  2. help (used 2 times, last: 2024-01-15 10:30:30)

console> exit
Goodbye! 👋

Tipps & Best Practices

Tab-Completion nutzen

Verwenden Sie Tab für Command-Vervollständigung:

console> db:mi<Tab>        # Vervollständigt zu db:migrate
console> user:cr<Tab>      # Vervollständigt zu user:create

History effizient nutzen

• ↑/↓: Navigieren Sie durch die History
• History-Command: Zeigen Sie alle Commands an
• Readline: Nutzen Sie Readline für bessere Erfahrung

Hilfe verwenden

• help: Zeigt alle Commands
• help <command>: Detaillierte Hilfe für einen Command
• Kontextuelle Hilfe: Wird nach Fehlern automatisch angezeigt

Commands mit Argumenten

• Quoted Arguments: Verwenden Sie Anführungszeichen für Argumente mit Leerzeichen
• Flags: Verwenden Sie --flag für boolesche Optionen
• Positional Arguments: Argumente werden in der Reihenfolge der Methoden-Parameter übergeben

Troubleshooting

Readline nicht verfügbar

Wenn Readline nicht verfügbar ist, sehen Sie:

⚠ Readline not available (install php-readline for better experience)

Lösung: Installieren Sie die php-readline Extension.

Commands nicht gefunden

Wenn ein Command nicht gefunden wird, werden Vorschläge angezeigt:

console> db:migrat
Command 'db:migrat' not found.

Did you mean one of these?
  • db:migrate (95% match)

History funktioniert nicht

• Ohne Readline: History-Navigation (↑/↓) funktioniert nicht, aber History wird gespeichert
• Mit Readline: History-Navigation funktioniert automatisch

Hilfe generiert Fehler

Wenn die Hilfe-Generierung fehlschlägt, wird eine Fallback-Ausgabe angezeigt:

console> help invalid:command
Command 'invalid:command' not found.

Did you mean one of these?
  • valid:command (85% match)

Architektur

Komponenten

• ConsoleDialog: Haupt-Orchestrator für den Dialog-Modus
• DialogCommandExecutor: Command-Execution für Dialog-Modus
• CommandHistory: History-Verwaltung (geteilt mit TUI)
• CommandSuggestionEngine: Vorschlags-Engine (geteilt mit TUI)
• CommandHelpGenerator: Hilfe-Generator (geteilt mit TUI)

Integration

Der Dialog-Modus ist vollständig in ConsoleApplication integriert:

// In ConsoleApplication::run()
if (in_array($commandName, ['--dialog', '--chat'])) {
    return $this->launchDialogMode();
}

Wiederverwendung

Der Dialog-Modus nutzt die gleichen Komponenten wie die TUI:

• CommandRegistry: Command-Discovery und -Execution
• CommandGroupRegistry: Command-Kategorisierung
• CommandHistory: History-Verwaltung
• CommandSuggestionEngine: Vorschlags-Engine

Unterschiede zur TUI

Aspekt	TUI	Dialog-Modus
Interface	Grafisch mit Navigation	Prompt-basiert
Terminal-Anforderungen	Kompatibles Terminal erforderlich	Funktioniert überall
Maus-Support	✅	❌
Tab-Completion	Limited	✅ (mit Readline)
History-Navigation	Limited	✅ (mit Readline)
Command-Suggestions	✅	✅ (intelligenter)
Einfachheit	Komplexer	Einfacher
Best für	Visuelle Navigation	Schnelle Eingabe

Zusammenfassung

Der Dialog-Modus bietet eine einfache, effiziente Alternative zur TUI für Benutzer, die:

• Eine klassische Prompt-Eingabe bevorzugen
• Schnelle Command-Ausführung ohne Navigation benötigen
• Tab-Completion und History-Navigation nutzen möchten
• In Terminals ohne TUI-Support arbeiten

Start: php console.php --dialog oder php console.php --chat