Symfony Web Command Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require devture/symfony-web-command-bundle
   

   Add to config/bundles.php:

   Devture\Bundle\WebCommandBundle\DevtureWebCommandBundle::class => ['all' => true],
   

2. Configuration Add to config/packages/devture_web_command.yaml:

   devture_web_command:
       auth_token: '%env(DEVTURE_WEB_COMMAND_AUTH_TOKEN)%'
       forced_uri: '%env(DEVTURE_WEB_COMMAND_FORCED_URI)%'
   

   Set environment variables in .env:

   DEVTURE_WEB_COMMAND_AUTH_TOKEN="$(pwgen -Bsv1 64)"
   DEVTURE_WEB_COMMAND_FORCED_URI="https://your-app.com"
   

3. First Use Case Trigger a command via HTTP:

   curl -X POST -H "Authorization: Bearer $DEVTURE_WEB_COMMAND_AUTH_TOKEN" http://your-app/web-command/execute/your:command
   

Implementation Patterns

Workflows

1. Cron Job Replacement Replace direct cron calls with HTTP requests:

   * * * * * curl -sS -X POST -H "Authorization: Bearer $TOKEN" http://app/web-command/execute/app:task
   

2. API-Driven Command Execution Build a frontend UI to trigger commands securely (e.g., admin dashboard buttons).

3. Dynamic Command Arguments Pass arguments via query params or JSON body:

   curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"arg1": "value1"}' http://app/web-command/execute/app:command
   

4. Output Handling Capture command output via HTTP response (default) or redirect to a file:

   devture_web_command:
       output_file: '%kernel.project_dir%/var/web-command.log'
   

Integration Tips

• Symfony Messenger: Use the bundle with Symfony Messenger for async command execution.
• Laravel Adaptation: Wrap the bundle in a Laravel package (e.g., spatie/laravel-web-command) for seamless integration.
• Logging: Log all command executions via Symfony’s monolog or Laravel’s log channel.
• Rate Limiting: Combine with Symfony’s rate_limiter to prevent abuse.

Gotchas and Tips

Pitfalls

1. Authentication Leaks

   • Never expose DEVTURE_WEB_COMMAND_AUTH_TOKEN in client-side code. Use server-side proxies or environment variables strictly.
   • Rotate tokens periodically via environment management tools (e.g., Laravel Envoy, Ansible).

2. Forced URI Mismatches

   • If forced_uri is misconfigured, generated URLs (e.g., for email links) may break. Test locally with http://localhost and update to production URI.
   • Leave forced_uri empty if commands don’t generate URLs (e.g., cache:clear).

3. Command Output Size

   • Large outputs (e.g., debug:container) may hit PHP’s max_execution_time or HTTP limits. Stream output or paginate results:

     devture_web_command:
         output_stream: true
     

4. CSRF Protection

   • The bundle doesn’t include CSRF protection by default. Add Symfony’s csrf_token middleware if needed:

     # config/packages/security.yaml
     firewalls:
         main:
             csrf_protection: true
     

Debugging

• 403 Forbidden: Verify auth_token matches exactly (case-sensitive) and is passed in the Authorization header.
• 500 Errors: Check Symfony’s var/log/dev.log for command-specific exceptions. Wrap commands in try-catch blocks for graceful failures.
• Missing Commands: Ensure commands are autowired (e.g., tagged as console.command) and the bundle is loaded before the command.

Extension Points

1. Custom Authentication Override the Devture\Bundle\WebCommandBundle\Security\Authenticator to integrate with Symfony’s security system:

   // src/Security/CustomAuthenticator.php
   use Devture\Bundle\WebCommandBundle\Security\Authenticator as BaseAuthenticator;
   
   class CustomAuthenticator extends BaseAuthenticator {
       public function supports($token): bool {
           // Custom logic (e.g., JWT, OAuth)
       }
   }
   

2. Command Whitelisting Restrict accessible commands via YAML:

   devture_web_command:
       allowed_commands:
           - 'app:safe-command'
           - 'app:another-safe-command'
   

3. Event Listeners Hook into command execution via Symfony events:

   // src/EventListener/WebCommandListener.php
   use Devture\Bundle\WebCommandBundle\Event\CommandExecuteEvent;
   
   class WebCommandListener {
       public function onCommandExecute(CommandExecuteEvent $event) {
           if ($event->getCommandName() === 'app:critical') {
               $event->stopPropagation(); // Block execution
           }
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\WebCommandListener:
           tags:
               - { name: kernel.event_listener, event: devture.web_command.execute, method: onCommandExecute }