initial implementation

README.md

@@ -1,2 +1,32 @@
 # phpquoteshellarg
-php quote shell arguments
+php quote shell arguments function
+... doing a better job than php's builtin escapeshellarg(): https://3v4l.org/Hkv7h
+
+# installation
+the script is just a standalone .php file, you can just copypaste it. 
+
+another alternative is to use composer:
+```
+composer require 'divinity76/phpquoteshellarg'
+```
+# usage
+
+```
+<?php
+require_once(__DIR__ . '/vendor/autoload.php');
+use function Divinity76\quoteshellarg\quoteshellarg;
+
+$str="æøå\x01";
+var_dump(["str"=>$str,"escapeshellarg"=>escapeshellarg($str), "quoteshellarg"=>quoteshellarg($str)]);
+```
+may outputs something like
+```
+array(3) {
+  ["str"]=>
+  string(7) "æøå
"
+  ["escapeshellarg"]=>
+  string(3) "'
'"
+  ["quoteshellarg"]=>
+  string(9) "'æøå
'"
+}
+```

composer.json

@@ -0,0 +1,14 @@
+{
+    "name": "divinity76/phpquoteshellarg",
+    "description": "php quote shell arguments",
+    "keywords": ["quoteshellarg", "escapeshellarg"],
+    "homepage": "https://github.com/divinity76/phprouter",
+    "type": "library",
+    "license": "Unlicense",
+    "require": {
+        "php": ">=7.2"
+    },
+    "autoload": {
+        "psr-4": {"Divinity76\\": "src/Divinity76/"}
+    }
+}

src/Divinity76/quoteshellarg/quoteshellarg.php

@@ -0,0 +1,33 @@
+<?php
+declare (strict_types = 1);
+namespace Divinity76\quoteshellarg;
+
+/**
+ * quotes shell arguments
+ * (doing a better job than escapeshellarg)
+ *
+ * @param string $arg
+ * @throws UnexpectedValueException if $arg contains null bytes
+ * @return string
+ */
+
+function quoteshellarg(string $arg): string
+{
+    static $isUnix = null;
+    if ($isUnix === null) {
+        $isUnix = in_array(PHP_OS_FAMILY, array('Linux', 'BSD', 'Darwin', 'Solaris'), true);
+    }
+    if ($isUnix) {
+        // PHP's built-in escapeshellarg() for unix is kindof garbage: https://3v4l.org/Hkv7h
+        // corrupting-or-stripping UTF-8 unicode characters like "æøå" and non-printable characters like "\x01",
+        // both of which are fully legal in unix shell arguments.
+        // In single-quoted-unix-shell-arguments there are only 2 bytes that needs special attention: \x00 and \x27
+        if (false !== strpos($arg, "\x00")) {
+            throw new UnexpectedValueException('unix shell arguments cannot contain null bytes!');
+        }
+        return "'" . strtr($arg, array("'" => "'\\''")) . "'";
+    }
+    // todo: quoteshellarg for windows? it's a nightmare though: https://docs.microsoft.com/en-us/archive/blogs/twistylittlepassagesallalike/everyone-quotes-command-line-arguments-the-wrong-way
+    // fallback to php's builtin escapeshellarg
+    return escapeshellarg($arg);
+}