Added support for output and error streams

[petrknap]

• This pull request does not contain any breaking change.
• I asked the AI to briefly summarize, use and improve the feature(s), and I'm okay with the output:

Could you briefly summarize the filter methods $output and $error params from the following code for me?

final class Filter
{
    public function __construct(
        private readonly string $command,
        private readonly array $options = [],
    ) {}

    /**
     * @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|null {/* ... */}

    public function pipe(self $to): self {/* ... */}
}

In the filter method of the Filter class, the $output and $error parameters are used to manage the results of the filtering operation.

$output Parameter

• Type: resource|null
• Purpose: This parameter can be used to provide a stream resource (like a file handle or a memory stream) where the output of the filter operation will be written. If $output is null, the method returns a string containing the result of the filter operation.

$error Parameter

• Type: resource|null
• Purpose: This parameter can be used to provide a stream resource where any error messages or logs related to the filtering operation will be written. If no resource is provided, error handling is managed differently within the method.

Return Value

• If $output is null, the method returns the filtered result as a string.
• If $output is provided (i.e., not null), the method writes the filtered result to the specified resource and returns null.

Summary: The $output and $error parameters allow the method to be flexible in terms of where it writes its results and errors, either to streams or as return values. This design enables better control over output and error handling, making the filter method adaptable for different use cases.

Could you show me how to use it?

Certainly! Here's an example showing how to use the filter method with the $output and $error parameters:

// Open a memory stream for output
$outputStream = fopen('php://memory', 'w+');
// Open a memory stream for error handling (optional)
$errorStream = fopen('php://memory', 'w+');

// Create a filter instance
$filter = new Filter('exampleCommand');

// Use the filter method with a string input and output to a memory stream
$inputString = "Input data";
$filter->filter($inputString, $outputStream, $errorStream);

// Rewind and read the output stream content
rewind($outputStream);
$outputData = stream_get_contents($outputStream);
echo "Output: " . $outputData . PHP_EOL;

// Rewind and read the error stream content (if any)
rewind($errorStream);
$errorData = stream_get_contents($errorStream);
echo "Error: " . $errorData . PHP_EOL;

// Close the streams
fclose($outputStream);
fclose($errorStream);

Is there any way to name the parameters better?

Sure! Here are some suggestions to improve the clarity of your parameter names:

For $input:

• $data
• $content
• $inputData

For $output:

• $outputStream
• $destinationStream
• $resultStream

For $error:

• $errorStream
• $errorLog
• $errorOutput

These new names aim to be more descriptive, making it clearer what each parameter represents. Choose the ones that best fit the context of your application and make your code more readable.