Windows command-line formatter
A PHP function to escape command-line arguments, which replaces
escapeshellarg with more robust methods for both Windows and non-Windows platforms. Install from Packagist and use it like this:
$escaped = Winbox\Args::escape($argument);
Alternatively, you can just copy the code into your own project (but please keep the license attribution and documentation link).
The following transformations are made:
- Double-quotes are escaped with a backslash, with any preceeding backslashes doubled up.
- The argument is only enclosed in double-quotes if it contains whitespace or is empty.
- Trailing backslashes are doubled up if the argument is enclosed in double-quotes.
See How Windows parses the command-line if you would like to know why.
By default, cmd.exe meta characters are also escaped:
- by caret-escaping the transformed argument (if it contains internal double-quotes or
- or by enclosing the argument in double-quotes.
There are some limitations:
- If cmd is started with DelayedExpansion enabled,
!...!syntax could expand environment variables.
- If the program name requires caret-escaping and contains whitespace, cmd will not recognize it.
- If an argument contain a newline
\ncharacter, this will not be escaped.
The argument is enclosed is single-quotes, with internal single-quotes escaped.
Yup. An entire repo for a tiny function. However, it needs quite a lot of explanation because:
- the command-line parsing rules in Windows are not immediately obvious.
- PHP generally uses cmd.exe to execute programs and this applies a different set of rules.
- there is no simple solution.
Full details explaining the different parsing rules, potential pitfalls and limitations can be found in the Wiki.
Winbox-Args is licensed under the MIT License - see the LICENSE file for details.