[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /*
   4   * This file is part of the Symfony package.
   5   *
   6   * (c) Fabien Potencier <[email protected]>
   7   *
   8   * For the full copyright and license information, please view the LICENSE
   9   * file that was distributed with this source code.
  10   */
  11  
  12  namespace Symfony\Component\Console\Helper;
  13  
  14  use Symfony\Component\Console\Output\ConsoleOutputInterface;
  15  use Symfony\Component\Console\Output\OutputInterface;
  16  use Symfony\Component\Process\Exception\ProcessFailedException;
  17  use Symfony\Component\Process\Process;
  18  
  19  /**
  20   * The ProcessHelper class provides helpers to run external processes.
  21   *
  22   * @author Fabien Potencier <[email protected]>
  23   *
  24   * @final
  25   */
  26  class ProcessHelper extends Helper
  27  {
  28      /**
  29       * Runs an external process.
  30       *
  31       * @param array|Process $cmd      An instance of Process or an array of the command and arguments
  32       * @param callable|null $callback A PHP callback to run whenever there is some
  33       *                                output available on STDOUT or STDERR
  34       */
  35      public function run(OutputInterface $output, $cmd, string $error = null, callable $callback = null, int $verbosity = OutputInterface::VERBOSITY_VERY_VERBOSE): Process
  36      {
  37          if (!class_exists(Process::class)) {
  38              throw new \LogicException('The ProcessHelper cannot be run as the Process component is not installed. Try running "compose require symfony/process".');
  39          }
  40  
  41          if ($output instanceof ConsoleOutputInterface) {
  42              $output = $output->getErrorOutput();
  43          }
  44  
  45          $formatter = $this->getHelperSet()->get('debug_formatter');
  46  
  47          if ($cmd instanceof Process) {
  48              $cmd = [$cmd];
  49          }
  50  
  51          if (!\is_array($cmd)) {
  52              throw new \TypeError(sprintf('The "command" argument of "%s()" must be an array or a "%s" instance, "%s" given.', __METHOD__, Process::class, get_debug_type($cmd)));
  53          }
  54  
  55          if (\is_string($cmd[0] ?? null)) {
  56              $process = new Process($cmd);
  57              $cmd = [];
  58          } elseif (($cmd[0] ?? null) instanceof Process) {
  59              $process = $cmd[0];
  60              unset($cmd[0]);
  61          } else {
  62              throw new \InvalidArgumentException(sprintf('Invalid command provided to "%s()": the command should be an array whose first element is either the path to the binary to run or a "Process" object.', __METHOD__));
  63          }
  64  
  65          if ($verbosity <= $output->getVerbosity()) {
  66              $output->write($formatter->start(spl_object_hash($process), $this->escapeString($process->getCommandLine())));
  67          }
  68  
  69          if ($output->isDebug()) {
  70              $callback = $this->wrapCallback($output, $process, $callback);
  71          }
  72  
  73          $process->run($callback, $cmd);
  74  
  75          if ($verbosity <= $output->getVerbosity()) {
  76              $message = $process->isSuccessful() ? 'Command ran successfully' : sprintf('%s Command did not run successfully', $process->getExitCode());
  77              $output->write($formatter->stop(spl_object_hash($process), $message, $process->isSuccessful()));
  78          }
  79  
  80          if (!$process->isSuccessful() && null !== $error) {
  81              $output->writeln(sprintf('<error>%s</error>', $this->escapeString($error)));
  82          }
  83  
  84          return $process;
  85      }
  86  
  87      /**
  88       * Runs the process.
  89       *
  90       * This is identical to run() except that an exception is thrown if the process
  91       * exits with a non-zero exit code.
  92       *
  93       * @param array|Process $cmd      An instance of Process or a command to run
  94       * @param callable|null $callback A PHP callback to run whenever there is some
  95       *                                output available on STDOUT or STDERR
  96       *
  97       * @throws ProcessFailedException
  98       *
  99       * @see run()
 100       */
 101      public function mustRun(OutputInterface $output, $cmd, string $error = null, callable $callback = null): Process
 102      {
 103          $process = $this->run($output, $cmd, $error, $callback);
 104  
 105          if (!$process->isSuccessful()) {
 106              throw new ProcessFailedException($process);
 107          }
 108  
 109          return $process;
 110      }
 111  
 112      /**
 113       * Wraps a Process callback to add debugging output.
 114       */
 115      public function wrapCallback(OutputInterface $output, Process $process, callable $callback = null): callable
 116      {
 117          if ($output instanceof ConsoleOutputInterface) {
 118              $output = $output->getErrorOutput();
 119          }
 120  
 121          $formatter = $this->getHelperSet()->get('debug_formatter');
 122  
 123          return function ($type, $buffer) use ($output, $process, $callback, $formatter) {
 124              $output->write($formatter->progress(spl_object_hash($process), $this->escapeString($buffer), Process::ERR === $type));
 125  
 126              if (null !== $callback) {
 127                  $callback($type, $buffer);
 128              }
 129          };
 130      }
 131  
 132      private function escapeString(string $str): string
 133      {
 134          return str_replace('<', '\\<', $str);
 135      }
 136  
 137      /**
 138       * {@inheritdoc}
 139       */
 140      public function getName(): string
 141      {
 142          return 'process';
 143      }
 144  }