Console Ui Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require drinksco/console-ui-bundle
   yarn add @drinksco/console-ui
   

   Ensure WebpackEncoreBundle is configured in your Symfony app (default).

2. Enable Bundle: Add to config/bundles.php:

   DrinksCo\ConsoleUIBundle\DrinksCoConsoleUIBundle::class => ['all' => true],
   

3. First Use Case:

   • Create a command with UI support:

     use DrinksCo\ConsoleUIBundle\Attribute\ConsoleUI;
     use Symfony\Component\Console\Command\Command;
     use Symfony\Component\Console\Input\InputInterface;
     use Symfony\Component\Console\Output\OutputInterface;
     
     #[ConsoleUI]
     class MyCommand extends Command
     {
         protected function execute(InputInterface $input, OutputInterface $output): int
         {
             $output->writeln('Hello from UI!');
             return Command::SUCCESS;
         }
     }
     

   • Run the command via the UI by visiting /_console-ui (default route).

Implementation Patterns

Core Workflows

1. Command Execution:

   • Use the #[ConsoleUI] attribute to auto-register commands for UI access.
   • Supports argument/option input via the web interface (e.g., dropdowns, text fields).

2. Real-Time Output:

   • The UI streams command output in real-time using WebSockets (Symfony's Mercure or raw sockets).
   • Example: Logs, progress bars, or interactive prompts render dynamically.

3. Integration with Symfony:

   • Dependency Injection: Inject services into commands as usual.

     public function __construct(private MyService $service) {}
     

   • Event Listeners: Attach to console.command events for pre/post-processing.

     $event->getCommand()->setUiEnabled(true); // Enable UI for specific commands
     

4. Custom UI Components:

   • Extend the TypeScript web components (e.g., add a custom modal for prompts).
   • Override templates in templates/bundles/consoleui/ (e.g., command_list.html.twig).

5. Authentication:

   • Secure the /_console-ui route with Symfony’s security system:

     # config/routes.yaml
     _console_ui:
         path: /_console-ui
         controller: DrinksCo\ConsoleUIBundle\Controller\ConsoleUIController::index
         methods: [GET]
         security: true
     

Advanced Patterns

• Command Groups: Use Symfony’s #[Command] groups to categorize commands in the UI:

  #[Command(name: 'app:group:subcommand', group: 'app:group')]
  

• Async Execution: Offload long-running commands to a queue (e.g., Symfony Messenger) and poll results via the UI.

• Shared State: Pass data between the UI and command via Symfony’s ParameterBag or session:

  $input->getOption('ui-data'); // Parse JSON from the UI
  

Gotchas and Tips

Pitfalls

1. WebSocket Limits:

   • The bundle uses HTTP/1.1 WebSockets, which caps concurrent connections to 6 per domain.
   • Workaround: Use Mercure (Symfony’s pub/sub) or upgrade to HTTP/2 if available.

2. TypeScript Dependencies:

   • The UI relies on untested TypeScript components. Debug with:

     yarn build --watch
     

   • Tip: Fork the repo to extract the web component as an NPM package (see TODO).

3. Command Registration:

   • Commands must be registered as services. Use autoconfigure: true in config/services.yaml:

     services:
         _controllers:
             resource: ../src/Controller/
             autoconfigure: true
         _commands:
             resource: ../src/Command/
             tags: ['console.command']
             autoconfigure: true
     

4. Input Handling:

   • The UI sends arguments/options as a flat array. Validate on the command side:

     $input->getArgument('id') ?? throw new \InvalidArgumentException('ID required');
     

5. CORS Issues:

   • If accessing the UI from a different domain, configure CORS in Symfony’s firewall:

     # config/packages/security.yaml
     cors:
         paths:
             '^/_console-ui/':
                 allow_origin: ['*']
     

Debugging Tips

• Check WebSocket Connection: Use browser dev tools (Network tab) to verify WebSocket upgrades (ws:// or wss://).

  • Error: WebSocket connection failed → Check Symfony’s kernel.debug mode or server config.

• Log Output: Enable debug mode (APP_DEBUG=1) to see raw command output in Symfony’s log:

  tail -f var/log/dev.log
  

• UI Assets: Clear Encore assets after updates:

  yarn encore dev --watch
  

Extension Points

1. Custom Templates: Override the UI layout in templates/bundles/consoleui/base.html.twig.

2. Add Command Metadata: Use Symfony’s #[Command] attributes to enrich the UI:

   #[Command(
       description: 'Processes files (UI-friendly)',
       help: 'See <info>https://example.com</info> for details.'
   )]
   

3. Hook into UI Events: Listen for console.ui.command.execute events to modify behavior:

   use DrinksCo\ConsoleUIBundle\Event\ConsoleUIEvent;
   
   public function onCommandExecute(ConsoleUIEvent $event) {
       $event->setOutput(new StreamedOutput()); // Custom output handler
   }
   

4. Localization: Translate command descriptions/options using Symfony’s translation system:

   {{ 'app.command.description'|trans }}