Download the PHP package takuya/php-process-exec without Composer

Exec Process by php .

This help to run process by fork ( proc_open ). This package depends on proc_open wrapper class.

Handling process, Run Long time command safety. and Event handler model.

Installing

by packagist

by GitHub

Example

Pipe process

Run CMD STRING by bash.

Do something at get output as line by line.

Do something after process finished.

Avoiding shell at run command.

run command without shell.

"Run Command should be avoided in php" , you may have been lectured. One of this reason is SHELL ARGs ESCAPING. Shell string escaping is a troublemaker.

It's easy enough that run command without shell escaping. In php shell exec, pass Array to proc_opee. it can do that.

Another reason for avoid shell execution is Directory Traversal vulnerability.

This can be avoided by checking values in advance.

These ways show that properly use of proc_open is SAFE.

Even though, proc_open itself is troublesome function. so I wrote proc_open wrapper class

Nonetheless, I still have frustration. when Re-using of COMMAND config (params+args+redirect) is messy. So I wrote a class to make Arguments as class instance ( command options ).

Command as Struct

ExecArgStruct is Cmd itself not process.

By using Struct, we can check and validate arguments, such as must option, restrict command, check file accessible, before run.

Dividing role, EXECUTION and VALIDATION , make process execution simple.

Example: argument checking and validation as construct.

Checking indispensable options, like this.

This package supports to run command more safer and more easier than proc_open().

Event Trigger / Event Listener

Using Event, " Process changed, then do something".

proc_open with handling process status ( running / finished / error ) increase complexity. Solving this, Event-Listeners can be added.

Process Events are these.

Event Observer is used internal of this package, in ProcessExecutor, observer is used to detect IO Streaming.

onStdOut / onStdErr

Skip to write new Observer, Simplified Listener shortcut callback function is included in ProcessExecutor.

onInputProgress / progress input (pv)

Input Percentage, ( like pv command ) callback function included.

onInputProgress pass a percentage of input has read.

Notice : this is not stable, reading speed limitation.

Pipe ( piping process )

This is shell pipe sample pipe(|).

Piping command line in shell by pure proc_open() is very confusing.

I wrote ProcOpen class to make easier for using pipe process than proc_open.

Supporting pipe() as function, raise the abstraction level of pipe process.

Two STDERR in Pipe , read separately

For example, run 2 process pv x.mp4| ffmpeg -i pipe:0 like this.

Normal shell (ex. bash ), output is write to stderr(2), and '\r' will cancel each other stderr.

To resolve this, Separate STDERR per process and individually out (cmd 2>err.txt). but, this way , reading stderr is messy.

Without shell (bash) output file, directory access to To STDERR by programme, Reading Two of STDERR is very simple. This package supports two of stderr in pipe.

Result is this , Each STDERR printed separately.Each STDERR can handle as each stream.

Classes in This EXEC package

Notice

Notice 1 LINUX PIPE_BUFF

This packaged is interfered with PIPE_BUFF / PIPE_SIZE of Linux kernel.

Without reading STDOUT and STDOUT , and too many writing , Linux PIPE buff get stuck. Then, Process can't write , Linux will make sleep the process . Kernel has PIPE_SIZE=65,536 bytes.If stdout keep 64kb without reading, then the process will be stopped. To prevent this blocking, Streams must be read proper timing or specify output file. Like command that FFMpeg, ImageMagick is used in proc_open, It will write large size byte onto STDOUT, These command will be blocked and stopped.

This package is on purpose designed not to prevent blocking.

This package intended very consciously will be blocked and stopped.

Notice 2: semaphore

Semaphore and SharedMemory is used in ForkedExecutor in daemonize.

Semaphore and SharedMemory will cause trouble, shortage of size and fails to allocate memory, without deallocating.

After interrupted of CTRL-C, Check Semaphore and SharedMemory is released.

Use these command carefully to manage. ( especially macOS, has few memory for shared memory)

Notice 3 : pcntl_async_signals

pcntl_async_signals called in advance, to signal detection.

POSIX signal detection , write one line (pcntl_async_signals). Without pcntl_async_signals result in no POSIX signal. (see :PHP and SIGNALS,in background )

In ProcessExecutor this line implicitly, but proc_open and ProcOpen(wrapper) needs explicitly calling.

Test

run PHPUnit for testing this.

code coverage

show Code coverage in phpunit

TODO: 2024-05-27

• Buffering stdout,stdout after reached Linux PIPE_MAX
• supporting TTY
  • check by stream_isatty and can write Y/N.

todo: 2024-09-15

Buffering stdout,stdout after reached Linux PIPE_MAX

ffprobe raise trouble , so I need automated buffering.