Add $escape parameter to addArg() to override escape setting per call

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## 1.0.2
 
- * Also escape single args, e.g. for filepaths on Windows
+ * Add `$escape` parameter to `addArg()` to override escaping settings per call
 
 ## 1.0.1
 

README.md

@@ -60,8 +60,8 @@ $command->addArg('--keys', array('key1','key2')
 
 ### Properties
 
- * `$escapeArgs': Whether to escape any argument passed through `addArg()`. Default is `true`.
- * `$escapeCommand`: Whether to escape the command passed to setCommand() or the constructor.
+ * `$escapeArgs`: Whether to escape any argument passed through `addArg()`. Default is `true`.
+ * `$escapeCommand`: Whether to escape the command passed to `setCommand()` or the constructor.
     This is only useful if `$escapeArgs` is `false`. Default is `false`.
  * `$procCwd`: The initial working dir passed to `proc_open()`. Default is `null` for current
     PHP working dir.
@@ -75,7 +75,7 @@ $command->addArg('--keys', array('key1','key2')
  * `setOptions($options)`: Set command options
     * `$options`: array of name => value options that should be applied to the object.
        You can also pass options that use a setter, e.g. you can pass a `command` option which
-       will be passed to setCommand().
+       will be passed to `setCommand().`
  * `setCommand($command)`: Set command
     * `$command`: The command or full command string to execute, like `gzip` or `gzip -d`.
        You can still call `addArg()` to add more arguments to the command. If `$escapeCommand` was
@@ -85,12 +85,14 @@ $command->addArg('--keys', array('key1','key2')
  * `setArgs($args)`: Set argument as string
     * `$args`: The command arguments as string. Note, that these will not get escaped!
  * `getArgs()`: The command arguments that where set through `setArgs()` or `addArg()`, as string
- * `addArg($key, $value=null)`: Add argument with correct escaping
+ * `addArg($key, $value=null, $escape=null)`: Add argument with correct escaping
     * `$key`: The argument key to add e.g. `--feature` or `--name=`. If the key does not end with
-       and `=`, the `$value` will be separated by a space, if any.
+       and `=`, the `$value` will be separated by a space, if any. Keys are not escaped unless
+       `$value` is null and `$escape` is `true`.
     * `$value`: The optional argument value which will get escaped if `$escapeArgs` is true.
        An array can be passed to add more than one value for a key, e.g. `addArg('--exclude', array('val1','val2'))`
        which will create the option "--exclude 'val1' 'val2'".
+    * `$escape`: If set, this overrides the `$escapeArgs` setting and enforces escaping/no escaping
  * `getOutput()`: The command output as string. Empty if none.
  * `getError()`: The error message, either stderr or internal message. Empty if none.
  * `getStdErr()`: The stderr output. Empty if none.

src/Command.php

@@ -165,28 +165,31 @@ public function getArgs()
     }
 
     /**
-     * @param string $key the argument key to add e.g. '--feature' or '--name='. If the key does not end with
-     * and '=', the $value will be separated by a space, if any
+     * @param string $key the argument key to add e.g. `--feature` or `--name=`. If the key does not end with
+     * and `=`, the $value will be separated by a space, if any. Keys are not escaped unless $value is null
+     * and $escape is `true`.
      * @param string|array|null $value the optional argument value which will get escaped if $escapeArgs is true.
-     * An array can be passed to add more than one value for a key, e.g. addArg('--exclude', array('val1','val2'))
-     * which will create the option "--exclude 'val1' 'val2'".
+     * An array can be passed to add more than one value for a key, e.g. `addArg('--exclude', array('val1','val2'))`
+     * which will create the option `--exclude 'val1' 'val2'`.
+     * @param bool|null $escape if set, this overrides the $escapeArgs setting and enforces escaping/no escaping
      * @return Command for method chaining
      */
-    public function addArg($key, $value=null)
+    public function addArg($key, $value = null, $escape = null)
     {
+        $doEscape = $escape!==null ? $escape : $this->escapeArgs;
         if ($value===null) {
-            // Escape single args, e.g. for filename args on Windows ("C:\Program Files\..")
-            $this->_args[] = $this->escapeArgs ? escapeshellarg($key) : $key;
+            // Only escape single arguments if explicitely requested
+            $this->_args[] = $escape ? escapeshellarg($key) : $key;
         } else {
             $separator = substr($key, -1)==='=' ? '' : ' ';
             if (is_array($value)) {
                 $params = array();
                 foreach ($value as $v) {
-                    $params[] = $this->escapeArgs ? escapeshellarg($v) : $v;
+                    $params[] = $doEscape ? escapeshellarg($v) : $v;
                 }
                 $this->_args[] = $key.$separator.implode(' ',$params);
             } else {
-                $this->_args[] = $key.$separator.($this->escapeArgs ? escapeshellarg($value) : $value);
+                $this->_args[] = $key.$separator.($doEscape ? escapeshellarg($value) : $value);
             }
         }
 

tests/CommandTest.php

@@ -64,10 +64,11 @@ public function testCanAddArguments()
         $command->addArg('--a');
         $command->addArg('--a', 'v');
         $command->addArg('--a', array("v'1",'v2','v3'));
-        $command->addArg('-b=','v');
+        $command->addArg('-b=','v', false);
         $command->addArg('-b=', array('v4','v5','v6'));
         $command->addArg('-c', '');
-        $this->assertEquals("--arg1=x '--a' --a 'v' --a 'v'\''1' 'v2' 'v3' -b='v' -b='v4' 'v5' 'v6' -c ''", $command->getArgs());
+        $command->addArg('some name', null, true);
+        $this->assertEquals("--arg1=x --a --a 'v' --a 'v'\''1' 'v2' 'v3' -b=v -b='v4' 'v5' 'v6' -c '' 'some name'", $command->getArgs());
     }
     public function testCanResetArguments()
     {
@@ -84,16 +85,17 @@ public function testCanDisableEscaping()
         $command->addArg('--a');
         $command->addArg('--a', 'v');
         $command->addArg('--a', array("v1",'v2','v3'));
-        $command->addArg('-b=','v');
+        $command->addArg('-b=','v', true);
         $command->addArg('-b=', array('v4','v5','v6'));
-        $this->assertEquals("--a --a v --a v1 v2 v3 -b=v -b=v4 v5 v6", $command->getArgs());
+        $command->addArg('some name', null, true);
+        $this->assertEquals("--a --a v --a v1 v2 v3 -b='v' -b=v4 v5 v6 'some name'", $command->getArgs());
     }
     public function testCanRunCommandWithArguments()
     {
         $command = new Command('ls');
         $command->addArg('-l');
         $command->addArg('-n');
-        $this->assertEquals("ls '-l' '-n'", $command->getExecCommand());
+        $this->assertEquals("ls -l -n", $command->getExecCommand());
         $this->assertTrue($command->execute());
     }
 
@@ -137,7 +139,7 @@ public function testCanCastToString()
         $command = new Command('ls');
         $command->addArg('-l');
         $command->addArg('-n');
-        $this->assertEquals("ls '-l' '-n'", (string)$command);
+        $this->assertEquals("ls -l -n", (string)$command);
     }
 
     // Proc