Proc.php

<?php
/**
 * Proc.php
 *
 * Executes a process with proc_open() and guarantees it is terminated on exit
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 *
 * @link       https://www.librenms.org
 *
 * @copyright  2016 Tony Murray
 * @author     Tony Murray <murraytony@gmail.com>
 */

namespace LibreNMS;

use Exception;
use Illuminate\Support\Str;

class Proc
{
    /**
     * @var resource the process this object is responsible for
     */
    private $_process;
    /**
     * @var array array of process pipes [stdin,stdout,stderr]
     */
    private $_pipes;

    /**
     * @var bool if this process is synchronous (waits for output)
     */
    private $_synchronous;

    /**
     * @var int|null hold the exit code, we can only get this on the first process_status after exit
     */
    private $_exitcode = null;

    /**
     * Create and run a new process
     * Most arguments match proc_open()
     *
     * @param  string  $cmd  the command to execute
     * @param  array  $descriptorspec  the definition of pipes to initialize
     * @param  null  $cwd  working directory to change to
     * @param  array|null  $env  array of environment variables to set
     * @param  bool  $blocking  set the output pipes to blocking (default: false)
     *
     * @throws Exception the command was unable to execute
     */
    public function __construct(
        $cmd,
        $descriptorspec = [
            0 => ['pipe', 'r'],
            1 => ['pipe', 'w'],
            2 => ['pipe', 'w'],
        ],
        $cwd = null,
        $env = null,
        $blocking = false
    ) {
        $this->_process = proc_open($cmd, $descriptorspec, $this->_pipes, $cwd, $env);
        if (! is_resource($this->_process)) {
            throw new Exception("Command failed: $cmd");
        }
        stream_set_blocking($this->_pipes[1], $blocking);
        stream_set_blocking($this->_pipes[2], $blocking);
        $this->_synchronous = true;
    }

    /**
     * Called when this object goes out of scope or php exits
     * If it is still running, terminate the process
     */
    public function __destruct()
    {
        if ($this->isRunning()) {
            $this->terminate();
        }
    }

    /**
     * Get one of the pipes
     * 0 - stdin
     * 1 - stdout
     * 2 - stderr
     *
     * @param  int  $nr  pipe number (0-2)
     * @return resource the pipe handle
     */
    public function pipe($nr)
    {
        return $this->_pipes[$nr];
    }

    /**
     * Send a command to this process and return the output
     * the output may not correspond to this command if this
     * process is not synchronous
     * If the command isn't terminated with a newline, add one
     *
     * @param  string  $command
     * @return array
     */
    public function sendCommand($command)
    {
        $this->sendInput($this->checkAddEOL($command));

        return $this->getOutput();
    }

    /**
     * Send data to stdin
     *
     * @param  string  $data  the string to send
     */
    public function sendInput($data)
    {
        fwrite($this->_pipes[0], $data);
    }

    /**
     * Gets the current output of the process
     * If this process is set to synchronous, wait for output
     *
     * @param  int  $timeout  time to wait for output, only applies if this process is synchronous
     * @return array [stdout, stderr]
     */
    public function getOutput($timeout = 15)
    {
        if ($this->_synchronous) {
            $pipes = [$this->_pipes[1], $this->_pipes[2]];
            $w = null;
            $x = null;

            stream_select($pipes, $w, $x, $timeout);
        }

        return [stream_get_contents($this->_pipes[1]), stream_get_contents($this->_pipes[2])];
    }

    /**
     * Close all pipes for this process
     */
    private function closePipes()
    {
        foreach ($this->_pipes as $pipe) {
            if (is_resource($pipe)) {
                fclose($pipe);
            }
        }
    }

    /**
     * Attempt to gracefully close this process
     * optionally send one last piece of input
     * such as a quit command
     *
     * ** Warning: this will block until the process closes.
     * Some processes might not close on their own.
     *
     * @param  string  $command  the final command to send (appends newline if one is ommited)
     * @return int the exit status of this process (-1 means error)
     */
    public function close($command = null)
    {
        if (isset($command)) {
            try {
                if (is_resource($this->_pipes[0])) {
                    $this->sendInput($this->checkAddEOL($command));
                }
            } catch (\ErrorException $e) {
                // might have closed already
            }
        }

        $this->closePipes();

        return proc_close($this->_process);
    }

    /**
     * Forcibly close this process
     * Please attempt to run close() instead of this
     * This will be called when this object is destroyed if the process is still running
     *
     * @param  int  $timeout  how many microseconds to wait before terminating (SIGKILL)
     * @param  int  $signal  the signal to send
     *
     * @throws Exception
     */
    public function terminate($timeout = 3000, $signal = 15)
    {
        $status = $this->getStatus();

        $this->closePipes();

        $closed = proc_terminate($this->_process, $signal);

        $time = 0;
        while ($time < $timeout) {
            $closed = ! $this->isRunning();
            if ($closed) {
                break;
            }

            usleep(100);
            $time += 100;
        }

        if (! $closed) {
            // try harder
            if (function_exists('posix_kill')) {
                $killed = posix_kill($status['pid'], 9); //9 is the SIGKILL signal
            } else {
                $killed = proc_terminate($this->_process, 9);
            }
            proc_close($this->_process);

            if (! $killed && $this->isRunning()) {
                throw new Exception('Terminate failed!');
            }
        }
    }

    /**
     * Get the status of this process
     * see proc_get_status()
     *
     * @return array status array
     */
    public function getStatus()
    {
        $status = proc_get_status($this->_process);

        if ($status['running'] === false && is_null($this->_exitcode)) {
            $this->_exitcode = $status['exitcode'];
        }

        return $status;
    }

    /**
     * Check if this process is running
     *
     * @return bool
     */
    public function isRunning()
    {
        if (! is_resource($this->_process)) {
            return false;
        }
        $st = $this->getStatus();

        return isset($st['running']) && $st['running'];
    }

    /**
     * Returns the exit code from the process.
     * Will return null unless isRunning() or getStatus() has been run and returns false.
     *
     * @return int|null
     */
    public function getExitCode()
    {
        return $this->_exitcode;
    }

    /**
     * If this process waits for output
     *
     * @return bool
     */
    public function isSynchronous()
    {
        return $this->_synchronous;
    }

    /**
     * Set this process as synchronous, by default processes are synchronous
     * It is advisable not to change this mid way as output could get mixed up
     * or you could end up blocking until the getOutput timeout expires
     *
     * @param  bool  $synchronous
     */
    public function setSynchronous($synchronous)
    {
        $this->_synchronous = $synchronous;
    }

    /**
     * Add and end of line character to a string if
     * it doesn't already end with one
     *
     * @param  string  $string
     * @return string
     */
    private function checkAddEOL($string)
    {
        if (! Str::endsWith($string, PHP_EOL)) {
            $string .= PHP_EOL;
        }

        return $string;
    }
}