Server Shell Bundle Laravel Package

Getting Started

• Install via Composer: composer require tourze/server-shell-bundle. For Laravel, you may need to manually register the bundle’s service provider or use a Symfony kernel bridge—check the package README for framework-specific instructions.
• First look at the bundle’s README.md and Resources/config/ to understand available services and routes. The package likely exposes a shell command runner and/or a web terminal endpoint.
• Minimal first use case: create an authenticated admin route that executes a whitelisted diagnostic command (e.g., php artisan about or df -h) and displays the output. This validates wiring without exposing dangerous commands.
• Note: release 1.0.1 is a patch release (only a changelog link). No breaking changes or new features are documented, so treat it as a bug‑fix update. Review the diff between 1.0.0 and 1.0.1 to confirm.

Implementation Patterns

• Service wrapper: Inject the bundle’s command runner service into your own Laravel service or controller. Wrap execution in a try/catch and return structured output (stdout, stderr, exit code).
• Artisan command integration: Create an Artisan command that delegates to the bundle for running server maintenance scripts. This keeps day‑to‑day operations inside Laravel’s CLI.
• Whitelist‑based execution: Build a config array of allowed commands (config/shell_commands.php) and validate against it before calling the runner. Use this for deploy hooks, cache clears, or log tailing.
• Queue for long‑running commands: Dispatch a job that uses the runner and stores results in cache or a database table. Poll from a dashboard.
• Testing: Use Symfony’s Process mock or the bundle’s test doubles (if provided) to simulate command output. For Laravel, bind a fake runner in the container during tests.
• Upgrade workflow: Since 1.0.1 is a patch, run composer update tourze/server-shell-bundle and re‑run your test suite. Keep an eye on the GitHub compare link for any hidden changes.

Gotchas and Tips

• Framework mismatch: This is a Symfony bundle. Laravel does not natively auto‑discover Symfony bundles. You may need to instantiate services manually or use a compatibility layer. Test thoroughly.
• Security first: Never expose arbitrary shell execution. Always whitelist commands, require authentication/authorization, and consider running under a restricted user. The bundle may not provide built‑in access control.
• Command injection: Sanitize any user‑supplied arguments. Prefer fixed command strings or use escapeshellarg.
• Config quirks: Look for server_shell.yaml or similar config files. In Laravel, you may need to publish/adapt configuration manually.
• Debugging: Enable verbose logging (-vvv in Symfony, or Laravel’s Log::debug around the runner). Check storage/logs/laravel.log for process errors.
• Extension points: The bundle likely exposes events or a command registry. Use these to add custom commands or intercept execution without forking the package.
• Sparse changelog: 1.0.1 provides no details beyond a compare link. If you rely on this package in production, pin the version ("tourze/server-shell-bundle": "1.0.1") and review the GitHub diff before upgrading further.