Console Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require coresphere/console-bundle
   

   Ensure your php version in composer.json is 5.5+ (not overridden by config.platform.php).

2. Register Bundle: Add to AppKernel.php under dev/test environments:

   $bundles[] = new CoreSphere\ConsoleBundle\CoreSphereConsoleBundle();
   

3. Add Route: Include in routing_dev.yml:

   _console:
       resource: "@CoreSphereConsoleBundle/Resources/config/routing.yml"
       prefix:   /console
   

4. Access Console: Visit /console in your browser (dev environment only). Authenticate via Symfony’s security layer (if configured).

First Use Case: Running Commands via UI

• Example: Clear cache without CLI access:
  1. Navigate to /console.
  2. Type cache:clear in the input field.
  3. Press Enter to execute.
  • Output: Colored, formatted results appear in the browser (e.g., success/failure messages).

Implementation Patterns

Workflows

1. Command Execution:

   • Autocomplete: Type doctrine: → Bundle suggests doctrine:schema:update, doctrine:migrations:....
   • History: Commands persist via localStorage (per-browser).
   • Arguments: Pass flags/args directly (e.g., cache:clear --no-warmup).

2. Integration with Symfony Security:

   • Extend CoreSphere\ConsoleBundle\Security\ConsoleAuthenticator to enforce role-based access (e.g., ROLE_ADMIN).
   • Example:

     # security.yml
     access_control:
         - { path: ^/console, roles: ROLE_ADMIN }
     

3. Custom Commands:

   • Create a command (e.g., app/Command/MyCommand.php) and tag it with console.command.
   • It automatically appears in the /console UI without extra config.

4. Output Handling:

   • Colors: ANSI escape codes render as browser-friendly colors (e.g., red for errors).
   • Tables: Use Symfony’s Table component in commands—outputs as HTML tables.

Advanced Patterns

• Command Groups: Organize commands under tabs (e.g., "Doctrine," "Cache") by prefixing names (e.g., doctrine:...). Tip: Use Command classes with @Route annotations for custom grouping.

• API Access: Disable the UI and expose commands via HTTP by:

  1. Creating a controller to parse GET/POST params.
  2. Using Symfony\Component\Console\Application to execute commands programmatically. Example:

  $application = new Application();
  $application->find('cache:clear')->run(new ArgumentInput([]), new ConsoleOutput());
  

• Logging: Redirect console output to Symfony’s logger:

  $output = new StreamOutput(fopen('php://temp', 'w+'));
  $logger = new ConsoleLogger($output);
  $application->setLogger($logger);
  

Gotchas and Tips

Pitfalls

1. Environment Restriction:

   • Bundle only loads in dev/test environments. Forgetting to register it in AppKernel causes 404s.
   • Fix: Double-check registerBundles() and routing_dev.yml.

2. Security Risks:

   • No built-in auth: Anyone with browser access can run commands. Always pair with Symfony’s security:

     # security.yml
     providers:
         console:
             entity: { class: AppBundle\Entity\User }
     firewalls:
         console:
             pattern: ^/console
             form_login: ~
     

   • Tip: Use ROLE_SUPER_ADMIN for sensitive commands.

3. Output Formatting:

   • ANSI Colors: Some terminals/browsers misrender colors. Test in Chrome/Firefox.
   • Workaround: Use HTML <span> tags in output for critical cases.

4. Command History:

   • History is browser-local (not shared across devices). For shared history, implement a backend service (e.g., Redis).

5. Performance:

   • Long-running commands (e.g., doctrine:migrations:migrate) may time out in the browser.
   • Solution: Use AJAX polling or WebSockets for real-time output.

Debugging Tips

1. 404 Errors:

   • Verify:
     • Bundle is registered in AppKernel.
     • Route is in routing_dev.yml.
     • Environment is dev/test.

2. Blank Page:

   • Check Symfony’s debug:router for route conflicts.
   • Ensure twig bundle is loaded (UI uses Twig templates).

3. Command Not Found:

   • Confirm the command is tagged console.command in its service definition:

     services:
         app.my_command:
             class: AppBundle\Command\MyCommand
             tags:
                 - { name: console.command }
     

4. Output Issues:

   • Disable caching in the browser (Ctrl+F5) to see real-time updates.
   • For malformed output, inspect the raw command via CLI first.

Extension Points

1. Custom UI:

   • Override Twig templates in app/Resources/CoreSphereConsoleBundle/views/ (e.g., default/index.html.twig).
   • Example: Add a custom header or footer.

2. Command Filtering:

   • Extend CoreSphere\ConsoleBundle\Command\ConsoleCommand to hide/show commands dynamically:

     public function isEnabled()
     {
         return $this->getApplication()->getKernel()->getEnvironment() === 'dev';
     }
     

3. Output Formatting:

   • Subclass CoreSphere\ConsoleBundle\Output\BrowserOutput to modify rendering:

     class CustomBrowserOutput extends BrowserOutput
     {
         protected function getStyle($code)
         {
             // Customize color mappings
             return parent::getStyle($code);
         }
     }
     

   • Register as a service with the console.output tag.

4. API Endpoint:

   • Create a custom route to execute commands via HTTP:

     // src/Controller/ConsoleController.php
     public function executeCommand(Request $request)
     {
         $command = $this->get('console')->find($request->query->get('command'));
         $command->run(new ArgumentInput([]), new StreamOutput(fopen('php://temp', 'w+')));
         return new Response("Done");
     }