Add structured Command execution with composition and redirects

README.md

@@ -17,6 +17,7 @@ composer require utopia-php/console
 require_once __DIR__.'/vendor/autoload.php';
 
 use Utopia\Console;
+use Utopia\Command;
 
 Console::success('Ready to work!');
 
@@ -28,7 +29,11 @@ if ($answer !== 'y') {
 }
 
 $output = '';
-$exitCode = Console::execute('php -r "echo \"Hello\";"', '', $output, 3);
+$stderr = '';
+$command = new Command(PHP_BINARY)
+    ->option('-r', 'echo "Hello";');
+
+$exitCode = Console::execute($command, '', $output, $stderr, 3);
 
 Console::log("Command returned {$exitCode} with: {$output}");
 ```
@@ -45,17 +50,65 @@ Console::error('Red log');        // stderr
 
 ### Execute Commands
 
-`Console::execute()` returns the exit code and writes the combined stdout/stderr output into the third argument. Pass a timeout (in seconds) to stop long-running processes and an optional progress callback to stream intermediate output.
+`Console::execute()` returns the exit code and writes stdout and stderr into the referenced output variables. Pass a timeout (in seconds) to stop long-running processes and an optional progress callback to stream intermediate output. Prefer `Utopia\Command` or argv arrays when you want structured command building.
 
 ```php
+$command = new Command(PHP_BINARY)
+    ->option('-r', 'fwrite(STDOUT, "success\\n");');
+
 $output = '';
 $input = '';
-$exitCode = Console::execute('>&1 echo "success"', $input, $output, 3);
+$stderr = '';
+$exitCode = Console::execute($command, $input, $output, $stderr, 3);
 
 echo $exitCode;  // 0
 echo $output;    // "success\n"
 ```
 
+### Build Commands
+
+Use `flag()` for switches without a value, `option()` for keys that take a value, and `argument()` for positional arguments.
+
+```php
+$command = new Command('tar')
+    ->flag('-cz')
+    ->option('-f', 'archive.tar.gz')
+    ->option('-C', '/tmp/project')
+    ->argument('.');
+```
+
+### Compose Commands
+
+Use the static helpers when you need shell operators such as pipes, `&&`, `||`, grouping, or redirects.
+
+```php
+$pipeline = Command::pipe(
+    new Command('ps')->flag('-ef'),
+    new Command('grep')->argument('php-fpm'),
+    new Command('wc')->flag('-l'),
+);
+
+$deploy = Command::and(
+    Command::group(
+        Command::or(
+            new Command('build'),
+            new Command('build:fallback'),
+        )
+    ),
+    new Command('publish'),
+);
+
+$logs = Command::appendStdout(
+    Command::pipe(
+        new Command('cat')->argument('app.log'),
+        new Command('grep')->argument('ERROR'),
+    ),
+    'errors.log',
+);
+```
+
+Plain commands execute in argv mode. Composed, grouped, and redirected commands execute through shell syntax.
+
 ### Create a Daemon
 
 Use `Console::loop()` to build daemons without tight loops. The helper sleeps between iterations and periodically triggers garbage collection.
@@ -72,7 +125,7 @@ Console::loop(function () {
 
 ## System Requirements
 
-Utopia Console requires PHP 7.4 or later. We recommend using the latest PHP version whenever possible.
+Utopia Console requires PHP 8.0 or later. We recommend using the latest PHP version whenever possible.
 
 ## License
 

composer.json

@@ -14,7 +14,8 @@
         "psr-4": {"Utopia\\": "src/"}
     },
     "require": {
-        "php": ">=8.0"
+        "php": ">=8.0",
+        "utopia-php/validators": "^0.1.0"
     },
     "require-dev": {
         "phpunit/phpunit": "^9.3",