- Can I use this package to replace all `exec()` and `shell_exec()` calls in my Laravel app?
- Yes, this package is designed to replace raw shell calls with a safer, more maintainable API. It’s ideal for Laravel tasks like running Artisan commands, integrating external tools (e.g., Git, Docker), or executing background jobs. However, audit your existing CLI calls first to ensure compatibility, especially for user-provided input.
- How do I handle errors or timeouts when running terminal commands in Laravel queues?
- The package includes built-in timeout handling and exit code validation. For Laravel queues, wrap `Terminal::run()` in a try-catch block to log failures via Laravel’s exception handler (e.g., Sentry) or retry transient errors. Example: `try { Terminal::run('git pull')->timeout(30); } catch (TerminalException $e) { Log::error($e); }`.
- Does this package work with Laravel’s Artisan commands or only standalone PHP scripts?
- It works seamlessly with both. You can use it to execute Artisan commands programmatically (e.g., `Terminal::run('php artisan migrate')->stdout()`) or integrate CLI tools directly in your Laravel app. The fluent API reduces boilerplate compared to `Artisan::call()` for complex workflows.
- How do I mock terminal commands for Laravel unit tests?
- The package supports mocking via interfaces or dependency injection. Use Laravel’s `MockerTrait` or Mockery to fake `Terminal` instances. For example, mock `Terminal::run()` to return predefined output in tests, ensuring your logic handles success/failure cases without hitting the shell. Check the package’s `TerminalInterface` for mocking hooks.
- Will this package work in Laravel Forge/Valet environments, or is it server-only?
- It works in all Laravel environments, including Forge, Valet, and shared hosting—*as long as shell access is enabled*. For shared hosting, test commands like `Terminal::run('php artisan optimize')` to confirm permissions. Avoid user-provided input in commands to prevent shell injection risks.
- Can I stream real-time output (e.g., `git pull` logs) to a Livewire/Inertia dashboard?
- Yes! Use the `stream()` method to capture live output and emit events to Livewire or Inertia. Example: `Terminal::run('git pull')->stream(function ($line) { Livewire::emit('log', $line); })`. This is perfect for deployment dashboards or CLI-driven workflows with UI feedback.
- What Laravel and PHP versions does this package support?
- The package is compatible with **Laravel 10/11** and requires **PHP 8.1+**, aligning with Laravel’s current LTS support. Check the `composer.json` constraints for exact version requirements. If using older Laravel versions, verify Symfony Process compatibility.
- How do I customize environment variables or working directories for commands?
- Use the `env()` and `dir()` methods to set environment variables or working directories. Example: `Terminal::run('composer install')->env(['COMPOSER_AUTH' => $auth])->dir(storage_path('app'))`. For Laravel-specific vars (e.g., `APP_ENV`), extend the `Terminal` class or use a service provider to preload them.
- Are there security risks with dynamic command arguments (e.g., user input)?
- The package escapes arguments by default, but **always validate user-provided input** before passing it to commands. Avoid dynamic paths or arguments in production. For extra safety, use a whitelist of allowed commands or implement a custom `CommandBuilder` to sanitize inputs.
- What alternatives exist for running terminal commands in Laravel, and why choose this package?
- Alternatives include raw `exec()`, `shell_exec()`, or Symfony Process directly. This package stands out for its **Laravel-friendly API**, built-in mocking support, and features like streaming/output capture. It’s more maintainable than raw calls and integrates cleanly with Laravel’s ecosystem (e.g., queues, Artisan, Livewire).