Code cleanup

Author: kamermans

.gitignore

@@ -2,3 +2,4 @@ vendor/
 build/
 composer.phar
 composer.lock
+.idea/

src/Command.php

@@ -59,7 +59,7 @@ public function setCallback(callable $callback, $readlines=false)
      * Read no more than this many bytes at a time
      * 
      * @param int $bytes
-     * @reutrn Command - Fluent
+     * @return Command - Fluent
      */
     public function setReadBuffer($bytes)
     {
@@ -172,6 +172,7 @@ public function argument($arg) {
      * @param string|resource $stdin The string contents for STDIN or a stream resource to be consumed
      * @param bool $throw_exceptions If true (default), an exception will be thrown if the command fails
      * @return Command - Fluent interface
+     * @throws CommandException The command failed
      */
     public function run($stdin = null, $throw_exceptions = true)
     {
@@ -181,15 +182,15 @@ public function run($stdin = null, $throw_exceptions = true)
         $this->stderr = null;
         $this->timestart = microtime(true);
 
-        $process = new ProcessManager($this->getFullCommand(), $buffers);
-
         // Prepare the buffers structure
         $buffers = [
             self::STDIN  => $stdin,
             self::STDOUT => &$this->stdout,
             self::STDERR => &$this->stderr,
         ];
 
+        $process = new ProcessManager($this->getFullCommand(), $buffers);
+
         $this->exitcode = $process->exec($this->callback, $this->callbacklines, $this->readbuffer, $this->cwd, $this->env, $this->conf);
         $this->timeend = microtime(true);
 

src/CommandException.php

@@ -1,6 +1,10 @@
 <?php namespace kamermans\Command;
 
-class CommandException extends \Exception {
+/**
+ * Class CommandException is thrown when a command fails
+ * @package kamermans\Command
+ */
+class CommandException extends Exception {
 
 	protected $cmd;
 
@@ -14,4 +18,4 @@ public function getCommand()
 	{
 		return $this->cmd;
 	}
-}
+}

src/Exception.php

@@ -0,0 +1,7 @@
+<?php namespace kamermans\Command;
+
+/**
+ * Base Exception
+ * @package kamermans\Command
+ */
+class Exception extends \Exception {}

src/ProcessManager.php

@@ -1,5 +1,12 @@
 <?php namespace kamermans\Command;
-
+use kamermans\Command\Stream\Handler;
+
+/**
+ * Class ProcessManager
+ * Starts and manages a process, handling STDIN, STDOUT and STDERR and exit status.
+ *
+ * @package kamermans\Command
+ */
 class ProcessManager {
 
     protected $cmd;
@@ -10,6 +17,12 @@ class ProcessManager {
     protected $io_writes = [];
     protected $streams = [];
 
+
+    /**
+     * ProcessManager constructor.
+     * @param string $cmd Full command to be run
+     * @param array $buffers Array of buffers to be used for STDIN, STDOUT, STDERR
+     */
     public function __construct($cmd, &$buffers)
     {
         if (!is_array($buffers)) {
@@ -21,15 +34,15 @@ public function __construct($cmd, &$buffers)
     }
 
     /**
-     * Executes a command returning the exitcode and capturing the stdout and stderr
+     * Executes a command returning the exit code and capturing the stdout and stderr
      *
      * @param callable $callback  A callback function for stdout/stderr data
      * @param bool $callbacklines Call callback for each line
      * @param int $buffer_size Read this many bytes at a time
      * @param string $cwd Set working directory
      * @param array $env Environment variables for the process
      * @param array $conf Additional options for proc_open()
-     * @return int
+     * @return int Process exit code
      */
     public function exec($callback, $callbacklines, $buffer_size, $cwd, $env, $conf)
     {
@@ -79,13 +92,24 @@ public function exec($callback, $callbacklines, $buffer_size, $cwd, $env, $conf)
         return $exit_code;
     }
 
+    /**
+     * Checks all ready read/write handles as returned by `stream_select()` and calls the write() or read() methods
+     * of their corresponding Stream handler
+     *
+     * @see Writer::write()
+     * @see Reader::read()
+     *
+     * @param $handles
+     * @return bool
+     * @throws Exception
+     */
     protected function doReadWrite($handles)
     {
         if ($handles['ready'] === 0) {
             // Stream timeout; no streams ready
             return false;
         } else if ($handles['ready'] === false) {
-            throw new \Exception("stream_select() failed while waiting for I/O on command");
+            throw new Exception("stream_select() failed while waiting for I/O on command");
         }
 
         // Read from all ready streams
@@ -108,6 +132,14 @@ protected function doReadWrite($handles)
         return true;
     }
 
+    /**
+     * Opens the process handle via `proc_open()`
+     *
+     * @param string $cwd The initial working dir for the command. This must be an absolute directory path or null.
+     * @param array $env An array with the environment variables for the command that will be run, or null.
+     * @param array $conf Additional options to pass to `proc_open()` (as the `$other_options` parameter).
+     * @throws Exception The command failed to start
+     */
     protected function open($cwd, $env, $conf)
     {
         // Define the streams to configure for the process
@@ -120,7 +152,7 @@ protected function open($cwd, $env, $conf)
         // Start the process
         $this->handle = proc_open($this->cmd, $descriptors, $this->io_handles, $cwd, $env, $conf);
         if (!is_resource($this->handle)) {
-            throw new \Exception("Failed to open process handle");
+            throw new Exception("Failed to open process handle");
         }
 
         // Set all IO handles to non-blocking mode
@@ -142,7 +174,14 @@ protected function open($cwd, $env, $conf)
         ];
     }
 
-    protected function close($exit_code, $callback)
+    /**
+     * Closes the currently running process and returns the exit code.
+     *
+     * @param int $exit_code The code that the process exited with or null if unavailable
+     * @param callable $callback Output data callback function
+     * @return int Exit code
+     */
+    protected function close($exit_code, callable $callback=null)
     {
         // Make sure all IO handles are closed
         foreach ($this->io_handles as $id => $handle) {
@@ -171,16 +210,29 @@ protected function close($exit_code, $callback)
         return $exit_code;
     }
 
+    /**
+     * @return bool true if STDIN buffer is available for reading
+     */
     protected function isStdInAvailable()
     {
         return $this->isStdInStreaming() || !empty($this->buffers[Command::STDIN]);
     }
 
+    /**
+     * @return bool true if STDIN is a stream (false if it is a string)
+     */
     protected function isStdInStreaming()
     {
         return is_resource($this->buffers[Command::STDIN]);
     }
 
+    /**
+     * Setup the STDIN, STDOUT and STDERR stream handlers
+     *
+     * @param callable|null $callback
+     * @param bool $callbacklines
+     * @param int $buffer_size
+     */
     protected function setupStreams($callback, $callbacklines, $buffer_size)
     {
         // Prepare STDIN
@@ -253,28 +305,33 @@ protected function setupStreams($callback, $callbacklines, $buffer_size)
         ];
     }
 
-
+    /**
+     * This function will wait until streams are ready for read/write, or a timeout has occurred, then it will
+     * return an array of those handles that are ready for processing.
+     *
+     * @return array
+     */
     protected function waitForReadyHandles()
     {
         // Setup streams before each iteration since they are changed by stream_select()
         $stream_select_timeout_sec = null;
         $stream_select_timeout_usec = 200000;
 
-        $handles['read'] = array_filter($this->io_reads, 'is_resource');
+        $handles = [
+            'read' => array_filter($this->io_reads, 'is_resource'),
+            'write' => [],
+            'except' => [],
+        ];
 
         if ($this->isStdInAvailable() && is_resource($this->io_handles[Command::STDIN])) {
             $handles['write'] = $this->io_writes;
-        } else {
-            $handles['write'] = [];
         }
 
-        $except = [];
-
         // This line will block until a stream is ready for input or output
         $num_ready = stream_select(
             $handles['read'],
             $handles['write'],
-            $except,
+            $handles['except'],
             $stream_select_timeout_sec,
             $stream_select_timeout_usec
         );
@@ -284,6 +341,12 @@ protected function waitForReadyHandles()
         return $handles;
     }
 
+    /**
+     * Returns the Stream Handler (Reader/Writer) that is managing a given IO handle
+     *
+     * @param resource $handle
+     * @return Stream\Handler
+     */
     protected function getStreamFromIoHandle($handle)
     {
         return $this->streams[array_search($handle, $this->io_handles)];

src/Stream/CallbackLinesReader.php

@@ -2,6 +2,10 @@
 
 use kamermans\Command\TerminateException;
 
+/**
+ * Reads a stream into a callback one line at a time
+ * @package kamermans\Command\Stream
+ */
 class CallbackLinesReader extends CallbackReader {
 
     public function read()

src/Stream/CallbackReader.php

@@ -1,15 +1,35 @@
 <?php namespace kamermans\Command\Stream;
 
+use kamermans\Command\Exception;
 use kamermans\Command\TerminateException;
 
+/**
+ * Reads a stream into a callback in chunks
+ * @package kamermans\Command\Stream
+ */
 class CallbackReader extends StringReader {
 
     protected $callback;
 
-    public function __construct($stream, $stream_id, $callback, $buffer_size=4096)
+    /**
+     * CallbackReader constructor.
+     *
+     * Note that the $callback function will be called with two arguments:
+     *   int $stream_id The stream_id that the data was read from
+     *   string $data The data that was read
+     *
+     * When the stream is finally closed, it will be called one last time with `$data = null`.
+     *
+     * @param resource $stream The source stream to be read from
+     * @param int $stream_id The ID of the stream (0=STDIN, 1=STDOUT, 2=STDERR)
+     * @param callable $callback The function that will be called for each chunk of data
+     * @param int $buffer_size The max bytes that can be copied at one time
+     * @throws Exception The source stream is invalid
+     */
+    public function __construct($stream, $stream_id, callable $callback, $buffer_size=4096)
     {
         if (!is_resource($stream)) {
-            throw new \InvalidArguentException("stream is not a valid resource");
+            throw new Exception("stream is not a valid resource");
         }
 
         $this->callback = $callback;

src/Stream/Handler.php

@@ -0,0 +1,11 @@
+<?php namespace kamermans\Command\Stream;
+
+/**
+ * Manages an IO handle/resource and is able to provide stats about the bytes affected.
+ * @package kamermans\Command\Stream
+ */
+interface Handler {
+
+    public function getBytes();
+
+}

src/Stream/Reader.php

@@ -1,8 +1,15 @@
 <?php namespace kamermans\Command\Stream;
 
+/**
+ * Handles a stream and can read from it
+ * @package kamermans\Command\Stream
+ */
 interface Reader {
 
+    /**
+     * Reads data from a stream.  This function should be called until the stream is closed (EOF).
+     * @return int bytes read
+     */
     public function read();
-    public function getBytes();
 
 }

src/Stream/StreamWriter.php

@@ -1,6 +1,12 @@
 <?php namespace kamermans\Command\Stream;
 
-class StreamWriter implements Writer {
+use kamermans\Command\Exception;
+
+/**
+ * Writes a stream into another stream
+ * @package kamermans\Command\Stream
+ */
+class StreamWriter implements Handler, Writer {
 
     protected $id;
     protected $stream;
@@ -9,14 +15,22 @@ class StreamWriter implements Writer {
     protected $buffer_size;
     protected $bytes = 0;
 
+    /**
+     * StreamWriter constructor.
+     *
+     * @param resource $source_stream The source stream that will be read from
+     * @param resource $dest_stream The destination stream that will be written to
+     * @param int $buffer_size The max bytes that can be copied at one time
+     * @throws Exception The source or destination streams are invalid
+     */
     public function __construct($source_stream, $dest_stream, $buffer_size=4096)
     {
         if (!is_resource($source_stream)) {
-            throw new \InvalidArguentException("source_stream is not a valid resource");
+            throw new Exception("source_stream is not a valid resource");
         }
 
         if (!is_resource($dest_stream)) {
-            throw new \InvalidArgumentException("dest_stream is not a valid resource");
+            throw new Exception("dest_stream is not a valid resource");
         }
 
         $this->id = (string)$source_stream;