adachsoft/command-executor-lib

A robust PHP library for executing system commands with timeout support, output handling, and process management

v1.0.2 2025-09-22 05:43 UTC

Requires

• php: ^8.3

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^11.0

MIT

• Arkadiusz Adach

• php
• cli
• process
• command
• shell
• timeout
• executor

README

A robust PHP library for executing system commands with timeout support, output handling, and process management.

Features

• Simple API - Easy to use interface for command execution
• Error Handling - Comprehensive exception handling with detailed error information
• Process Management - Full control over command execution environment
• Output Capture - Captures both stdout and stderr streams
• Environment Variables - Support for custom environment variables
• Working Directory - Ability to set custom working directory
• PHP 8.3+ - Modern PHP with strict types and full type safety

Installation

Install via Composer:

composer require adachsoft/command-executor-lib

Requirements

• PHP 8.3 or higher
• No external system dependencies

Quick Start

Basic Usage

<?php

use AdachSoft\CommandExecutorLib\SimpleCommandExecutor;

$executor = new SimpleCommandExecutor();

// Execute a simple command
try {
    $output = $executor->execute('ls -la');
    echo $output;
} catch (CommandExecutorException $e) {
    echo "Error: " . $e->getMessage();
}

Advanced Usage

Execute with Environment Variables

<?php

use AdachSoft\CommandExecutorLib\SimpleCommandExecutor;

$executor = new SimpleCommandExecutor();

// Set custom environment variables
$env = [
    'PATH' => '/usr/local/bin:/usr/bin:/bin',
    'DEBUG' => 'true'
];

$output = $executor->execute('echo $DEBUG', $env);
// Output: true

Execute in Specific Directory

<?php

use AdachSoft\CommandExecutorLib\SimpleCommandExecutor;

$executor = new SimpleCommandExecutor();

// Execute command in specific directory
$output = $executor->execute('ls -la', [], '/var/www');

Handle Command Failures

<?php

use AdachSoft\CommandExecutorLib\SimpleCommandExecutor;
use AdachSoft\CommandExecutorLib\CommandExecutorException;

$executor = new SimpleCommandExecutor();

try {
    $output = $executor->execute('nonexistent-command');
} catch (CommandExecutorException $e) {
    echo "Command failed: " . $e->getMessage() . "\n";
    echo "Exit code: " . $e->getExitCode() . "\n";
    echo "Output: " . $e->getCommandOutput() . "\n";
}

Get Exit Code Without Exception

<?php

use AdachSoft\CommandExecutorLib\SimpleCommandExecutor;

$executor = new SimpleCommandExecutor();

// Execute command and get both output and exit code
$result = $executor->executeWithExitCode('ls /nonexistent');

if ($result['exitCode'] === 0) {
    echo "Success: " . $result['output'];
} else {
    echo "Failed with code " . $result['exitCode'] . ": " . $result['output'];
}

Real-World Examples

Git Operations

<?php

use AdachSoft\CommandExecutorLib\SimpleCommandExecutor;

$executor = new SimpleCommandExecutor();

// Get current git branch
$branch = trim($executor->execute('git rev-parse --abbrev-ref HEAD'));
echo "Current branch: $branch";

// Check git status
$status = $executor->execute('git status --porcelain', [], '/path/to/project');
if (empty($status)) {
    echo "Working directory is clean";
} else {
    echo "Uncommitted changes detected";
}

File Operations

<?php

use AdachSoft\CommandExecutorLib\SimpleCommandExecutor;

$executor = new SimpleCommandExecutor();

// Create backup
$backupDir = '/backups/' . date('Y-m-d');
$executor->execute("mkdir -p $backupDir");
$executor->execute("cp -r /var/www $backupDir/");

// Check disk usage
$usage = $executor->execute('df -h / | tail -1');
echo "Disk usage: $usage";

Docker Operations

<?php

use AdachSoft\CommandExecutorLib\SimpleCommandExecutor;

$executor = new SimpleCommandExecutor();

// Build Docker image
$executor->execute('docker build -t myapp:latest .', [], '/path/to/dockerfile');

// Run container
$result = $executor->executeWithExitCode('docker run --rm myapp:latest');
if ($result['exitCode'] === 0) {
    echo "Container executed successfully";
}

API Reference

CommandExecutorInterface

The main interface that all command executors must implement.

Methods

• execute(string $command, array $env = [], ?string $cwd = null): string
• executeWithExitCode(string $command, array $env = [], ?string $cwd = null): array

SimpleCommandExecutor

Default implementation using PHP's proc_open().

Constructor

$executor = new SimpleCommandExecutor();

CommandExecutorException

Exception thrown when command execution fails.

Methods

• getCommandOutput(): ?string - Returns the command output
• getExitCode(): ?int - Returns the exit code
• fromCommandFailure() - Static factory method for creating exceptions

Error Handling

The library provides comprehensive error handling through CommandExecutorException:

<?php

try {
    $output = $executor->execute('invalid-command');
} catch (CommandExecutorException $e) {
    // Handle specific error cases
    switch ($e->getExitCode()) {
        case 127:
            echo "Command not found";
            break;
        case 126:
            echo "Permission denied";
            break;
        default:
            echo "Command failed: " . $e->getMessage();
    }
}

Testing

Run the test suite:

composer test

Run with coverage:

composer test-coverage

Run code quality checks:

composer quality

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run quality checks (composer quality)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a detailed list of changes.