First git push to github

vendor/maennchen/zipstream-php/guides/StreamOutput.rst

@@ -0,0 +1,113 @@
+Stream Output
+===============
+
+Stream to S3 Bucket
+---------------
+
+.. code-block:: php
+
+    use Aws\S3\S3Client;
+    use Aws\Credentials\CredentialProvider;
+    use ZipStream\ZipStream;
+
+    $bucket = 'your bucket name';
+    $client = new S3Client([
+        'region' => 'your region',
+        'version' => 'latest',
+        'bucketName' => $bucket,
+        'credentials' => CredentialProvider::defaultProvider(),
+    ]);
+    $client->registerStreamWrapper();
+
+    $zipFile = fopen("s3://$bucket/example.zip", 'w');
+
+    $zip = new ZipStream(
+        enableZip64: false,
+        outputStream: $zipFile,
+    );
+
+    $zip->addFile(
+        fileName: 'file1.txt',
+        data: 'File1 data',
+    );
+    $zip->addFile(
+        fileName: 'file2.txt',
+        data: 'File2 data',
+    );
+    $zip->finish();
+
+    fclose($zipFile);
+
+Stream to Callback Function
+---------------------------
+
+The CallbackStreamWrapper allows you to stream ZIP data to a custom callback function,
+enabling flexible output handling such as streaming to multiple destinations,
+progress tracking, or data transformation.
+
+.. code-block:: php
+
+    use ZipStream\ZipStream;
+    use ZipStream\Stream\CallbackStreamWrapper;
+
+    // Example 1: Stream to multiple destinations with proper file handling
+    $backupFile = fopen('backup.zip', 'wb');
+    $logFile = fopen('transfer.log', 'ab');
+    
+    $zip = new ZipStream(
+        outputStream: CallbackStreamWrapper::open(function (string $data) use ($backupFile, $logFile) {
+            // Send to browser
+            echo $data;
+            
+            // Save to file efficiently
+            fwrite($backupFile, $data);
+            
+            // Log transfer progress
+            fwrite($logFile, "Transferred " . strlen($data) . " bytes\n");
+        }),
+        sendHttpHeaders: false,
+    );
+
+    $zip->addFile('hello.txt', 'Hello World!');
+    $zip->finish();
+    
+    // Clean up resources
+    fclose($backupFile);
+    fclose($logFile);
+
+.. code-block:: php
+
+    // Example 2: Progress tracking
+    $totalBytes = 0;
+    $zip = new ZipStream(
+        outputStream: CallbackStreamWrapper::open(function (string $data) use (&$totalBytes) {
+            $totalBytes += strlen($data);
+            reportProgress($totalBytes); // Report progress to your tracking system
+            
+            // Your actual output handling
+            echo $data;
+        }),
+        sendHttpHeaders: false,
+    );
+
+    $zip->addFile('large_file.txt', str_repeat('A', 10000));
+    $zip->finish();
+
+.. code-block:: php
+
+    // Example 3: Data transformation using PHP stream filters
+    // For data transformations, prefer PHP's built-in stream filters
+    $outputStream = fopen('php://output', 'w');
+    stream_filter_append($outputStream, 'convert.base64-encode');
+    
+    $zip = new ZipStream(
+        outputStream: $outputStream,
+        sendHttpHeaders: false,
+    );
+
+    $zip->addFile('secret.txt', 'Confidential data');
+    $zip->finish();
+    fclose($outputStream);
+
+.. note::
+   For data transformations, PHP's built-in stream filters are preferred over callback transformations. Stream filters operate at the stream level and maintain data integrity. You can register custom filters using ``stream_filter_register()`` for specialized transformations.