Custom callable

src/Connection.php

@@ -40,8 +40,6 @@ public function __construct(
 
     /**
      * Checks if the given connection is the same as this one.
-     *
-     * @param  \ProtoneMedia\LaravelTaskRunner\Connection  $connection
      */
     public function is(Connection $connection): bool
     {

src/PendingTask.php

@@ -19,6 +19,11 @@ class PendingTask
 
     private ?string $outputPath = null;
 
+    /**
+     * @var callable|null
+     */
+    private $onOutput = null;
+
     public function __construct(
         public readonly Task $task
     ) {
@@ -36,10 +41,26 @@ public static function make(string|Task|PendingTask $task): static
         return $task instanceof PendingTask ? $task : new PendingTask($task);
     }
 
+    /**
+     * A PHP callback to run whenever there is some output available on STDOUT or STDERR.
+     */
+    public function onOutput(callable $callback): self
+    {
+        $this->onOutput = $callback;
+
+        return $this;
+    }
+
+    /**
+     * Returns the callback that should be run whenever there is some output available on STDOUT or STDERR.
+     */
+    public function getOnOutput(): ?callable
+    {
+        return $this->onOutput;
+    }
+
     /**
      * Returns the connection, if set.
-     *
-     * @return \ProtoneMedia\LaravelTaskRunner\Connection|null
      */
     public function getConnection(): ?Connection
     {
@@ -48,8 +69,6 @@ public function getConnection(): ?Connection
 
     /**
      * Setter for the connection.
-     *
-     * @param  string|\ProtoneMedia\LaravelTaskRunner\Connection  $connection
      */
     public function onConnection(string|Connection $connection): self
     {
@@ -142,8 +161,6 @@ public function writeOutputTo(string $outputPath = null): self
 
     /**
      * Checks if the given connection is the same as the connection of this task.
-     *
-     * @param  bool|string|\ProtoneMedia\LaravelTaskRunner\Connection|callable|null  $connection
      */
     public function shouldRunOnConnection(bool|string|Connection|callable $connection = null): bool
     {
@@ -189,9 +206,6 @@ public function storeInTemporaryDirectory(): string
 
     /**
      * Dispatches the task to the given task runner.
-     *
-     * @param  \ProtoneMedia\LaravelTaskRunner\TaskDispatcher|null  $taskDispatcher
-     * @return \ProtoneMedia\LaravelTaskRunner\ProcessOutput|null
      */
     public function dispatch(TaskDispatcher $taskDispatcher = null): ?ProcessOutput
     {

src/ProcessOutput.php

@@ -14,6 +14,21 @@ class ProcessOutput
 
     private ?ProcessResult $illuminateResult = null;
 
+    /**
+     * @var callable|null
+     */
+    private $onOutput = null;
+
+    /**
+     * A PHP callback to run whenever there is some output available on STDOUT or STDERR.
+     */
+    public function onOutput(callable $callback): self
+    {
+        $this->onOutput = $callback;
+
+        return $this;
+    }
+
     /**
      * Appends the buffer to the output.
      *
@@ -23,6 +38,10 @@ class ProcessOutput
     public function __invoke(string $type, $buffer)
     {
         $this->buffer .= $buffer;
+
+        if ($this->onOutput) {
+            ($this->onOutput)($type, $buffer);
+        }
     }
 
     /**

src/ProcessRunner.php

@@ -9,12 +9,16 @@ class ProcessRunner
 {
     /**
      * Runs the given process and waits for it to finish.
-     *
-     * @return \ProtoneMedia\LaravelTaskRunner\ProcessOutput
      */
-    public function run(PendingProcess $process): ProcessOutput
+    public function run(PendingProcess $process, callable $onOutput = null): ProcessOutput
     {
-        return tap(new ProcessOutput, function (ProcessOutput $output) use ($process) {
+        $output = new ProcessOutput;
+
+        if ($onOutput) {
+            $output->onOutput($onOutput);
+        }
+
+        return tap($output, function (ProcessOutput $output) use ($process) {
             $timeout = false;
 
             try {

src/RemoteProcessRunner.php

@@ -7,12 +7,27 @@
 
 class RemoteProcessRunner
 {
+    /**
+     * @var callable|null
+     */
+    private $onOutput = null;
+
     public function __construct(
         private Connection $connection,
         private ProcessRunner $processRunner
     ) {
     }
 
+    /**
+     * A PHP callback to run whenever there is some output available on STDOUT or STDERR.
+     */
+    public function onOutput(callable $callback): self
+    {
+        $this->onOutput = $callback;
+
+        return $this;
+    }
+
     /**
      * Runs the full path of given script on the remote server.
      */
@@ -61,8 +76,6 @@ private function sshOptions(): array
 
     /**
      * Formats the script and output paths, and runs the script.
-     *
-     * @return \ProtoneMedia\LaravelTaskRunner\ProcessOutput
      */
     public function runUploadedScript(string $script, string $output, int $timeout = 0): ProcessOutput
     {
@@ -74,8 +87,6 @@ public function runUploadedScript(string $script, string $output, int $timeout =
 
     /**
      * Formats the script and output paths, and runs the script in the background.
-     *
-     * @return \ProtoneMedia\LaravelTaskRunner\ProcessOutput
      */
     public function runUploadedScriptInBackground(string $script, string $output, int $timeout = 0): ProcessOutput
     {
@@ -90,8 +101,6 @@ public function runUploadedScriptInBackground(string $script, string $output, in
 
     /**
      * Wraps the script in a bash subshell command, and runs it over SSH.
-     *
-     * @return \ProtoneMedia\LaravelTaskRunner\ProcessOutput
      */
     private function run(string $script, int $timeout = 0): ProcessOutput
     {
@@ -104,17 +113,15 @@ private function run(string $script, int $timeout = 0): ProcessOutput
         ]);
 
         $output = $this->processRunner->run(
-            FacadesProcess::command($command)->timeout($timeout > 0 ? $timeout : null)
+            FacadesProcess::command($command)->timeout($timeout > 0 ? $timeout : null),
+            $this->onOutput
         );
 
         return $this->cleanupOutput($output);
     }
 
     /**
      * Removes the known hosts warning from the output.
-     *
-     * @param  \ProtoneMedia\LaravelTaskRunner\ProcessOutput  $processOutput
-     * @return \ProtoneMedia\LaravelTaskRunner\ProcessOutput
      */
     private function cleanupOutput(ProcessOutput $processOutput): ProcessOutput
     {

src/Task.php

@@ -38,8 +38,6 @@ public function getName(): string
 
     /**
      * Returns the timeout of the task in seconds.
-     *
-     * @return int
      */
     public function getTimeout(): ?int
     {
@@ -148,8 +146,6 @@ public function getScript(): string
 
     /**
      * Returns a new PendingTask with this task.
-     *
-     * @return \ProtoneMedia\LaravelTaskRunner\PendingTask
      */
     public function pending(): PendingTask
     {
@@ -158,8 +154,6 @@ public function pending(): PendingTask
 
     /**
      * Returns a new PendingTask with this task.
-     *
-     * @return \ProtoneMedia\LaravelTaskRunner\PendingTask
      */
     public static function make(...$arguments): PendingTask
     {

src/TaskDispatcher.php

@@ -28,8 +28,6 @@ public function __construct(private ProcessRunner $processRunner)
 
     /**
      * Runs the given task.
-     *
-     * @return null|\ProtoneMedia\LaravelTaskRunner\ProcessOutput
      */
     public function run(PendingTask $pendingTask): ?ProcessOutput
     {
@@ -79,8 +77,6 @@ private function runInBackground(PendingTask $pendingTask)
 
     /**
      * Runs the given task on the given connection.
-     *
-     * @return \ProtoneMedia\LaravelTaskRunner\ProcessOutput
      */
     private function runOnConnection(PendingTask $pendingTask): ProcessOutput
     {
@@ -90,6 +86,10 @@ private function runOnConnection(PendingTask $pendingTask): ProcessOutput
             ['connection' => $pendingTask->getConnection(), 'processRunner' => $this->processRunner]
         );
 
+        if ($outputCallbable = $pendingTask->getOnOutput()) {
+            $runner->onOutput($outputCallbable);
+        }
+
         $id = $pendingTask->getId() ?: Str::random(32);
 
         $runner->verifyScriptDirectoryExists()->upload("{$id}.sh", $pendingTask->task->getScript());