[Process] Improve typing for process callback

jack-worman · nicolas-grekas · commit 56cc4ffeb142 · 2025-06-04T15:36:34.000+02:00
diff --git a/src/Symfony/Component/Process/PhpProcess.php b/src/Symfony/Component/Process/PhpProcess.php
@@ -55,6 +55,9 @@ public static function fromShellCommandline(string $command, ?string $cwd = null
         throw new LogicException(\sprintf('The "%s()" method cannot be called when using "%s".', __METHOD__, self::class));
     }
 
+    /**
+     * @param (callable('out'|'err', string):void)|null $callback
+     */
     public function start(?callable $callback = null, array $env = []): void
     {
         if (null === $this->getCommandLine()) {
diff --git a/src/Symfony/Component/Process/PhpSubprocess.php b/src/Symfony/Component/Process/PhpSubprocess.php
@@ -78,6 +78,9 @@ public static function fromShellCommandline(string $command, ?string $cwd = null
         throw new LogicException(\sprintf('The "%s()" method cannot be called when using "%s".', __METHOD__, self::class));
     }
 
+    /**
+     * @param (callable('out'|'err', string):void)|null $callback
+     */
     public function start(?callable $callback = null, array $env = []): void
     {
         if (null === $this->getCommandLine()) {
diff --git a/src/Symfony/Component/Process/Process.php b/src/Symfony/Component/Process/Process.php
@@ -51,6 +51,9 @@ class Process implements \IteratorAggregate
     public const ITER_SKIP_OUT = 4;     // Use this flag to skip STDOUT while iterating
     public const ITER_SKIP_ERR = 8;     // Use this flag to skip STDERR while iterating
 
+    /**
+     * @var \Closure('out'|'err', string)|null
+     */
     private ?\Closure $callback = null;
     private array|string $commandline;
     private ?string $cwd;
@@ -231,8 +234,8 @@ public function __clone()
      * The STDOUT and STDERR are also available after the process is finished
      * via the getOutput() and getErrorOutput() methods.
      *
-     * @param callable|null $callback A PHP callback to run whenever there is some
-     *                                output available on STDOUT or STDERR
+     * @param (callable('out'|'err', string):void)|null $callback A PHP callback to run whenever there is somed
+     *                                                            output available on STDOUT or STDERR
      *
      * @return int The exit status code
      *
@@ -257,6 +260,9 @@ public function run(?callable $callback = null, array $env = []): int
      * This is identical to run() except that an exception is thrown if the process
      * exits with a non-zero exit code.
      *
+     * @param (callable('out'|'err', string):void)|null $callback A PHP callback to run whenever there is some
+     *                                                            output available on STDOUT or STDERR
+     *
      * @return $this
      *
      * @throws ProcessFailedException if the process didn't terminate successfully
@@ -284,8 +290,8 @@ public function mustRun(?callable $callback = null, array $env = []): static
      * the output in real-time while writing the standard input to the process.
      * It allows to have feedback from the independent process during execution.
      *
-     * @param callable|null $callback A PHP callback to run whenever there is some
-     *                                output available on STDOUT or STDERR
+     * @param (callable('out'|'err', string):void)|null $callback A PHP callback to run whenever there is some
+     *                                                            output available on STDOUT or STDERR
      *
      * @throws ProcessStartFailedException When process can't be launched
      * @throws RuntimeException            When process is already running
@@ -395,8 +401,8 @@ public function start(?callable $callback = null, array $env = []): void
      *
      * Be warned that the process is cloned before being started.
      *
-     * @param callable|null $callback A PHP callback to run whenever there is some
-     *                                output available on STDOUT or STDERR
+     * @param (callable('out'|'err', string):void)|null $callback A PHP callback to run whenever there is some
+     *                                                            output available on STDOUT or STDERR
      *
      * @throws ProcessStartFailedException When process can't be launched
      * @throws RuntimeException            When process is already running
@@ -424,7 +430,8 @@ public function restart(?callable $callback = null, array $env = []): static
      * from the output in real-time while writing the standard input to the process.
      * It allows to have feedback from the independent process during execution.
      *
-     * @param callable|null $callback A valid PHP callback
+     * @param (callable('out'|'err', string):void)|null $callback A PHP callback to run whenever there is some
+     *                                                            output available on STDOUT or STDERR
      *
      * @return int The exitcode of the process
      *
@@ -471,6 +478,9 @@ public function wait(?callable $callback = null): int
      * from the output in real-time while writing the standard input to the process.
      * It allows to have feedback from the independent process during execution.
      *
+     * @param (callable('out'|'err', string):void)|null $callback A PHP callback to run whenever there is some
+     *                                                            output available on STDOUT or STDERR
+     *
      * @throws RuntimeException         When process timed out
      * @throws LogicException           When process is not yet started
      * @throws ProcessTimedOutException In case the timeout was reached
@@ -1291,22 +1301,21 @@ private function getDescriptors(bool $hasCallback): array
      * The callbacks adds all occurred output to the specific buffer and calls
      * the user callback (if present) with the received output.
      *
-     * @param callable|null $callback The user defined PHP callback
+     * @param callable('out'|'err', string)|null $callback
+     *
+     * @return \Closure('out'|'err', string)
      */
     protected function buildCallback(?callable $callback = null): \Closure
     {
         if ($this->outputDisabled) {
-            return fn ($type, $data): bool => null !== $callback && $callback($type, $data);
+            return fn ($type, $data) => null !== $callback && $callback($type, $data);
         }
 
-        $out = self::OUT;
-
-        return function ($type, $data) use ($callback, $out): bool {
-            if ($out == $type) {
-                $this->addOutput($data);
-            } else {
-                $this->addErrorOutput($data);
-            }
+        return function (string $type, string $data) use ($callback): bool {
+            match ($type) {
+                self::OUT => $this->addOutput($data),
+                self::ERR => $this->addErrorOutput($data),
+            };
 
             return null !== $callback && $callback($type, $data);
         };

Original file line number	Diff line number	Diff line change
`@@ -55,6 +55,9 @@ public static function fromShellCommandline(string $command, ?string $cwd = null`
`55`	`55`	`throw new LogicException(\sprintf('The "%s()" method cannot be called when using "%s".', __METHOD__, self::class));`
`56`	`56`	`}`
`57`	`57`
	`58`	`+ /**`
	`59`	`+ * @param (callable('out'\|'err', string):void)\|null $callback`
	`60`	`+ */`
`58`	`61`	`public function start(?callable $callback = null, array $env = []): void`
`59`	`62`	`{`
`60`	`63`	`if (null === $this->getCommandLine()) {`
Original file line number	Diff line number	Diff line change
`@@ -78,6 +78,9 @@ public static function fromShellCommandline(string $command, ?string $cwd = null`
`78`	`78`	`throw new LogicException(\sprintf('The "%s()" method cannot be called when using "%s".', __METHOD__, self::class));`
`79`	`79`	`}`
`80`	`80`
	`81`	`+ /**`
	`82`	`+ * @param (callable('out'\|'err', string):void)\|null $callback`
	`83`	`+ */`
`81`	`84`	`public function start(?callable $callback = null, array $env = []): void`
`82`	`85`	`{`
`83`	`86`	`if (null === $this->getCommandLine()) {`