Process Utilities

Purpose and Scope

This document covers the ProcessUtils class, which provides utilities for safely escaping shell arguments when executing external processes. The class handles platform-specific escaping requirements for both Windows and Unix-like systems, addressing known PHP bugs related to shell argument handling.

For information about other utility functions, see page 9.1 (Helper Functions). For general data manipulation utilities, see page 9.4 (Data Manipulation).

---

Overview

The ProcessUtils class is a static utility class that provides a single public method for escaping shell arguments in a cross-platform manner. It was originally adapted from Symfony 3 and addresses specific PHP bugs that affect shell argument escaping on different operating systems.

Feature	Description
Primary Method	escapeArgument() - Escapes strings for safe shell usage
Platform Support	Windows and Unix-like systems (Linux, macOS, BSD)
PHP Bug Fixes	Addresses PHP bugs #43784 and #49446
Origin	Adapted from Symfony 3 Process component

Sources: src/ProcessUtils.php1-71

---

System Architecture

The following diagram illustrates how ProcessUtils fits into the broader utilities ecosystem and its interaction with the operating system:

Diagram: ProcessUtils System Integration

This diagram shows how application code uses ProcessUtils to safely escape arguments before passing them to PHP's shell execution functions. The platform detection mechanism determines which escaping strategy to apply.

Sources: src/ProcessUtils.php20-58

---

Escaping Decision Flow

The following diagram illustrates the detailed logic flow within the escapeArgument() method:

Diagram: Argument Escaping Decision Flow

This flowchart illustrates the complete decision tree for escaping shell arguments, showing the divergent paths for Windows and Unix systems.

Sources: src/ProcessUtils.php20-58

---

Platform-Specific Behavior

Platform Detection

The ProcessUtils class uses PHP's DIRECTORY_SEPARATOR constant to detect the operating system. Windows systems use backslash (\) as the directory separator, while Unix-like systems use forward slash (/).

Sources: src/ProcessUtils.php26

Windows Escaping Strategy

Windows shell argument escaping is complex due to multiple factors:

Issue	Solution
Empty Arguments	Return "" (empty double quotes)
Double Quotes	Escape as \"
Environment Variables	Wrap %var% patterns as ^%"var"^% to prevent expansion
Trailing Backslashes	Double trailing backslashes to prevent quote escaping
Final Wrapping	Wrap entire argument in double quotes if necessary

The Windows implementation addresses PHP bugs #43784 (where escapeshellarg removes % characters) and #49446 (where escapeshellarg doesn't work correctly on Windows).

Escaping Process:

1. Check for empty string and return ""
2. Split argument by double quote characters
3. For each segment:
   • If it's a double quote: escape as \"
   • If surrounded by %: wrap as ^%"content"^% to prevent variable expansion
   • If ends with backslash: add extra backslash
   • Otherwise: add as-is and mark for quote wrapping
4. Wrap final result in double quotes if needed

Sources: src/ProcessUtils.php26-54

Unix/Linux Escaping Strategy

Unix-like systems use a simpler escaping strategy based on single quotes:

Approach	Implementation
Quote Wrapping	Wrap entire argument in single quotes
Quote Escaping	Replace ' with '\'' (close quote, escaped quote, open quote)

The Unix implementation is straightforward: wrap the argument in single quotes and escape any existing single quotes by ending the quoted string, adding an escaped quote, and reopening the quoted string.

Formula: ' + str_replace("'", "'\\''", $argument) + '

Sources: src/ProcessUtils.php57

---

API Reference

ProcessUtils::escapeArgument()

Escapes a string to be used as a shell argument, handling platform-specific requirements.

Parameters:

• $argument (string) - The argument to escape

Returns:

• (string) - The safely escaped argument

Platform Behavior:

Platform	Escaping Method	Example Input	Example Output
Windows	Double quotes with special character handling	hello world	"hello world"
Windows	Environment variable protection	%PATH%	^%"PATH"^%
Windows	Quote escaping	say "hello"	"say \"hello\""
Unix/Linux	Single quotes with quote escaping	hello world	'hello world'
Unix/Linux	Quote escaping	it's working	'it'\''s working'

Sources: src/ProcessUtils.php20-58

ProcessUtils::isSurroundedBy()

Helper method that checks if a string is surrounded by a specific character (both first and last characters match).

Parameters:

• $arg (string) - The string to check
• $char (string) - The character to look for

Returns:

• (bool) - True if the string has length > 2 and starts and ends with the character

Usage: Used internally to detect environment variable patterns like %PATH% on Windows.

Sources: src/ProcessUtils.php67-70

---

Code Entity Mapping

The following diagram maps conceptual components to actual code entities:

Diagram: Concept-to-Code Mapping

This diagram connects high-level concepts to their concrete implementations in the codebase, facilitating code navigation.

Sources: src/ProcessUtils.php1-71

---

Usage Examples

Basic Usage

Handling Special Characters

Environment Variable Protection (Windows)

Empty Arguments

Sources: src/ProcessUtils.php20-58

---

Security Considerations

Shell Injection Prevention

The primary purpose of ProcessUtils::escapeArgument() is to prevent shell injection attacks. Always escape user-supplied input before passing it to shell execution functions:

Known PHP Bugs Addressed

Bug ID	Description	How ProcessUtils Fixes It
#43784	escapeshellarg() removes % characters	Custom escaping preserves % with proper protection
#49446	escapeshellarg() doesn't work on Windows	Platform-specific logic for Windows command line

Sources: src/ProcessUtils.php22-25

Best Practices

1. Always Escape User Input: Never pass unescaped user input to shell commands
2. Use Full Paths: Combine with full executable paths to prevent PATH manipulation
3. Validate First: Validate input format before escaping (defense in depth)
4. Avoid Shell When Possible: Use proc_open() with direct argument arrays when feasible

---

Edge Cases and Special Handling

Windows-Specific Edge Cases

Input Pattern	Handling	Reason
Empty string ("")	Returns ""	Windows requires quoted empty arguments
Ends with backslash (path\)	Doubles backslash (path\\)	Prevents quote escaping
Contains %VAR%	Wraps as ^%"VAR"^%	Prevents environment variable expansion
Contains double quotes	Escapes as \"	Prevents command injection

Unix-Specific Edge Cases

Input Pattern	Handling	Reason
Contains single quote (')	Replaces with '\''	Breaks out and escapes quote
Empty string	Returns ''	Unix requires empty quotes for empty arguments

Sources: src/ProcessUtils.php27-57

---

Implementation Details

Windows Escaping Algorithm

The Windows escaping implementation uses a character-by-character parsing approach:

Step-by-step Process:

1. Empty Check src/ProcessUtils.php27-29

   • Return "" for empty strings

2. Split by Quotes src/ProcessUtils.php34

   • Use preg_split() with PREG_SPLIT_DELIM_CAPTURE to preserve quotes

3. Process Each Part src/ProcessUtils.php34-48

   • Escape double quotes as \"
   • Protect %var% patterns from expansion
   • Handle trailing backslashes

4. Final Wrapping src/ProcessUtils.php50-52

   • Wrap in quotes if needed based on $quote flag

Unix Escaping Algorithm

The Unix escaping is much simpler:

Single-step Process:

1. Replace all ' with '\''
2. Wrap entire string in single quotes

This works because in Unix shells, single-quoted strings are literal (no variable expansion), and the only way to include a single quote is to end the quoted string, add an escaped single quote, and start a new quoted string.

Sources: src/ProcessUtils.php57

---

Related Classes and Functions

While ProcessUtils is a standalone utility, it may be used in conjunction with:

• PHP's native exec(), shell_exec(), system(), proc_open() functions
• Queue job execution that spawns processes
• Scheduled task runners that execute shell commands
• Custom process management implementations

For broader system utilities, see page 9.1 (Helper Functions). For environment-specific configurations, see page 9.5 (Environment Configuration).

Sources: src/ProcessUtils.php1-71