Cli Menu Laravel Package

Getting Started

Start by installing via Composer:

composer require php-school/cli-menu

Then create a basic menu in your console command or standalone script:

use PHPSchool\CliMenu\CliMenu;
use PHPSchool\CliMenu\MenuBuilder;

require 'vendor/autoload.php';

$menu = (new MenuBuilder)
    ->setTitle('My CLI Tool')
    ->addOption('A', 'Run setup', function () { echo "Setting up...\n"; })
    ->addOption('B', 'Exit', function () { echo "Goodbye!\n"; return false; })
    ->build();

$menu->open();

This gives you a responsive, keyboard-navigable menu—arrow keys select, Enter confirms, Esc exits. Perfect for quick tooling like project scaffolding, config setup, or dev utility scripts.

Implementation Patterns

• Callback-based flow control: Return false from a callback to exit the menu loop (e.g., for “Exit” or fatal-error handlers). Return null or omit to return to the menu.
• Dynamic menu generation: Build menus conditionally (e.g., detect existing DB connections, available services, or environment state) before calling build().
• Nested submenus: Use addSubMenu() to create hierarchical navigation:

  ->addSubMenu('Database', (new MenuBuilder)
      ->addOption('M', 'Migrate', $migrateCallable)
      ->addOption('S', 'Seed', $seedCallable)
  )
  

• Styling with themes: Customize globally or per-menu:

  $menu = $builder->build();
  $menu->getRenderable()
       ->setOptionPaddingLeft(3)
       ->setSelectedStyle(new \PHPSchool\CliMenu\Style\SelectedStyle('bg_white', 'black'))
       ->setClosedBorderChars('═', '║', '╔', '╗', '╚', '╝');
  

• Multi-select flows: Use addMultiSelect() for group selections (e.g., modules to enable), and render a summary before execution.

Gotchas and Tips

• Platform compatibility: Menus work best on Unix-like terminals; Windows users may see colors/borders incorrectly without xterm or modern cmd.exe/PowerShell. Ensure stream_isatty(STDOUT) is supported or fallback gracefully.
• Non-blocking input: The menu blocks on open()—avoid mixing with event loops (ReactPHP/Swoole). For async flows, defer long-running tasks to background processes or spawn threads.
• Disable items without breaking navigation: Use setDisabled(true) on options for context-aware UI (e.g., “Next step only if DB configured”). Users can still navigate over disabled items, but Enter does nothing.
• Custom prompts: Override default exit behavior (e.g., ? for help) by extending CliMenu and overriding handleKey(), or pre-pend addHelpItem() for standard help.
• Debugging callbacks: Wrap callbacks in try-catch and output to STDERR—the menu overwrites the screen, so errors vanish unless explicitly captured.
• Styling quirks: Some terminals render dark-on-dark text poorly. Always test with --ansi and check PHP_EOL differences across platforms—use PHPSchool\CliMenu\Terminal::getTerminal() for reliable auto-detection.