Add CallbackStreamWrapper for custom ZIP output (#199)

[eyupcanakman]

Summary

This PR introduces the CallbackStreamWrapper, a new stream wrapper (zipcb://) allowing ZIP output to be sent to any custom PHP callback function.

Why

• Streaming simultaneously to multiple destinations (e.g., files, logs, browser).
• Real-time progress tracking during archive creation.
• Performing safe, byte-stream-level data transformations without temporary files.

Requested originally in #199.

What changed

• New class ZipStream\Stream\CallbackStreamWrapper (zipcb:// protocol).
  CallbackStreamWrapper::open(callable $cb) returns a writable resource for the outputStream option.
• Docs: updated README.md, guides/Options.rst, guides/StreamOutput.rst.
• Tests: new test/CallbackOutputTest.php (data integrity, multi-stream, error handling, stats, large chunks, progress).

Backward compatibility

No breaking changes. Existing code that passes a normal stream resource still works.

Closes #199

[Copilot]

Pull Request Overview

This PR adds a new CallbackStreamWrapper to allow ZIP output to be sent to any custom PHP callback, enabling streaming to multiple destinations and real-time progress tracking.

• Introduces the CallbackStreamWrapper class with the zipcb:// protocol support
• Adds comprehensive tests in CallbackOutputTest.php covering data forwarding, error handling, and stream statistics
• Updates documentation in README.md, Options.rst, and StreamOutput.rst to cover usage details

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test/CallbackOutputTest.php	New tests validating the callback stream behavior and error cases
src/Stream/CallbackStreamWrapper.php	Implements the callback stream wrapper class for ZIP streaming
guides/StreamOutput.rst	Added examples for using CallbackStreamWrapper in documentation
guides/Options.rst	Documents CallbackStreamWrapper as an option for outputStream
README.md	Demonstrates CallbackStreamWrapper usage with code examples

[maennchen]

Thanks for the PR, this looks amazing ❤️

I’m off organizing a festival this week and will have a closer look next week (Wednesday or a bit later).

[maennchen]

I don't like this example since it outputs both data and status messages to the browser which will result in an invalid zip. Can we replace this with some dummy code like reportProgress($totalBytes); or something like that?

[maennchen]

I'm not sure if I would point people to do that. There's a builtin way in PHP to deal with this kind of thing: Stream Filters

So instead you would:

$fp = fopen('php://output', 'w');
stream_filter_append($fp, "str.base64");
$zip = new ZipStream(
  outputStream: $fp,
  // ...
);

Here's how to register new filters: https://www.php.net/manual/en/function.stream-filter-register.php