winbox/args

Windows command-line formatter

v1.1.1 2019-11-07 17:17 UTC

Requires

• php: ^5.3.2 || ^7.0 || ^8.0

Requires (Dev)

• phpunit/phpunit: ^4.8.35 || ^5.7 || 6.5 - 8

MIT

• John Stevenson

• command
• windows
• Escape

README

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).

What it does on the Windows platform

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 %...% syntax).
• or by enclosing the argument in double-quotes.

There are some limitations:

1. If cmd is started with DelayedExpansion enabled, !...! syntax could expand environment variables.
2. If the program name requires caret-escaping and contains whitespace, cmd will not recognize it.
3. If an argument contain a newline \n character, this will not be escaped.

See How cmd.exe parses a command and Implementing a solution for more information.

What it does on non-Windows platforms

The argument is enclosed is single-quotes, with internal single-quotes escaped.

Is that it?

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.

License

Winbox-Args is licensed under the MIT License - see the LICENSE file for details.