Zip

Read and write ZIP archives in pure PHP — no libzip, no ZipArchive. Streams entries one at a time, so you can build EPUBs, .docx files, and multi-gigabyte plugin bundles without buffering the archive in memory.

composer require wp-php-toolkit/zip

Common PHP ZIP workflows rely on the ZipArchive extension or shelling out to zip. Those are awkward in hosts without libzip, WebAssembly builds, and code paths that need to stream archive data through toolkit byte streams.

The Zip component reads and writes Stored and Deflate archives in pure PHP. The decoder is pull-based, so listing the central directory of a 2 GB ZIP costs roughly the size of the directory itself. The encoder accepts any ByteWriteStream as a sink and writes one entry at a time.

Read a file out of a ZIP

ZipFilesystem implements this toolkit's Filesystem interface, so once you wrap the byte reader you can call get_contents(), ls(), and is_dir() just like the other filesystem backends.

Try this: after Run, add a second append_file() call before $enc->close() for a notes.md entry, then call print_r( $zip->ls( '/' ) ) at the end. The directory listing reflects the new entry without re-reading the file.

<?php
require '/wordpress/wp-content/php-toolkit/vendor/autoload.php';

use WordPress\ByteStream\MemoryPipe;
use WordPress\ByteStream\ReadStream\FileReadStream;
use WordPress\ByteStream\WriteStream\FileWriteStream;
use WordPress\Zip\FileEntry;
use WordPress\Zip\ZipDecoder;
use WordPress\Zip\ZipEncoder;
use WordPress\Zip\ZipFilesystem;

$path = tempnam( sys_get_temp_dir(), 'demo' ) . '.zip';
$out  = FileWriteStream::from_path( $path, 'truncate' );
$enc  = new ZipEncoder( $out );
$enc->append_file( new FileEntry( array(
	'path'               => 'readme.txt',
	'compression_method' => ZipDecoder::COMPRESSION_NONE,
	'body_reader'        => new MemoryPipe( 'Hello from inside the zip.' ),
) ) );
$enc->close();
$out->close_writing();

$zip = ZipFilesystem::create( FileReadStream::from_path( $path ) );
echo $zip->get_contents( 'readme.txt' );

Build an EPUB from scratch

An EPUB follows one strict ZIP rule: write the mimetype entry first and store it without compression. Deflate the rest of the archive normally.

<?php
require '/wordpress/wp-content/php-toolkit/vendor/autoload.php';

use WordPress\ByteStream\MemoryPipe;
use WordPress\ByteStream\ReadStream\FileReadStream;
use WordPress\ByteStream\WriteStream\FileWriteStream;
use WordPress\Zip\FileEntry;
use WordPress\Zip\ZipDecoder;
use WordPress\Zip\ZipEncoder;
use WordPress\Zip\ZipFilesystem;

$path = tempnam( sys_get_temp_dir(), 'book' ) . '.epub';
$out  = FileWriteStream::from_path( $path, 'truncate' );
$enc  = new ZipEncoder( $out );

// 1) The mimetype entry MUST be first and stored uncompressed.
$enc->append_file( new FileEntry( array(
	'path'               => 'mimetype',
	'compression_method' => ZipDecoder::COMPRESSION_NONE,
	'body_reader'        => new MemoryPipe( 'application/epub+zip' ),
) ) );

$container = <<<'XML'
<?xml version="1.0"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
<rootfiles><rootfile full-path="EPUB/package.opf" media-type="application/oebps-package+xml"/></rootfiles>
</container>
XML;

foreach ( array(
	'META-INF/container.xml' => $container,
	'EPUB/package.opf'       => <<<'XML'
<package version="3.0" xmlns="http://www.idpf.org/2007/opf"><metadata/><manifest/><spine/></package>',
	'EPUB/chapter1.xhtml'    => <<<'XML'
<html xmlns="http://www.w3.org/1999/xhtml"><body><h1>Chapter 1</h1><p>It was a dark and stormy night.</p></body></html>
XML,
) as $name => $body ) {
	$enc->append_file( new FileEntry( array(
		'path'               => $name,
		'compression_method' => ZipDecoder::COMPRESSION_DEFLATE,
		'body_reader'        => new MemoryPipe( $body ),
	) ) );
}
$enc->close();
$out->close_writing();

$zip = ZipFilesystem::create( FileReadStream::from_path( $path ) );
printf( "mimetype: %s\n", $zip->get_contents( 'mimetype' ) );
printf( "size on disk: %d bytes\n", filesize( $path ) );

Stream a large entry without buffering it

Calling get_contents() on a 500 MB CSV inside a ZIP would eat 500 MB of RAM. Use open_read_stream() instead and inflate-as-you-go.

<?php
require '/wordpress/wp-content/php-toolkit/vendor/autoload.php';

use WordPress\ByteStream\MemoryPipe;
use WordPress\ByteStream\ReadStream\FileReadStream;
use WordPress\ByteStream\WriteStream\FileWriteStream;
use WordPress\Zip\FileEntry;
use WordPress\Zip\ZipDecoder;
use WordPress\Zip\ZipEncoder;
use WordPress\Zip\ZipFilesystem;

$path = tempnam( sys_get_temp_dir(), 'big' ) . '.zip';
$out  = FileWriteStream::from_path( $path, 'truncate' );
$enc  = new ZipEncoder( $out );
$enc->append_file( new FileEntry( array(
	'path'               => 'data.csv',
	'compression_method' => ZipDecoder::COMPRESSION_DEFLATE,
	'body_reader'        => new MemoryPipe( str_repeat( "id,value,timestamp\n1,foo,2024\n2,bar,2024\n", 5000 ) ),
) ) );
$enc->close();
$out->close_writing();

$zip    = ZipFilesystem::create( FileReadStream::from_path( $path ) );
$stream = $zip->open_read_stream( 'data.csv' );

$rows  = 0;
$bytes = 0;
$tail  = '';
while ( ! $stream->reached_end_of_data() ) {
	$n = $stream->pull( 8192 );
	if ( 0 === $n ) break;
	$chunk  = $tail . $stream->consume( $n );
	$lines  = explode( "\n", $chunk );
	$tail   = array_pop( $lines );
	$rows  += count( $lines );
	$bytes += $n;
}
printf( "Inflated %d bytes in 8 KB chunks, parsed %d rows.\n", $bytes, $rows );

Repack: modify one file, copy the rest

Updating one file in a ZIP without rewriting the others is impossible at the format level — the central directory points at byte offsets. The pragmatic answer is repack: stream the source archive into a new one, swapping the file you care about.

<?php
require '/wordpress/wp-content/php-toolkit/vendor/autoload.php';

use WordPress\ByteStream\MemoryPipe;
use WordPress\ByteStream\ReadStream\FileReadStream;
use WordPress\ByteStream\WriteStream\FileWriteStream;
use WordPress\Zip\FileEntry;
use WordPress\Zip\ZipDecoder;
use WordPress\Zip\ZipEncoder;
use WordPress\Zip\ZipFilesystem;

$src_path = tempnam( sys_get_temp_dir(), 'orig' ) . '.zip';
$src_out  = FileWriteStream::from_path( $src_path, 'truncate' );
$src_enc  = new ZipEncoder( $src_out );
foreach ( array(
	'config.json'   => '{"debug":false,"version":"1.0"}',
	'app/index.php' => <<<'HTML'
<?php echo "hello";
XML,
	'app/style.css' => 'body{color:#333}
HTML,
) as $name => $body ) {
	$src_enc->append_file( new FileEntry( array(
		'path'               => $name,
		'compression_method' => ZipDecoder::COMPRESSION_DEFLATE,
		'body_reader'        => new MemoryPipe( $body ),
	) ) );
}
$src_enc->close();
$src_out->close_writing();

$source   = ZipFilesystem::create( FileReadStream::from_path( $src_path ) );
$dst_path = tempnam( sys_get_temp_dir(), 'repacked' ) . '.zip';
$dst_out  = FileWriteStream::from_path( $dst_path, 'truncate' );
$dst_enc  = new ZipEncoder( $dst_out );

$dirs = array( '/' );
while ( $dirs ) {
	$dir = array_shift( $dirs );
	foreach ( $source->ls( $dir ) as $name ) {
		$path = rtrim( $dir, '/' ) . '/' . $name;
		if ( $source->is_dir( $path ) ) {
			$dirs[] = $path;
			continue;
		}
		$rel  = ltrim( $path, '/' );
		$body = ( 'config.json' === $rel )
			? '{"debug":true,"version":"1.0.1"}'
			: $source->get_contents( $rel );
		$dst_enc->append_file( new FileEntry( array(
			'path'               => $rel,
			'compression_method' => ZipDecoder::COMPRESSION_DEFLATE,
			'body_reader'        => new MemoryPipe( $body ),
		) ) );
	}
}
$dst_enc->close();
$dst_out->close_writing();

$repacked = ZipFilesystem::create( FileReadStream::from_path( $dst_path ) );
echo "new config.json: " . $repacked->get_contents( 'config.json' ) . "\n";
echo "untouched: " . $repacked->get_contents( 'app/index.php' ) . "\n";

Defend against zip-slip

A malicious archive can name an entry ../../etc/passwd and trick a naive extractor into clobbering files outside the destination. ZipDecoder::sanitize_path() strips leading ../ segments and collapses internal /../ sequences before exposing the path.

<?php
require '/wordpress/wp-content/php-toolkit/vendor/autoload.php';

use WordPress\Zip\ZipDecoder;

$evil_inputs = array(
	'../../etc/passwd',
	'./safe/path.txt',
	'a/../../b/secret',
	'a//b///c.txt',
	'../../../../root/.ssh/authorized_keys',
);
foreach ( $evil_inputs as $name ) {
	printf( "%-45s => %s\n", $name, ZipDecoder::sanitize_path( $name ) );
}

Pipe ZIP entries into an InMemoryFilesystem

Real-world recipe: take an uploaded plugin ZIP, expand it into an InMemoryFilesystem so you can validate, edit, or scan it before it ever touches disk. Three components compose into something you couldn't build with ZipArchive alone.

<?php
require '/wordpress/wp-content/php-toolkit/vendor/autoload.php';

use WordPress\ByteStream\MemoryPipe;
use WordPress\ByteStream\ReadStream\FileReadStream;
use WordPress\ByteStream\WriteStream\FileWriteStream;
use WordPress\Filesystem\InMemoryFilesystem;
use WordPress\Zip\FileEntry;
use WordPress\Zip\ZipDecoder;
use WordPress\Zip\ZipEncoder;
use WordPress\Zip\ZipFilesystem;
use function WordPress\Filesystem\copy_between_filesystems;

$path = tempnam( sys_get_temp_dir(), 'app' ) . '.zip';
$out  = FileWriteStream::from_path( $path, 'truncate' );
$enc  = new ZipEncoder( $out );
foreach ( array(
	'app/index.php'        => <<<'HTML'
<?php echo "ok";',
	'app/lib/util.php'     => '<?php // util
HTML,
	'app/assets/style.css' => 'body{margin:0}',
	'app/README.md'        => '# App',
) as $name => $body ) {
	$enc->append_file( new FileEntry( array(
		'path'               => $name,
		'compression_method' => ZipDecoder::COMPRESSION_DEFLATE,
		'body_reader'        => new MemoryPipe( $body ),
	) ) );
}
$enc->close();
$out->close_writing();

$zip = ZipFilesystem::create( FileReadStream::from_path( $path ) );
$mem = InMemoryFilesystem::create();
copy_between_filesystems( array(
	'source_filesystem' => $zip,
	'source_path'       => '/',
	'target_filesystem' => $mem,
	'target_path'       => '/',
) );

$mem->put_contents( '/app/VERSION', '1.0.0' );
echo "files now in memory:\n";
$dirs = array( '/' );
$files = array();
while ( $dirs ) {
	$dir = array_shift( $dirs );
	foreach ( $mem->ls( $dir ) as $name ) {
		$p = rtrim( $dir, '/' ) . '/' . $name;
		if ( $mem->is_dir( $p ) ) {
			$dirs[] = $p;
			continue;
		}
		$files[] = $p;
	}
}
sort( $files );
foreach ( $files as $path ) {
	echo "  " . $path . "\n";
}

When to use which type

Use	For
`ZipFilesystem::create()`	Reading. You want `get_contents()`, `ls()`, `is_dir()` over a ZIP. The most common case.
`ZipEncoder`	Writing. Stream entries into any `ByteWriteStream` sink. Required when format rules matter (EPUB, .docx).
`ZipDecoder`	Low-level read access to the central directory and individual entry headers. Most code reaches for `ZipFilesystem` instead.
`open_read_stream()` on a ZipFilesystem	Inflating a single large entry without buffering it whole in memory.
`copy_between_filesystems()`	Moving entries from a ZIP into another filesystem (memory, local, SQLite).

Pitfalls

E-readers reject EPUBs whose mimetype entry has compression. Use COMPRESSION_NONE for that single entry.

Never extract entry paths verbatim. Always run paths through ZipDecoder::sanitize_path(). Without it, a hostile archive can write outside the destination directory.

Zip

Read a file out of a ZIP

Build an EPUB from scratch

Stream a large entry without buffering it

Repack: modify one file, copy the rest

Defend against zip-slip

Pipe ZIP entries into an InMemoryFilesystem

When to use which type

Pitfalls

See also