@averay/codeformat 0.2.7 → 0.2.9

package/vendor/react/child-process/README.md

@@ -1,619 +0,0 @@
-# ChildProcess
-
-[![CI status](https://github.com/reactphp/child-process/actions/workflows/ci.yml/badge.svg)](https://github.com/reactphp/child-process/actions)
-[![installs on Packagist](https://img.shields.io/packagist/dt/react/child-process?color=blue&label=installs%20on%20Packagist)](https://packagist.org/packages/react/child-process)
-
-Event-driven library for executing child processes with
-[ReactPHP](https://reactphp.org/).
-
-This library integrates [Program Execution](http://php.net/manual/en/book.exec.php)
-with the [EventLoop](https://github.com/reactphp/event-loop).
-Child processes launched may be signaled and will emit an
-`exit` event upon termination.
-Additionally, process I/O streams (i.e. STDIN, STDOUT, STDERR) are exposed
-as [Streams](https://github.com/reactphp/stream).
-
-**Table of contents**
-
-* [Quickstart example](#quickstart-example)
-* [Process](#process)
-  * [Stream Properties](#stream-properties)
-  * [Command](#command)
-  * [Termination](#termination)
-  * [Custom pipes](#custom-pipes)
-  * [Sigchild Compatibility](#sigchild-compatibility)
-  * [Windows Compatibility](#windows-compatibility)
-* [Install](#install)
-* [Tests](#tests)
-* [License](#license)
-
-## Quickstart example
-
-```php
-$process = new React\ChildProcess\Process('echo foo');
-$process->start();
-
-$process->stdout->on('data', function ($chunk) {
-    echo $chunk;
-});
-
-$process->on('exit', function($exitCode, $termSignal) {
-    echo 'Process exited with code ' . $exitCode . PHP_EOL;
-});
-```
-
-See also the [examples](examples).
-
-## Process
-
-### Stream Properties
-
-Once a process is started, its I/O streams will be constructed as instances of
-`React\Stream\ReadableStreamInterface` and `React\Stream\WritableStreamInterface`. 
-Before `start()` is called, these properties are not set. Once a process terminates, 
-the streams will become closed but not unset.
-
-Following common Unix conventions, this library will start each child process
-with the three pipes matching the standard I/O streams as given below by default.
-You can use the named references for common use cases or access these as an
-array with all three pipes.
-
-* `$stdin`  or `$pipes[0]` is a `WritableStreamInterface`
-* `$stdout` or `$pipes[1]` is a `ReadableStreamInterface`
-* `$stderr` or `$pipes[2]` is a `ReadableStreamInterface`
-
-Note that this default configuration may be overridden by explicitly passing
-[custom pipes](#custom-pipes), in which case they may not be set or be assigned
-different values. In particular, note that [Windows support](#windows-compatibility)
-is limited in that it doesn't support non-blocking STDIO pipes. The `$pipes`
-array will always contain references to all pipes as configured and the standard
-I/O references will always be set to reference the pipes matching the above
-conventions. See [custom pipes](#custom-pipes) for more details.
-
-Because each of these implement the underlying
-[`ReadableStreamInterface`](https://github.com/reactphp/stream#readablestreaminterface) or 
-[`WritableStreamInterface`](https://github.com/reactphp/stream#writablestreaminterface), 
-you can use any of their events and methods as usual:
-
-```php
-$process = new Process($command);
-$process->start();
-
-$process->stdout->on('data', function ($chunk) {
-    echo $chunk;
-});
-
-$process->stdout->on('end', function () {
-    echo 'ended';
-});
-
-$process->stdout->on('error', function (Exception $e) {
-    echo 'error: ' . $e->getMessage();
-});
-
-$process->stdout->on('close', function () {
-    echo 'closed';
-});
-
-$process->stdin->write($data);
-$process->stdin->end($data = null);
-// …
-```
-
-For more details, see the
-[`ReadableStreamInterface`](https://github.com/reactphp/stream#readablestreaminterface) and 
-[`WritableStreamInterface`](https://github.com/reactphp/stream#writablestreaminterface).
-
-### Command
-
-The `Process` class allows you to pass any kind of command line string:
-
-```php
-$process = new Process('echo test');
-$process->start();
-```
-
-The command line string usually consists of a whitespace-separated list with
-your main executable bin and any number of arguments. Special care should be
-taken to escape or quote any arguments, escpecially if you pass any user input
-along. Likewise, keep in mind that especially on Windows, it is rather common to
-have path names containing spaces and other special characters. If you want to
-run a binary like this, you will have to ensure this is quoted as a single
-argument using `escapeshellarg()` like this:
-
-```php
-$bin = 'C:\\Program files (x86)\\PHP\\php.exe';
-$file = 'C:\\Users\\me\\Desktop\\Application\\main.php';
-
-$process = new Process(escapeshellarg($bin) . ' ' . escapeshellarg($file));
-$process->start();
-```
-
-By default, PHP will launch processes by wrapping the given command line string
-in a `sh` command on Unix, so that the first example will actually execute
-`sh -c echo test` under the hood on Unix. On Windows, it will not launch
-processes by wrapping them in a shell.
-
-This is a very useful feature because it does not only allow you to pass single
-commands, but actually allows you to pass any kind of shell command line and
-launch multiple sub-commands using command chains (with `&&`, `||`, `;` and
-others) and allows you to redirect STDIO streams (with `2>&1` and family).
-This can be used to pass complete command lines and receive the resulting STDIO
-streams from the wrapping shell command like this:
-
-```php
-$process = new Process('echo run && demo || echo failed');
-$process->start();
-```
-
-> Note that [Windows support](#windows-compatibility) is limited in that it
-  doesn't support STDIO streams at all and also that processes will not be run
-  in a wrapping shell by default. If you want to run a shell built-in function
-  such as `echo hello` or `sleep 10`, you may have to prefix your command line
-  with an explicit shell like `cmd /c echo hello`.
-
-In other words, the underlying shell is responsible for managing this command
-line and launching the individual sub-commands and connecting their STDIO
-streams as appropriate.
-This implies that the `Process` class will only receive the resulting STDIO
-streams from the wrapping shell, which will thus contain the complete
-input/output with no way to discern the input/output of single sub-commands.
-
-If you want to discern the output of single sub-commands, you may want to
-implement some higher-level protocol logic, such as printing an explicit
-boundary between each sub-command like this:
-
-```php
-$process = new Process('cat first && echo --- && cat second');
-$process->start();
-```
-
-As an alternative, considering launching one process at a time and listening on
-its `exit` event to conditionally start the next process in the chain.
-This will give you an opportunity to configure the subsequent process I/O streams:
-
-```php
-$first = new Process('cat first');
-$first->start();
-
-$first->on('exit', function () {
-    $second = new Process('cat second');
-    $second->start();
-});
-```
-
-Keep in mind that PHP uses the shell wrapper for ALL command lines on Unix.
-While this may seem reasonable for more complex command lines, this actually
-also applies to running the most simple single command:
-
-```php
-$process = new Process('yes');
-$process->start();
-```
-
-This will actually spawn a command hierarchy similar to this on Unix:
-
-```
-5480 … \_ php example.php
-5481 …    \_ sh -c yes
-5482 …        \_ yes
-```
-
-This means that trying to get the underlying process PID or sending signals
-will actually target the wrapping shell, which may not be the desired result
-in many cases.
-
-If you do not want this wrapping shell process to show up, you can simply
-prepend the command string with `exec` on Unix platforms, which will cause the
-wrapping shell process to be replaced by our process:
-
-```php
-$process = new Process('exec yes');
-$process->start();
-```
-
-This will show a resulting command hierarchy similar to this:
-
-```
-5480 … \_ php example.php
-5481 …    \_ yes
-```
-
-This means that trying to get the underlying process PID and sending signals
-will now target the actual command as expected.
-
-Note that in this case, the command line will not be run in a wrapping shell.
-This implies that when using `exec`, there's no way to pass command lines such
-as those containing command chains or redirected STDIO streams.
-
-As a rule of thumb, most commands will likely run just fine with the wrapping
-shell.
-If you pass a complete command line (or are unsure), you SHOULD most likely keep
-the wrapping shell.
-If you're running on Unix and you want to pass an invidual command only, you MAY
-want to consider prepending the command string with `exec` to avoid the wrapping shell.
-
-### Termination
-
-The `exit` event will be emitted whenever the process is no longer running.
-Event listeners will receive the exit code and termination signal as two
-arguments:
-
-```php
-$process = new Process('sleep 10');
-$process->start();
-
-$process->on('exit', function ($code, $term) {
-    if ($term === null) {
-        echo 'exit with code ' . $code . PHP_EOL;
-    } else {
-        echo 'terminated with signal ' . $term . PHP_EOL;
-    }
-});
-```
-
-Note that `$code` is `null` if the process has terminated, but the exit
-code could not be determined (for example
-[sigchild compatibility](#sigchild-compatibility) was disabled).
-Similarly, `$term` is `null` unless the process has terminated in response to
-an uncaught signal sent to it.
-This is not a limitation of this project, but actual how exit codes and signals
-are exposed on POSIX systems, for more details see also
-[here](https://unix.stackexchange.com/questions/99112/default-exit-code-when-process-is-terminated).
-
-It's also worth noting that process termination depends on all file descriptors
-being closed beforehand.
-This means that all [process pipes](#stream-properties) will emit a `close`
-event before the `exit` event and that no more `data` events will arrive after
-the `exit` event.
-Accordingly, if either of these pipes is in a paused state (`pause()` method
-or internally due to a `pipe()` call), this detection may not trigger.
-
-The `terminate(?int $signal = null): bool` method can be used to send the
-process a signal (SIGTERM by default).
-Depending on which signal you send to the process and whether it has a signal
-handler registered, this can be used to either merely signal a process or even
-forcefully terminate it.
-
-```php
-$process->terminate(SIGUSR1);
-```
-
-Keep the above section in mind if you want to forcefully terminate a process.
-If your process spawn sub-processes or implicitly uses the
-[wrapping shell mentioned above](#command), its file descriptors may be
-inherited to child processes and terminating the main process may not
-necessarily terminate the whole process tree.
-It is highly suggested that you explicitly `close()` all process pipes
-accordingly when terminating a process:
-
-```php
-$process = new Process('sleep 10');
-$process->start();
-
-Loop::addTimer(2.0, function () use ($process) {
-    foreach ($process->pipes as $pipe) {
-        $pipe->close();
-    }
-    $process->terminate();
-});
-```
-
-For many simple programs these seamingly complicated steps can also be avoided
-by prefixing the command line with `exec` to avoid the wrapping shell and its
-inherited process pipes as [mentioned above](#command).
-
-```php
-$process = new Process('exec sleep 10');
-$process->start();
-
-Loop::addTimer(2.0, function () use ($process) {
-    $process->terminate();
-});
-```
-
-Many command line programs also wait for data on `STDIN` and terminate cleanly
-when this pipe is closed.
-For example, the following can be used to "soft-close" a `cat` process:
-
-```php
-$process = new Process('cat');
-$process->start();
-
-Loop::addTimer(2.0, function () use ($process) {
-    $process->stdin->end();
-});
-```
-
-While process pipes and termination may seem confusing to newcomers, the above
-properties actually allow some fine grained control over process termination,
-such as first trying a soft-close and then applying a force-close after a
-timeout.
-
-### Custom pipes
-
-Following common Unix conventions, this library will start each child process
-with the three pipes matching the standard I/O streams by default. For more
-advanced use cases it may be useful to pass in custom pipes, such as explicitly
-passing additional file descriptors (FDs) or overriding default process pipes.
-
-Note that passing custom pipes is considered advanced usage and requires a
-more in-depth understanding of Unix file descriptors and how they are inherited
-to child processes and shared in multi-processing applications.
-
-If you do not want to use the default standard I/O pipes, you can explicitly
-pass an array containing the file descriptor specification to the constructor
-like this:
-
-```php
-$fds = array(
-    // standard I/O pipes for stdin/stdout/stderr
-    0 => array('pipe', 'r'),
-    1 => array('pipe', 'w'),
-    2 => array('pipe', 'w'),
-
-    // example FDs for files or open resources
-    4 => array('file', '/dev/null', 'r'),
-    6 => fopen('log.txt','a'),
-    8 => STDERR,
-
-    // example FDs for sockets
-    10 => fsockopen('localhost', 8080),
-    12 => stream_socket_server('tcp://0.0.0.0:4711')
-);
-
-$process = new Process($cmd, null, null, $fds);
-$process->start();
-```
-
-Unless your use case has special requirements that demand otherwise, you're
-highly recommended to (at least) pass in the standard I/O pipes as given above.
-The file descriptor specification accepts arguments in the exact same format
-as the underlying [`proc_open()`](http://php.net/proc_open) function.
-
-Once the process is started, the `$pipes` array will always contain references to
-all pipes as configured and the standard I/O references will always be set to
-reference the pipes matching common Unix conventions. This library supports any
-number of pipes and additional file descriptors, but many common applications
-being run as a child process will expect that the parent process properly
-assigns these file descriptors.
-
-### Sigchild Compatibility
-
-Internally, this project uses a work-around to improve compatibility when PHP
-has been compiled with the `--enable-sigchild` option. This should not affect most
-installations as this configure option is not used by default and many
-distributions (such as Debian and Ubuntu) are known to not use this by default.
-Some installations that use [Oracle OCI8](http://php.net/manual/en/book.oci8.php)
-may use this configure option to circumvent `defunct` processes.
-
-When PHP has been compiled with the `--enable-sigchild` option, a child process'
-exit code cannot be reliably determined via `proc_close()` or `proc_get_status()`.
-To work around this, we execute the child process with an additional pipe and
-use that to retrieve its exit code.
-
-This work-around incurs some overhead, so we only trigger this when necessary
-and when we detect that PHP has been compiled with the `--enable-sigchild` option.
-Because PHP does not provide a way to reliably detect this option, we try to
-inspect output of PHP's configure options from the `phpinfo()` function.
-
-The static `setSigchildEnabled(bool $sigchild): void` method can be used to
-explicitly enable or disable this behavior like this:
-
-```php
-// advanced: not recommended by default
-Process::setSigchildEnabled(true);
-```
-
-Note that all processes instantiated after this method call will be affected.
-If this work-around is disabled on an affected PHP installation, the `exit`
-event may receive `null` instead of the actual exit code as described above.
-Similarly, some distributions are known to omit the configure options from
-`phpinfo()`, so automatic detection may fail to enable this work-around in some
-cases. You may then enable this  explicitly as given above.
-
-**Note:** The original functionality was taken from Symfony's
-[Process](https://github.com/symfony/process) compoment.
-
-### Windows Compatibility
-
-Due to platform constraints, this library provides only limited support for
-spawning child processes on Windows. In particular, PHP does not allow accessing
-standard I/O pipes on Windows without blocking. As such, this project will not
-allow constructing a child process with the default process pipes and will
-instead throw a `LogicException` on Windows by default:
-
-```php
-// throws LogicException on Windows
-$process = new Process('ping example.com');
-$process->start();
-```
-
-There are a number of alternatives and workarounds as detailed below if you want
-to run a child process on Windows, each with its own set of pros and cons:
-
-*   As of PHP 8, you can start the child process with `socket` pair descriptors
-    in place of normal standard I/O pipes like this:
-
-    ```php
-    $process = new Process(
-        'ping example.com',
-        null,
-        null,
-        [
-            ['socket'],
-            ['socket'],
-            ['socket']
-        ]
-    );
-    $process->start();
-
-    $process->stdout->on('data', function ($chunk) {
-        echo $chunk;
-    });
-    ```
-
-    These `socket` pairs support non-blocking process I/O on any platform,
-    including Windows. However, not all programs accept stdio sockets.
-
-*   This package does work on
-    [`Windows Subsystem for Linux`](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux)
-    (or WSL) without issues. When you are in control over how your application is
-    deployed, we recommend [installing WSL](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide)
-    when you want to run this package on Windows.
-
-*   If you only care about the exit code of a child process to check if its
-    execution was successful, you can use [custom pipes](#custom-pipes) to omit
-    any standard I/O pipes like this:
-
-    ```php
-    $process = new Process('ping example.com', null, null, array());
-    $process->start();
-
-    $process->on('exit', function ($exitcode) {
-        echo 'exit with ' . $exitcode . PHP_EOL;
-    });
-    ```
-
-    Similarly, this is also useful if your child process communicates over
-    sockets with remote servers or even your parent process using the
-    [Socket component](https://github.com/reactphp/socket). This is usually
-    considered the best alternative if you have control over how your child
-    process communicates with the parent process.
-
-*   If you only care about command output after the child process has been
-    executed, you can use [custom pipes](#custom-pipes) to configure file
-    handles to be passed to the child process instead of pipes like this:
-
-    ```php
-    $process = new Process('ping example.com', null, null, array(
-        array('file', 'nul', 'r'),
-        $stdout = tmpfile(),
-        array('file', 'nul', 'w')
-    ));
-    $process->start();
-
-    $process->on('exit', function ($exitcode) use ($stdout) {
-        echo 'exit with ' . $exitcode . PHP_EOL;
-
-        // rewind to start and then read full file (demo only, this is blocking).
-        // reading from shared file is only safe if you have some synchronization in place
-        // or after the child process has terminated.
-        rewind($stdout);
-        echo stream_get_contents($stdout);
-        fclose($stdout);
-    });
-    ```
-
-    Note that this example uses `tmpfile()`/`fopen()` for illustration purposes only.
-    This should not be used in a truly async program because the filesystem is
-    inherently blocking and each call could potentially take several seconds.
-    See also the [Filesystem component](https://github.com/reactphp/filesystem) as an
-    alternative.
-
-*   If you want to access command output as it happens in a streaming fashion,
-    you can use redirection to spawn an additional process to forward your
-    standard I/O streams to a socket and use [custom pipes](#custom-pipes) to
-    omit any actual standard I/O pipes like this:
-
-    ```php
-    $server = new React\Socket\Server('127.0.0.1:0');
-    $server->on('connection', function (React\Socket\ConnectionInterface $connection) {
-        $connection->on('data', function ($chunk) {
-            echo $chunk;
-        });
-    });
-
-    $command = 'ping example.com | foobar ' . escapeshellarg($server->getAddress());
-    $process = new Process($command, null, null, array());
-    $process->start();
-
-    $process->on('exit', function ($exitcode) use ($server) {
-        $server->close();
-        echo 'exit with ' . $exitcode . PHP_EOL;
-    });
-    ```
-
-    Note how this will spawn another fictional `foobar` helper program to consume
-    the standard output from the actual child process. This is in fact similar
-    to the above recommendation of using socket connections in the child process,
-    but in this case does not require modification of the actual child process.
-
-    In this example, the fictional `foobar` helper program can be implemented by
-    simply consuming all data from standard input and forwarding it to a socket
-    connection like this:
-
-    ```php
-    $socket = stream_socket_client($argv[1]);
-    do {
-        fwrite($socket, $data = fread(STDIN, 8192));
-    } while (isset($data[0]));
-    ```
-
-    Accordingly, this example can also be run with plain PHP without having to
-    rely on any external helper program like this:
-
-    ```php
-    $code = '$s=stream_socket_client($argv[1]);do{fwrite($s,$d=fread(STDIN, 8192));}while(isset($d[0]));';
-    $command = 'ping example.com | php -r ' . escapeshellarg($code) . ' ' . escapeshellarg($server->getAddress());
-    $process = new Process($command, null, null, array());
-    $process->start();
-    ```
-
-    See also [example #23](examples/23-forward-socket.php).
-
-    Note that this is for illustration purposes only and you may want to implement
-    some proper error checks and/or socket verification in actual production use
-    if you do not want to risk other processes connecting to the server socket.
-    In this case, we suggest looking at the excellent
-    [createprocess-windows](https://github.com/cubiclesoft/createprocess-windows).
-
-Additionally, note that the [command](#command) given to the `Process` will be
-passed to the underlying Windows-API
-([`CreateProcess`](https://docs.microsoft.com/en-us/windows/desktop/api/processthreadsapi/nf-processthreadsapi-createprocessa))
-as-is and the process will not be launched in a wrapping shell by default. In
-particular, this means that shell built-in functions such as `echo hello` or
-`sleep 10` may have to be prefixed with an explicit shell command like this:
-
-```php
-$process = new Process('cmd /c echo hello', null, null, $pipes);
-$process->start();
-```
-
-## Install
-
-The recommended way to install this library is [through Composer](https://getcomposer.org/).
-[New to Composer?](https://getcomposer.org/doc/00-intro.md)
-
-This will install the latest supported version:
-
-```bash
-composer require react/child-process:^0.6.6
-```
-
-See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades.
-
-This project aims to run on any platform and thus does not require any PHP
-extensions and supports running on legacy PHP 5.3 through current PHP 8+ and HHVM.
-It's *highly recommended to use the latest supported PHP version* for this project.
-
-See above note for limited [Windows Compatibility](#windows-compatibility).
-
-## Tests
-
-To run the test suite, you first need to clone this repo and then install all
-dependencies [through Composer](https://getcomposer.org/):
-
-```bash
-composer install
-```
-
-To run the test suite, go to the project root and run:
-
-```bash
-vendor/bin/phpunit
-```
-
-## License
-
-MIT, see [LICENSE file](LICENSE).

package/vendor/react/child-process/composer.json

@@ -1,49 +0,0 @@
-{
-    "name": "react/child-process",
-    "description": "Event-driven library for executing child processes with ReactPHP.",
-    "keywords": ["process", "event-driven", "ReactPHP"],
-    "license": "MIT",
-    "authors": [
-        {
-            "name": "Christian Lück",
-            "homepage": "https://clue.engineering/",
-            "email": "christian@clue.engineering"
-        },
-        {
-            "name": "Cees-Jan Kiewiet",
-            "homepage": "https://wyrihaximus.net/",
-            "email": "reactphp@ceesjankiewiet.nl"
-        },
-        {
-            "name": "Jan Sorgalla",
-            "homepage": "https://sorgalla.com/",
-            "email": "jsorgalla@gmail.com"
-        },
-        {
-            "name": "Chris Boden",
-            "homepage": "https://cboden.dev/",
-            "email": "cboden@gmail.com"
-        }
-    ],
-    "require": {
-        "php": ">=5.3.0",
-        "evenement/evenement": "^3.0 || ^2.0 || ^1.0",
-        "react/event-loop": "^1.2",
-        "react/stream": "^1.4"
-    },
-    "require-dev": {
-        "phpunit/phpunit": "^9.6 || ^5.7 || ^4.8.36",
-        "react/socket": "^1.16",
-        "sebastian/environment": "^5.0 || ^3.0 || ^2.0 || ^1.0"
-    },
-    "autoload": {
-        "psr-4": {
-            "React\\ChildProcess\\": "src/"
-        }
-    },
-    "autoload-dev": {
-        "psr-4": {
-            "React\\Tests\\ChildProcess\\": "tests/"
-        }
-    }
-}