Process Laravel Package

Product Decisions This Supports

• CLI Tool Development: Enables building robust, maintainable PHP CLI tools (e.g., internal DevOps utilities, automation scripts) with structured process management, reducing reliance on fragile exec() calls.
• Laravel Background Jobs: Facilitates non-blocking process execution in queue workers (e.g., triggering Docker builds, running batch scripts) while maintaining observability via exit codes and output streams.
• Build vs. Buy: Justifies avoiding reinventing process handling (e.g., no need for Symfony’s Process if a lightweight, framework-agnostic solution suffices) and reduces technical debt.
• Roadmap for Observability: Supports future features like process logging, error recovery, and retries by providing standardized access to stdout/stderr and exit codes, which can be integrated with Laravel’s monitoring tools.
• Security/Compliance: Simplifies safe process execution (e.g., input validation, environment isolation) for auditable workflows, critical for regulated industries or high-security applications.
• Microservices Integration: Enables PHP services to interact with external systems (e.g., calling REST APIs via curl, invoking Kubernetes commands) without coupling to a full framework like Symfony.

When to Consider This Package

• Avoid if:
  • You need advanced process chaining (e.g., pipes, tee, or complex I/O redirection) → Use symfony/process or bacon/bacon-qr.
  • Your use case requires Windows-specific features (e.g., job objects, handles) → Evaluate phpseclib or native extensions like proctitle.
  • You’re building a GUI application or need real-time process monitoring (e.g., CPU/memory) → Look at system extensions or sysprocess.
  • You require built-in retry logic or circuit breakers → Consider wrapping this package with a custom retry layer or using spatie/laravel-queue-job.
  • You need process pooling or concurrent execution → Combine with Laravel Queues or a task runner like react/promise.
• Use if:
  • You want a lightweight, framework-agnostic alternative to Symfony’s Process for Laravel or standalone scripts.
  • Your team prioritizes explicit control over process lifecycle (e.g., timeouts, environment variables, working directories).
  • You’re integrating with external tools (e.g., git, docker, curl) in CLI tools, Artisan commands, or queue workers.
  • You need structured output handling (e.g., parsing stdout/stderr for logging or validation) without reinventing the wheel.
  • Your roadmap includes observability (e.g., logging process metrics, capturing errors for debugging).

How to Pitch It (Stakeholders)

For Executives: *"This package lets us automate system interactions (e.g., running scripts, calling APIs, managing containers) from PHP safely and scalably—without locking us into a heavy framework. It’s perfect for:

• Internal tools (e.g., CI/CD hooks, database migrations) that need to run external commands reliably.
• Cost savings by avoiding custom scripts or third-party SaaS for simple automation.
• Future-proofing our stack with a standardized way to handle processes, making it easier to add logging, retries, or security checks later. Think of it as ‘exec() for grown-ups’: more control, less risk, and no vendor lock-in."*

For Engineering: *"Replace messy shell_exec() or exec() calls with a type-safe, non-blocking API for spawning processes. Key wins:

• Consistent API: Always check $process->isSuccessful() instead of hacking exit codes (=== 0).
• Streaming Output: Capture stdout/stderr incrementally for real-time logging (e.g., progress bars in CLI tools).
• Framework-Agnostic: Works in Laravel commands, standalone scripts, or even Symfony apps—no lock-in.
• MIT-Licensed & Lightweight: No bloat; just what you need for process management.

Example: Replace this fragile code:

$output = shell_exec('git pull');
if (strpos($output, 'Already up to date') === false) { ... }

With this:

$process = new Process(['git', 'pull']);
$process->run();
if (!$process->isSuccessful()) {
    throw new RuntimeException($process->getErrorOutput());
}

Clearer, safer, and testable. Let’s use this for:

• CLI tools (e.g., php artisan deploy).
• Queue workers (e.g., running docker build in background jobs).
• API integrations (e.g., calling external services via curl)."*

For DevOps/SRE: *"This gives us predictable, auditable process execution in PHP, which is critical for:

• Security: Validating inputs and environment variables to prevent command injection.
• Reliability: Setting timeouts and handling exit codes properly (no more silent failures).
• Debugging: Capturing stderr for logs and monitoring (integrates with Laravel’s logging stack). We can standardize how we run external commands across the org—whether in scripts, Artisan commands, or queue jobs."*