feat: added support for output and error streams

Author: petrknap

README.md

@@ -15,6 +15,23 @@ echo (
 )->filter('H4sIAAAAAAAAA0tJLEkEAGPz860EAAAA');
 ```
 
+If you want to process external data, redirect output or get errors, you can use input, output or error streams.
+
+```php
+namespace PetrKnap\ExternalFilter;
+
+$errorStream = fopen('php://memory', 'w+');
+
+(new Filter('php'))->filter(
+    '<?php fwrite(fopen("php://stderr", "w"), "error");',
+    error: $errorStream,
+);
+
+rewind($errorStream);
+echo stream_get_contents($errorStream);
+fclose($errorStream);
+```
+
 ---
 
 Run `composer require petrknap/external-filter` to install it.

src/Filter.php

@@ -24,25 +24,39 @@ public function __construct(
 
     /**
      * @param string|resource $input
+     * @param resource|null $output
+     * @param resource|null $error
+     *
+     * @return ($output is null ? string : null)
      *
      * @throws Exception\FilterException
      */
-    public function filter(mixed $input): string
+    public function filter(mixed $input, mixed $output = null, mixed $error = null): string|null
     {
         if (!is_string($input) && !is_resource($input)) {
             throw new class ('$input must be string|resource') extends InvalidArgumentException implements Exception\FilterException {
             };
         }
+        if ($output !== null && !is_resource($output)) {
+            throw new class ('$output must be resource|null') extends InvalidArgumentException implements Exception\FilterException {
+            };
+        }
+        if ($error !== null && !is_resource($error)) {
+            throw new class ('$error must be resource|null') extends InvalidArgumentException implements Exception\FilterException {
+            };
+        }
 
         $process = $this->startFilter($input);
-
-        $process->wait();
+        $process->wait(static fn (string $type, string $buffer) => match ($type) {
+            Process::OUT => $output === null or fwrite($output, $buffer),
+            Process::ERR => $error === null or fwrite($error, $buffer),
+            default => null,
+        });
         if (!$process->isSuccessful()) {
             throw new class ($process) extends ProcessFailedException implements Exception\FilterException {
             };
         }
-
-        return $process->getOutput();
+        return $output === null ? $process->getOutput() : null;
     }
 
     public function pipe(self $to): self

tests/FilterTest.php

@@ -36,6 +36,41 @@ public static function dataFiltersInput(): iterable
         yield 'resource(in-memory stream)' => [$inMemoryStream, $helloWorldPhpStdOut];
     }
 
+    #[DataProvider('dataWritesToStreamsAndReturnsExpectedValue')]
+    public function testWritesToStreamsAndReturnsExpectedValue(bool $useOutput, bool $useError): void
+    {
+        $outputStream = fopen('php://memory', 'w+');
+        $errorStream = fopen('php://memory', 'w+');
+
+        $returned = (new Filter('php'))->filter(
+            input: '<?php fwrite(fopen("php://stdout", "w"), "output"); fwrite(fopen("php://stderr", "w"), "error");',
+            output: $useOutput ? $outputStream : null,
+            error: $useError ? $errorStream : null,
+        );
+        rewind($outputStream);
+        rewind($errorStream);
+
+        self::assertSame([
+            'returned' => $useOutput ? null : 'output',
+            'output' => $useOutput ? 'output' : '',
+            'error' => $useError ? 'error' : '',
+        ], [
+            'returned' => $returned,
+            'output' => stream_get_contents($outputStream),
+            'error' => stream_get_contents($errorStream),
+        ]);
+    }
+
+    public static function dataWritesToStreamsAndReturnsExpectedValue(): array
+    {
+        return [
+            'no stream' => [false, false],
+            'output stream' => [true, false],
+            'error stream' => [false, true],
+            'both streams' => [true, true],
+        ];
+    }
+
     public function testBuildsAndExecutesPipeline(): void
     {
         $pipeline = (new Filter('gzip'))->pipe(new Filter('base64'))->pipe(new Filter('base64', ['--decode']));
@@ -48,20 +83,27 @@ public function testBuildsAndExecutesPipeline(): void
     }
 
     #[DataProvider('dataThrows')]
-    public function testThrows(string $command, array $options, mixed $input): void
+    public function testThrows(string $command, array $options, mixed $input, mixed $output, mixed $error): void
     {
         self::expectException(Exception\FilterException::class);
 
-        (new Filter($command, $options))->filter($input);
+        (new Filter($command, $options))->filter($input, $output, $error);
     }
 
     public static function dataThrows(): array
     {
+        $closedStream = fopen('php://memory', 'w');
+        fclose($closedStream);
         return [
-            'unknown command' => ['unknown', [], ''],
-            'unknown option' => ['php', ['--unknown'], ''],
-            'wrong data' => ['php', [], '<?php wrong data'],
-            'unsupported input' => ['php', [], new stdClass()],
+            'unknown command' => ['unknown', [], '', null, null],
+            'unknown option' => ['php', ['--unknown'], '', null, null],
+            'wrong data' => ['php', [], '<?php wrong data', null, null],
+            'unsupported input' => ['php', [], new stdClass(), null, null],
+            'unsupported output' => ['php', [], '', new stdClass(), null],
+            'unsupported error' => ['php', [], '', null, new stdClass()],
+            'closed input' => ['php', [], $closedStream, null, null],
+            'closed output' => ['php', [], '', $closedStream, null],
+            'closed error' => ['php', [], '', null, $closedStream],
         ];
     }
 }

tests/ReadmeTest.php

@@ -20,7 +20,8 @@ public static function getPathToMarkdownFile(): string
     public static function getExpectedOutputsOfPhpExamples(): iterable
     {
         return [
-            'example' => 'data',
+            'pipeline' => 'data',
+            'error-stream' => 'error',
         ];
     }
 }