Recommend this page to a friend! |
Classes of Christian Vigh | PHP Asynchronous Command | README.md | Download |
|
DownloadAsynchronousCommand classThis class addresses the case where an external command is to be run, and its output needs to be captured and interpreted as soon as the external command emits it. It uses streams to pipe the standard output of the child process and be able to read it. Unfortunately for Windows users, there are several limitations that this class tries to overcome :
In fact, on Windows it is currently impossible to separately get into PHP the output generated by a child process on both stdout and stderr without eventually doing a blocking call. For those reasons, this class makes a compromise : you can spawn a child process, send data to it through its stdin file descriptor, read from its standard output, but you will not be able to differentiate between stdout and stderr. Both will be mixed because stderr will systematically be redirected to stdout by the AsynchronousCommand class. Listed below is an example of how to run a command, capture in real-time its standard output, and do some special processing if a given string is encountered in the child output :
It is also possible to write to the child process standard input ; for that, just instanciate the command object using "true" as the second parameter ($pipe_stdin) :
Then, in the while loop, add the following code to write something if an input request has been made :
METHODSThe following paragraph the methods that are available from the AynchronousCommand class. ConstructorCreates a child process using the specified command. Prototype
Parameters$command (string) - Command to be executed.
$pipe_stdin (boolean) - When true, the parent process (ie, the one that instanciated an AsynchronousCommand object) will be able to write to its child stdin file descriptor using the Write or WriteLine methods. When false (the default), the file descriptor used for the child's standard input is the one of the parent process.
$run (boolean) - When true, the command is run immediately. Otherwise you will have to use the Run() method to start command execution. NotesDue to the current limitations of Windows and PHP on Windows, only the child process standard output can be read from a pipe as a non-blocking call. The child standard error is always redirected to standard output. Execute methodA shortcut using a static method for executing a command and displaying its output onto standard output. A callback can be specified to handle each chunk of output. Prototype
Parameters$command (string) - Command to execute. $cwd (string) - Current directory for command execution. $callback (callback) - Function that will be called for processing each chunk of data read from the command output stream. The callback must have the following signature :
The data will be written to standard output if the callback returns false. $line_buffering (boolean) - When true (the default), the command output stream data will be read line by line.
Return valueReturns the command exit status. Various getters and setters
Read, ReadLineReads data from the child standard output. Read() reads data from the child process standard output, up to 8Kb. ReadLine() reads a line, until an end of line is met. Prototype
Return valueThe data read from the child process standard output. For ReadLine(), the trailing newline is stripped from the returned value.
RunRuns the command specified to the AsynchronousCommand constructor. TerminatePrototype
Parameters ###$signal (integer) - (Unix systems only) Signal to be sent to the running process. Write, WriteLineWrites data to the standard input of the child process. This only works when the $pipe_stdin parameter of the class constructor has been set to true. Prototype
|