Add ZipStreamWriter to stream-write zip archives on PHP 7.2+ (#103)

This pull request introduces enhancements to the `ZipStreamWriter`
class, enabling efficient file streaming and compression when writing
ZIP archives. Key features include:

1. **Streaming File into ZIP**: Implements a method to stream a file
from disk directly into a ZIP archive without loading the entire file
into memory.
2. **Handling Central Directory**: Implements a method to write the
central directory entries and the end-of-central-directory record,
finalizing the ZIP archive.
3. **Deflate Compression**: Supports optional deflate compression for
files being added to the ZIP archive.

Closes #88

### Major Changes
1. **`writeFileFromPath` Method**:
   - Reads the source file from disk in two passes:
- First pass: Computes CRC32, uncompressed size, and compressed size
without buffering the entire file.
- Second pass: Streams the file's compressed data directly into the ZIP
archive.
   - Supports deflate compression using `deflate_add`.

2. **`flush_directory_index` Method**:
   - Collects and writes central directory entries to the ZIP stream.
- Writes the end-of-central-directory record to finalize the ZIP
structure.

### Example Usage

```php
use WordPress\Zip\ZipStreamWriter;

// File paths
$sourcePathOnDisk = '/path/to/source/file.txt';
$targetPathInZip = 'archive/file.txt';

// Create a file pointer for the output ZIP file
$zipFilePointer = fopen('output.zip', 'wb');

// Instantiate the ZipStreamWriter
$zipWriter = new ZipStreamWriter($zipFilePointer);

// Write a file from the filesystem into the ZIP archive
$zipWriter->writeFileFromPath($sourcePathOnDisk, $targetPathInZip, true); // Use 'false' for no compression

// Finalize the ZIP file
$zipWriter->flush_directory_index();

fclose($zipFilePointer);
```


### How to Test

1. Clone the repository and checkout the branch with these changes.
2. Ensure PHPUnit is installed.
3. Run the test suite using the command:
   ```sh
   vendor/bin/phpunit
   ```
4. Verify that all tests pass, indicating the functionality works as
expected.

### Notes

- This implementation aims to handle large files efficiently by
streaming data in chunks.
- The `flush_directory_index` method should be called once all file
entries have been written to ensure the ZIP archive is finalized
correctly.

Feel free to provide any feedback or request further modifications as
needed.

---------

Co-authored-by: Michael Reichardt <30837295+reimic@users.noreply.github.com>

Author: adamziel

.github/workflows/phpunit-tests-run.yml

@@ -36,6 +36,7 @@ jobs:
         with:
           php-version: '${{ inputs.php }}'
           tools: phpunit-polyfills
+          extensions: zip
 
       - name: Install Composer dependencies
         uses: ramsey/composer-install@v3

.github/workflows/phpunit-tests.yml

@@ -17,7 +17,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ ubuntu-latest, macos-latest, windows-latest ]
-        php: [ '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3' ]
+        php: [ '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3' ]
 
     with:
       os: ${{ matrix.os }}

src/WordPress/Zip/ZipCentralDirectoryEntry.php

@@ -4,6 +4,8 @@
 
 class ZipCentralDirectoryEntry {
 
+	const HEADER_SIZE = 46;
+
 	public $isDirectory;
 	public $firstByteAt;
 	public $versionCreated;
@@ -18,7 +20,6 @@ class ZipCentralDirectoryEntry {
 	public $diskNumber;
 	public $internalAttributes;
 	public $externalAttributes;
-	public $lastByteAt;
 	public $path;
 	public $extra;
 	public $fileComment;
@@ -37,15 +38,13 @@ public function __construct(
 		int $internalAttributes,
 		int $externalAttributes,
 		int $firstByteAt,
-		int $lastByteAt,
 		string $path,
 		string $extra,
 		string $fileComment
 	) {
 		$this->fileComment        = $fileComment;
 		$this->extra              = $extra;
 		$this->path               = $path;
-		$this->lastByteAt         = $lastByteAt;
 		$this->externalAttributes = $externalAttributes;
 		$this->internalAttributes = $internalAttributes;
 		$this->diskNumber         = $diskNumber;
@@ -65,4 +64,13 @@ public function __construct(
 	public function isFileEntry() {
 		return false;
 	}
+
+	public function size() {
+		return (
+			self::HEADER_SIZE +
+			strlen($this->path) +
+			strlen($this->extra) +
+			strlen($this->fileComment)
+		);
+	}
 }

src/WordPress/Zip/ZipFileEntry.php

@@ -3,6 +3,14 @@
 namespace WordPress\Zip;
 
 class ZipFileEntry {
+
+	/**
+	 * The size of the ZIP file entry header in bytes.
+	 * 
+	 * @var int
+	 */
+	const HEADER_SIZE = 30;
+
 	/**
 	 * @var bool
 	 */
@@ -58,7 +66,7 @@ public function __construct(
 		int $compressionMethod,
 		int $lastModifiedTime,
 		int $lastModifiedDate,
-		int $crc,
+		$crc,
 		int $compressedSize,
 		int $uncompressedSize,
 		string $path,
@@ -82,4 +90,13 @@ public function __construct(
 	public function isFileEntry() {
 		return true;
 	}
+
+	public function size() {
+		return (
+			self::HEADER_SIZE + 
+			strlen($this->path) + 
+			strlen($this->extra) + 
+			$this->compressedSize
+		);
+	}
 }